# k8Shell Documentation > k8Shell is a Kubernetes-native platform for provisioning and accessing workspaces over SSH, browser Console, or API. This file is auto-generated from the documentation source. For the full rendered site see https://docs.k8shell.io ## General - [Welcome](https://docs.k8shell.io/): "@context": "https://schema.org", "@graph": [ { "@type": "SoftwareApplication", "name": "k8shell", "url": "https://k8shell. - [Introduction](https://docs.k8shell.io/introduction): k8shell is a platform built around a simple idea: developer workspaces run in Kubernetes. - [Licensing](https://docs.k8shell.io/licensing): k8shell core services are licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). - [Releases](https://docs.k8shell.io/releases): All k8shell releases are published to GitHub Container Registry (ghcr.io). - [Support](https://docs.k8shell.io/support): Reach out if you've hit a bug, have a feature idea, or need direct help as an Early Access user. - [Roadmap](https://docs.k8shell.io/roadmap): k8shell already covers a broad set of functionality - SSH-based workspace access, blueprint-driven provisioning, identity and credential management, session ... - [Comparison](https://docs.k8shell.io/comparison): Several platforms address parts of the cloud-native developer workflow — spanning Cloud Development Environments (CDEs), self-hosted workspace tooling, and A... - [docs.k8shell.io](https://docs.k8shell.io/README): This repository is the source for docs.k8shell.io. ## Installation - [k8shell Open Source](https://docs.k8shell.io/installation/k8shell-oss): The full k8shell platform adds API Server, Session, Console, SSH Shield, Worktrace, and more. - [Quick Start](https://docs.k8shell.io/installation/k8shell-oss/quickstart): Install k8shell OSS on any Kubernetes cluster in a few minutes using the quickstart script. ## Architecture - [API Server](https://docs.k8shell.io/architecture/api-server): The API Server is the REST API gateway for k8shell. It is the single entry point for the k8shell CLI, the browser-based Console, and any external automation ... - [Authorization Service](https://docs.k8shell.io/architecture/authz): The Authorization service is the central policy enforcement point for the platform. - [Identity Service](https://docs.k8shell.io/architecture/identity): The Identity service manages k8shell user identities across the platform. It integrates with downstream identity providers such as GitHub and GitLab, onboard... - [Overview](https://docs.k8shell.io/architecture/overview): K8shell provides developer access to Kubernetes-based workspaces via SSH, a browser-based console, or the REST API. - [Provisioner Service](https://docs.k8shell.io/architecture/provisioner): The Provisioner is the platform component responsible for the full lifecycle of a workspace in Kubernetes — from assembling its configuration to creating or ... - [Session Service](https://docs.k8shell.io/architecture/session): The Session Service is the central store for user session state in k8shell. It records every session opened through the SSH Proxy or the Console (via the API... - [SSH Proxy Service](https://docs.k8shell.io/architecture/ssh-proxy): SSH Proxy provides an SSH protocol interface for SSH-compliant clients, authenticates and authorizes users using identity providers, provisions workspaces fo... - [SSH Shield](https://docs.k8shell.io/architecture/ssh-shield): SSH Shield protects the k8shell SSH entry point from brute-force attacks and automated credential-stuffing bots. - [Workspace](https://docs.k8shell.io/architecture/workspace): At the core of every workspace is the k8shelld process, which runs as PID 1 inside the main workspace container. - [Worktrace](https://docs.k8shell.io/architecture/worktrace): Worktrace is a real-time threat detection system that identifies malicious activity in interactive Kubernetes workspaces. - [Authentication](https://docs.k8shell.io/architecture/api-server/authentication): The API Server authenticates every inbound HTTP request before routing it to a backend service. Requests follow one of two paths depending on the client type. - [Blueprint](https://docs.k8shell.io/architecture/provisioner/blueprint): A blueprint is the configuration template from which workspaces are provisioned. It describes everything the Provisioner needs to create a workspace: the con... - [Deployment Models](https://docs.k8shell.io/architecture/workspace/deployment-models): A workspace can run in two different configurations, each offering different runtime capabilities to the user. - [IP Blocking](https://docs.k8shell.io/architecture/ssh-shield/blocking): SSH Shield detects malicious IPs from the failed authentication event stream and evaluates them against the detection mechanisms described in this page. - [Session Store](https://docs.k8shell.io/architecture/session/session-store): All session state is persisted in PostgreSQL under the session schema. Every session opened via the SSH Proxy or the Console is written to the session. - [Access](https://docs.k8shell.io/architecture/api-server/access): The API Server is exposed through a Kubernetes Ingress that handles two hostnames. The base hostname (e.g. app.k8shell.dev) serves all standard API traffic. - [Blueprint](https://docs.k8shell.io/architecture/overview/blueprint): A blueprint is the configuration template from which workspaces are provisioned. It describes everything the Provisioner needs to create a workspace pod: the... - [Blueprint Manager](https://docs.k8shell.io/architecture/provisioner/blueprint-manager): Platform blueprints are stored as YAML files in a directory on the Provisioner's filesystem. - [Configuration](https://docs.k8shell.io/architecture/ssh-shield/configuration): SSH Shield is configured via a YAML file. The path is passed as a command-line argument at startup. - [Configuration](https://docs.k8shell.io/architecture/workspace/configuration): A workspace pod is configured through a combination of a runtime configuration file read by k8shelld, files and secrets mounted into the container, and envir... - [Detection Rules](https://docs.k8shell.io/architecture/worktrace/detection-rules): Detection rules are the primary mechanism for identifying known attack signatures. - [Identity Providers](https://docs.k8shell.io/architecture/identity/providers): Identity providers (IdPs) are the external systems that hold the authoritative source of user information — GitHub, GitLab, a corporate directory, or any oth... - [Policy Domains](https://docs.k8shell.io/architecture/authz/policy-domains): Policies are organized into domains — logical groupings of related enforcement contracts. - [Protocol Support](https://docs.k8shell.io/architecture/ssh-proxy/protocol-support): SSH Proxy uses the SSH-2 protocol suite for client connections and optionally the PROXY protocol to preserve the original client IP when running behind a loa... - [Recording](https://docs.k8shell.io/architecture/session/recording): The Session Service can record the content of SSH sessions to disk for audit and replay purposes. - [API Reference](https://docs.k8shell.io/architecture/api-server/api): The API Server exposes a REST API over HTTP. All endpoints are versioned under /api/v1. The browser-based Console and CLI are the primary callers. - [Attack Paths](https://docs.k8shell.io/architecture/worktrace/attack-paths): Many real-world attacks consist of a sequence of steps, each individually ambiguous but collectively unambiguous when observed together. - [Comminication Flows](https://docs.k8shell.io/architecture/ssh-proxy/communication-flows): This document describes the flow between SSH Client, SSH Proxy, Identity, Provisioner, and k8shelld. - [Configuration](https://docs.k8shell.io/architecture/session/configuration): The Session Service is configured via a YAML file. The path is passed as a command-line argument at startup. - [Init and Bootstrap](https://docs.k8shell.io/architecture/workspace/init-bootstrap): A workspace pod starts through two sequential phases: an init phase that injects tooling into the container filesystem, and a bootstrap phase where k8shelld ... - [nfgate](https://docs.k8shell.io/architecture/ssh-shield/nfgate): nfgate is a lightweight gRPC daemon that manages nftables firewall rules on a Linux host. - [Standalone Pod](https://docs.k8shell.io/architecture/provisioner/standalone-pod): In the standalone model the Provisioner provisions the workspace by running helm install with the k8shell-workspace chart against the resolved blueprint. - [User Domain](https://docs.k8shell.io/architecture/authz/domain-user): The user domain covers identity lifecycle decisions — who may be admitted to the platform, how they authenticate, what user data they can read, and who may c... - [User Management](https://docs.k8shell.io/architecture/identity/user-management): Identity manages the full lifecycle of a k8shell user — admitting new users via OAuth flows, keeping their profiles in sync with upstream identity providers,... - [Workspace](https://docs.k8shell.io/architecture/overview/workspace): A workspace is an isolated Linux environment provisioned for a specific user according to a blueprint. - [Behavioral Detection](https://docs.k8shell.io/architecture/worktrace/behavioral-detection): The behavioral pipeline provides anomaly detection as a complement to the rule-based approach. - [Configuration](https://docs.k8shell.io/architecture/api-server/configuration): The API Server is configured via a YAML file. The path to the file is passed as a command-line argument at startup. - [IP Address Protection](https://docs.k8shell.io/architecture/ssh-proxy/ip-protection): The SSH Proxy runs as multiple instances within the Kubernetes cluster. Each instance listens on a TCP port exposed externally as tcp/22 through a LoadBalanc... - [SSH Domain](https://docs.k8shell.io/architecture/authz/domain-ssh): The SSH domain controls individual SSH channel types and requests. Each contract maps to a distinct SSH operation — interactive shell, command execution, fil... - [Tokens](https://docs.k8shell.io/architecture/identity/tokens): k8Shell uses two types of tokens: JWTs issued by the Identity service for authenticated sessions, and Personal Access Tokens (PATs) for long-lived programmat... - [User String](https://docs.k8shell.io/architecture/overview/user-string): The User String (USERSTR) is the user portion of the SSH connection string—the substring before the @ delimiter. - [Workload Injection](https://docs.k8shell.io/architecture/provisioner/workload-injection): In the injection model the Provisioner patches a running workload — a Deployment, StatefulSet, or DaemonSet — rather than creating a new pod. - [Credential Helpers](https://docs.k8shell.io/architecture/identity/credential-helpers): Identity acts as the credential helper backend for workspaces. When a tool running inside a workspace needs to authenticate against an external service — a G... - [Provisioning Flow](https://docs.k8shell.io/architecture/provisioner/provisioning-flow): The Provisioner handles two request types: provisioning a workspace and deleting one. - [Security](https://docs.k8shell.io/architecture/overview/security): Security is a first-class concern in k8shell. The platform is built for environments where multiple teams share the same cluster, and applies zero-trust prin... - [Session Domain](https://docs.k8shell.io/architecture/authz/domain-session): The session domain controls whether a session may be established and, if so, what recording obligations apply to it. - [Access](https://docs.k8shell.io/architecture/workspace/access): Workspace access encompasses both network connectivity and Kubernetes API access. Network policies control traffic between workspace pods and other endpoints... - [Configuration](https://docs.k8shell.io/architecture/identity/configuration): This page covers two areas of Identity configuration: the main configuration file used to run the service, and the Kubernetes RBAC roles required for Identit... - [Configuration](https://docs.k8shell.io/architecture/provisioner/configuration): This page covers two areas of Provisioner configuration: the main configuration file the Provisioner uses to perform its operations, and the Kubernetes RBAC ... - [Process Management](https://docs.k8shell.io/architecture/workspace/process-management): k8shelld runs as PID 1 inside the main workspace container and takes on two process management responsibilities: reaping zombie processes and terminating orp... - [Workspace Domain](https://docs.k8shell.io/architecture/authz/domain-workspace): The workspace domain controls the full workspace lifecycle — who can provision, create, list, read, delete, and connect to workspaces — as well as fine-grain... - [API Reference](https://docs.k8shell.io/architecture/identity/api): Identity exposes two gRPC services. IdentityService is the public-facing API consumed by the rest of the k8shell platform. - [API Reference](https://docs.k8shell.io/architecture/provisioner/api): The Provisioner exposes a single gRPC service (provisioner.v1.ProvisionerService) that manages the full lifecycle of user workspaces. - [App Manager](https://docs.k8shell.io/architecture/workspace/apps): The app manager is a component of k8shelld that installs, starts, and supervises long-running processes inside the workspace. - [Podman Sidecar](https://docs.k8shell.io/architecture/workspace/podman-sidecar): The Podman sidecar is an optional second container in the workspace pod that runs a rootless Podman daemon alongside the main workspace container. - [Storage](https://docs.k8shell.io/architecture/workspace/storage): Workspace storage mounts PersistentVolumeClaims at specified paths inside the workspace container. - [API Reference](https://docs.k8shell.io/architecture/workspace/api): k8shelld exposes two APIs: an external gRPC API used by other k8shell services over the network, and an internal REST API over a Unix socket used by in-works... ## Configuration - [Basic Configuration](https://docs.k8shell.io/configuration/basic-configuration): This section covers the essential configuration steps after a k8shell installation. They apply to both k8shell OSS and full k8shell Platform deployments. - [Helm Charts](https://docs.k8shell.io/configuration/helm-charts): k8shell platform is distributed via two main Helm charts. - [Exposing SSH Proxy](https://docs.k8shell.io/configuration/basic-configuration/exposing-ssh-proxy): SSH Proxy is the sole external entry point for all user connections into k8shell. Exposing it correctly is the most infrastructure-specific part of any deplo... - [k8shell Chart](https://docs.k8shell.io/configuration/helm-charts/k8shell-chart): The k8shell Helm chart is the base deployment for k8shell. It includes default configuration for all services and acts as the foundation for any k8shell inst... - [Adding Users](https://docs.k8shell.io/configuration/basic-configuration/adding-users): Users can be provisioned directly by the k8shell chart by specifying them under the users key in values.yaml. - [k8shell Bundle Chart](https://docs.k8shell.io/configuration/helm-charts/k8shell-bundle-chart): The k8shell-bundle chart is an umbrella chart that wraps the k8shell chart and adds production-ready supporting infrastructure in a single deployment. - [Adding Blueprints](https://docs.k8shell.io/configuration/basic-configuration/adding-blueprints): Blueprints define how workspaces are created — which container image to use, what resources to allocate, which init scripts to run, and more. - [GitHub IdP Chart](https://docs.k8shell.io/configuration/helm-charts/idp-github-chart): The idp-github Helm chart deploys the GitHub identity provider service, which allows users to authenticate to k8shell using their GitHub credentials. - [Container Images](https://docs.k8shell.io/configuration/basic-configuration/container-images): A blueprint's image field accepts any OCI-compatible container image. The workspace runs as that image, so its available tooling is entirely determined by wh... - [GitLab IdP Chart](https://docs.k8shell.io/configuration/helm-charts/idp-gitlab-chart): The idp-gitlab Helm chart deploys the GitLab identity provider service, which allows users to authenticate to k8shell using their GitLab credentials. - [Configuring Storage](https://docs.k8shell.io/configuration/basic-configuration/configuring-storage): Workspace storage is backed by Kubernetes PersistentVolumeClaims. The available storage options depend entirely on the CSI drivers installed in your cluster ... - [SSH Shield Chart](https://docs.k8shell.io/configuration/helm-charts/ssh-shield-chart): The ssh-shield Helm chart deploys the SSH Shield service, which protects the k8shell SSH entry point from brute-force attacks by monitoring authentication fa... - [Vault Secrets Chart](https://docs.k8shell.io/configuration/helm-charts/vault-secrets-chart): The vault-secrets chart is a lightweight utility chart for defining Kubernetes Secrets whose values are pulled from HashiCorp Vault. - [Configuring Podman](https://docs.k8shell.io/configuration/basic-configuration/configuring-podman): The Podman sidecar is an optional second container added to the workspace pod alongside the main workspace container. - [Common Fields](https://docs.k8shell.io/configuration/helm-charts/common-fields): The following sections describe parameters that appear across multiple k8shell Helm charts. ## Releases - [Release v26.6.4](https://docs.k8shell.io/releases/26.6.4): Released on 2026-06-26. ## User-guide - [Console](https://docs.k8shell.io/user-guide/console): The Console is the browser-based interface for managing workspaces, accessing applications, and running terminals — all without installing any local tools. - [k8shell CLI](https://docs.k8shell.io/user-guide/k8shell-cli): The k8shell CLI is the primary command-line tool for interacting with a k8shell api-server. - [kbox CLI](https://docs.k8shell.io/user-guide/kbox-cli): kbox is the in-workspace command-line interface. It communicates exclusively with k8shelld, the in-workspace daemon, through the Internal API — a REST API se... - [SSH](https://docs.k8shell.io/user-guide/ssh): K8shell exposes workspaces over standard SSH-2, meaning any RFC-compliant SSH client works without additional software. - [SSH and Exec](https://docs.k8shell.io/user-guide/ssh/ssh-exec): Connecting without any command starts a PTY shell session: - [User Guide](https://docs.k8shell.io/user-guide/overview): k8shell can be accessed through several user-facing tools, each suited to a different workflow. - [Forwarding](https://docs.k8shell.io/user-guide/ssh/forwarding): Forward your local SSH agent into the workspace so that keys stored locally are available for git operations, nested SSH connections, and other agent-aware t... - [Status and Info](https://docs.k8shell.io/user-guide/kbox-cli/status): kbox info displays a summary of workspace state, resource usage, and storage. It queries the /sysinfo endpoint and formats the response into labelled groups. - [File Transfer](https://docs.k8shell.io/user-guide/ssh/files): The workspace exposes the SFTP subsystem over SSH. Connect with any SFTP client: - [Sessions](https://docs.k8shell.io/user-guide/kbox-cli/sessions): kbox streams lists all active and recent streams created by incoming connections from the SSH Proxy or API Server. - [Workspaces](https://docs.k8shell.io/user-guide/console/workspaces): A workspace is an isolated cloud development environment provisioned for a specific user. - [VS Code Remote – SSH](https://docs.k8shell.io/user-guide/ssh/vscode): k8shell workspace code launches VS Code with the Remote – SSH extension connected to a workspace: - [Workspace Lifecycle](https://docs.k8shell.io/user-guide/kbox-cli/lifecycle): kbox shutdown stops the workspace from inside. - [Identity and Credentials](https://docs.k8shell.io/user-guide/kbox-cli/identity): kbox identity displays the JWT identity claims associated with the current workspace session. - [Apps](https://docs.k8shell.io/user-guide/kbox-cli/apps): Workspace apps are long-running processes defined in the blueprint and managed by k8shelld's app manager. - [Users and Sessions](https://docs.k8shell.io/user-guide/k8shell-cli/user): The user command (alias usr) lets you view users registered in k8shell. What you see depends on your role: regular users typically see only themselves, while... - [Workspaces](https://docs.k8shell.io/user-guide/k8shell-cli/workspace): The workspace command (alias ws) lets you create, inspect, and shut down workspaces.