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 environment variables injected at provisioning time.

Workspace naming

A workspace name is always the name of the pod the workspace runs in. In the standalone model the pod is created by the provisioner and its name equals the workspace canonical ID (e.g. alice-a3b5c7d). In the injection model the workspace runs inside a pod owned by the target workload, so the workspace name is that pod's name (e.g. identity-6d7f9c8b4-xkpqr).

For how canonical IDs are derived from the user string, see Canonical ID.

Main configuration

k8shelld reads /etc/k8shell/config.yaml on startup. This file is mounted from a ConfigMap generated by the provisioner for each workspace.

system:
  logLevel: info
  pprof: false
  apiServer:
    enabled: true
    address: http://api-server.k8shell:9101
  grpc:
    # gRPC server configuration

identity:
  tokenPath: /run/secrets/identity-token/token
  publicKeyPath: /run/secrets/jwt-verifier/public.pem
  signingMethod: RS256

saToken:
  enabled: true
  cacheTokens: true

terminateOrphans:
  enabled: true
  checkInterval: 30
  exclude: []

reapZombies:
  enabled: true

shells:
  detachedTTL: 30m
  allowUnlimittedTTL: false
  allowSessionDetach: true

system

The system section controls logging and the two servers k8shelld exposes: the gRPC server and the internal REST server.

• logLevel — log verbosity: debug, info, warn, or error.
• pprof — enable the Go pprof endpoint. Useful for profiling in development environments.
• apiServer.enabled — whether k8shelld connects to the API Server. When enabled, credential helpers and user context calls are proxied through it.
• apiServer.address — address of the API Server.
• grpc — gRPC server configuration, including TLS and listen address.

identity

k8shelld loads a JWT at startup that identifies the workspace user — carrying username, UID, GID, and email. This token is issued by the Identity service and mounted as a secret. It is verified on load and on each renewal.

• tokenPath — path to the JWT token file.
• publicKeyPath — path to the public key used to verify the token signature.
• signingMethod — JWT signing algorithm, e.g. RS256.

saToken

The saToken section configures the Kubernetes credential helper that retrieves service account tokens via the API server for Kubernetes API access.

• enabled — whether the service account token credential helper is active.
• cacheTokens — whether retrieved tokens are cached to avoid redundant API server calls.

terminateOrphans and reapZombies

These settings control k8shelld's process management behaviour. See Process Management for a detailed explanation of how orphan cleanup and zombie reaping work.

• terminateOrphans.enabled — enable the orphan process scanner.
• terminateOrphans.checkInterval — how often (in seconds) to scan for re-parented processes.
• terminateOrphans.exclude — process names to leave alone, even if re-parented to PID 1.
• reapZombies.enabled — enable zombie reaping on SIGCHLD.

shells

The shells section configures PTY shell session behavior and lifecycle management.

• detachedTTL — how long a PTY shell session with no attached client is kept alive before automatic termination. Accepts Go duration strings (e.g., 30m, 1h). Set to 0s to disable automatic termination.
• allowUnlimittedTTL — whether clients are allowed to set an unlimited TTL for detached sessions.
• allowSessionDetach — whether clients are allowed to detach from PTY shell sessions.

Security context

The blueprint can specify a Kubernetes SecurityContext for the main workspace container and the Podman sidecar. This allows fine-grained control over security settings like capabilities, user/group IDs, and privilege escalation.

Main container

The main container does not require full privileged mode (privileged: true). It must run as root (UID/GID 0) because k8shelld runs as PID 1 and performs operations that require root privileges: creating users, and setting up the workspace environment during bootstrap.

The following constraints are enforced:

• runAsUser: 0
• runAsGroup: 0
• runAsNonRoot: true
• readOnlyRootFilesystem: true
• allowPrivilegeEscalation: true

note

Although PID 1 runs under root with required root privileges, allowPrivilegeEscalation is required when the workspace user needs sudo access.

Capabilities: k8shelld requires the following Linux capabilities and will fail when they are not present:

• CHOWN — changing file ownership during user setup
• SETGID — setting group ID for the workspace user
• SETUID — setting user ID for the workspace user

If you specify drop: [ALL] in the capabilities block, you must explicitly re-add then in the add list.

Podman sidecar

The Podman sidecar runs with a non-privileged security context by default. Custom security contexts can be specified for fine-tuning alongside the Podman image version. See Podman Sidecar for details on how Podman operates securely in rootless mode.

Workspace files and directories

The provisioner mounts the following files and directories into the main container:

Path	Description
/etc/k8shell/config.yaml	k8shelld runtime configuration (see above).
/etc/k8shell/blueprint.yaml	The blueprint used to provision this workspace.
/etc/tls/k8shelld	TLS certificate and key for the gRPC server (cert-manager only).
/usr/local/bin/k8shelld	In-workspace daemon binary, injected by the init container.
/usr/local/bin/kbox	In-workspace CLI binary, injected by the init container.
/usr/local/k8shell/system	System tool wrapper scripts and user-defined init scripts from the blueprint.
/run/secrets/identity-token	Workspace identity JWT, issued by the Identity service.
/run/secrets/jwt-verifier	Public key used by k8shelld to verify the identity token.
/var/run/podman	Shared directory with the Podman sidecar containing podman.sock.
Blueprint storage paths	Each storage from the blueprint is mounted at its configured path.
Blueprint extFiles paths	Extra files from the blueprint are mounted at their configured paths.

Environment variables

Variable	Description
WORKSPACE	Workspace name.
BLUEPRINT	Blueprint name.
IMAGE	Main container image.
USERNAME	Workspace user's username.
USEREMAIL	Workspace user's email address.
USERFULLNAME	Workspace user's display name.

Additional variables can be defined in the blueprint under env and are merged with the above.