Workspaces
The workspace command (alias ws) lets you create, inspect, and shut down workspaces.
Listing workspaces
# list your own workspaces
k8shell workspace list
# list all workspaces (requires admin privileges)
k8shell workspace list --all
# filter by owner
k8shell workspace list --user alice
| Column | Description |
|---|---|
| NAME | Workspace name. |
| USERNAME | Owner username. |
| STATUS | Current pod status: Starting, Running, Stopped, etc. |
| ORIGIN | Source repo as owner/name, or the blueprint name when no repo is set. |
| CPU | CPU resource limit (e.g. 500m). |
| MEMORY | Memory resource limit (e.g. 512Mi). |
| VERSION | App version running in the workspace. |
| IP | Pod IP address. |
| CREATED | Creation timestamp (local time). |
Use --sort to order by any column, for example --sort -created for newest first.
Creating a workspace
Workspaces are created from a blueprint, optionally pinned to a specific repository and ref:
# create from a blueprint
k8shell workspace create --blueprint default
# create from a repo (branch defaults to the repo's default branch)
k8shell workspace create --repo my-org/my-repo
# create on behalf of another user (admin only)
k8shell workspace create --blueprint default --username alice
When --repo is given without an owner, the owner defaults to your username. The CLI shows a progress indicator during startup; pass --events to stream Kubernetes events instead:
$ k8shell ws create --repo k8shell-io/charts --events
Creating workspace john-37abff3 (job e84cca96-4a4c-4301-b4dc-aa4f1f87c8ed)
[2026-06-22 06:15:43] [john-37abff3] Starting: Waiting for node assignment
[2026-06-22 06:15:43] [john-37abff3] Starting: Waiting for containers to start
[2026-06-22 06:15:43] [john-37abff3] Starting: init-base: PodInitializing
[2026-06-22 06:15:44] [Pod/john-37abff3] Pulled: Container image "registry.k8shell.io/k8shell-base/k8shelld:pr-64-57f3ce0" already present on machine
[2026-06-22 06:15:44] [Pod/john-37abff3] Created: Created container: init-base
[2026-06-22 06:15:44] [Pod/john-37abff3] Started: Started container init-base
[2026-06-22 06:15:45] [Pod/john-37abff3] Pulled: Container image "registry.k8shell.io/workspaces/dev:1.13" already present on machine
[2026-06-22 06:15:45] [john-37abff3] Starting: k8shell-main: PodInitializing
[2026-06-22 06:15:45] [Pod/john-37abff3] Created: Created container: k8shell-main
[2026-06-22 06:15:45] [Pod/john-37abff3] Started: Started container k8shell-main
[2026-06-22 06:15:45] [Pod/john-37abff3] Pulled: Container image "quay.io/podman/stable:v5.8.1" already present on machine
[2026-06-22 06:15:45] [Pod/john-37abff3] Created: Created container: k8shell-podman
[2026-06-22 06:15:45] [Pod/john-37abff3] Started: Started container k8shell-podman
[2026-06-22 06:15:46] [john-37abff3] Running: Workspace is ready, provisioned in 3s
Events are Kubernetes events emitted as workspace resources are created and containers start. The provisioner writes them to the KV store during provisioning (see job tracking); they can be retrieved after the fact via workspace job-events, subject to the KV storage retention policy.
Shutting down a workspace
# stop a workspace (keeps workspace data)
k8shell workspace shutdown my-workspace
# permanently delete workspace data
k8shell workspace shutdown my-workspace --delete
Connecting via SSH
k8shell workspace ssh opens an SSH session to a running workspace. Identify the workspace with either --pod (workspace name) or --repo (repository in owner/name format):
# connect by workspace name
k8shell workspace ssh --pod my-workspace
# connect by repository
k8shell workspace ssh --repo my-org/my-repo
# pass extra flags to ssh (after --)
k8shell workspace ssh --pod my-workspace -- -L 8080:localhost:8080
# print the connection string without connecting
k8shell workspace ssh --pod my-workspace --print
Use --no-lookup to skip the workspace API call and derive the server from the context URL directly — useful if the API is unavailable. --b64 base64-encodes the userstring in the connection string.
Opening in VS Code
k8shell workspace code launches VS Code with the Remote - SSH extension connected to a workspace:
# open by workspace name
k8shell workspace code --pod my-workspace
# open to a specific folder
k8shell workspace code --pod my-workspace --path /home/user/project
# open by repository (optionally pin to a ref)
k8shell workspace code --repo my-org/my-repo --ref main
# print the remote URI instead of launching VS Code
k8shell workspace code --pod my-workspace --print
The userstring in the remote URI is always base64-encoded because VS Code does not accept raw userstrings in remote URIs.
Copying files with SCP
k8shell workspace scp copies files from a workspace to your local machine:
# copy from workspace root to current directory
k8shell workspace scp --pod my-workspace
# copy from a specific remote path to a local directory
k8shell workspace scp --pod my-workspace --path /home/user/data ./local-data
# copy by repository
k8shell workspace scp --repo my-org/my-repo --path /output
# print the SCP string without running it
k8shell workspace scp --pod my-workspace --print
The optional positional argument sets the local destination (default: .). Use --b64 to base64-encode the userstring in the SCP string.
Streaming job events
During or after workspace creation, you can stream the underlying Kubernetes job events:
k8shell workspace job-events my-workspace
This is useful for diagnosing slow or failed workspace startups.