K8e Sandbox

/k8e-sandbox

Treat this as the k8e-sandbox skill command.

Invocation (same skill, different harness prefixes):

• Claude Code: /k8e-sandbox <goal>
• Codex: $k8e-sandbox <goal> (or pick from /skills)
• Pi: /skill:k8e-sandbox <goal> (or /k8e-sandbox when skill commands are enabled)
• dsh (DeepSeek Harness): the model loads this skill via the skill tool (catalog name k8e-sandbox), or the user names it directly in chat — see dsh execution path below

Goal from invocation arguments:

$ARGUMENTS

If $ARGUMENTS is empty and no goal is otherwise provided, ask the user for a sandbox goal and stop (do not invent work).

What this skill can do (capability map)

Match the goal to a capability, then use the matching command. Exact flags live in the command reference.

dsh (DeepSeek Harness) execution path

In dsh, decide your execution mode by checking the current session's tool list first — everything else in this skill branches on it.

A. Plugin mounted — k8e_sandbox_session_status IS in your tool list

The dsh-k8e-sandbox plugin replaced the harness's execution seams:

• bash (subprocess seam) → runs inside the sandbox pod
• read / write / edit / dir listings (fs seam) → sandbox /workspace
• k8e_sandbox_* tools → session lifecycle, expose, egress allowlist

Rules:

1. Do NOT run k8e-sandbox-cli here: it is not present inside the sandbox, and invoking it from the sandboxed bash would recursively dial the gateway from inside the pod. Use the tools + sandboxed seams instead.
2. Prefer plain bash for commands — it lands in the sandbox. Use k8e_sandbox_exec when you want structured stdout/stderr/exitCode, and k8e_sandbox_run_background + k8e_sandbox_poll for long/streaming tasks.
3. First action in a session: k8e_sandbox_session_status — it lazily creates the session shared by fs/subprocess/exec, and reports available, sessionId, tenantId.

Tool reference (exact argument shapes — do not guess):

Service exposure in dsh: after starting a long-running service with k8e_sandbox_run_background, call k8e_sandbox_expose {port: 8080} and hand the returned URL to the user — same gateway-proxied URL the CLI's expose prints. Teardown with k8e_sandbox_unexpose {port: 8080}. These runs are not time-capped, so the service stays reachable until the session is destroyed.

Session, connection, and mTLS are owned by the plugin: it resolves the gateway from config → env → ~/.k8e/sandbox/profiles.yaml (KIP-17) and reuses one persistent gRPC connection. If a tool errors with gateway unreachable / mTLS / deadline, tell the user to run k8e-sandbox-cli connect (local) or k8e-sandbox-cli connect --endpoint <host>:50051 --apikey <key> (remote) outside dsh, then restart the dsh session.

B. Plugin NOT mounted — k8e_sandbox_* tools are NOT in your tool list

The plugin bundle is not installed for this dsh profile. dsh's bash still runs on the HOST here (no seam replacement), so the CLI-first flow below works normally: execute everything via k8e-sandbox-cli run ... exactly as the CLI examples describe. Do not pretend the k8e_sandbox_* tools exist — calling a nonexistent tool errors.

To enable the full plugin experience, ask the user to install the bundle once (from a k8e checkout), then restart dsh:

dsh plugin --profile <name> add <k8e>/plugins/deepseek-harness/packages/dsh-k8e-sandbox-bundle
dsh --profile <name>          # restart the session

dsh error quick reference

The CLI-first flow below (k8e-sandbox-cli run ...) is for harnesses where the sandbox is not mounted (Claude Code / Codex / Pi / dsh without the plugin).

Binary naming (read this first)

The downloaded file name carries a platform suffix — pick the one for the user's machine:

It is the same binary this skill invokes as k8e-sandbox-cli — just under the platform-suffixed name. To make the plain name work without renaming, create a symlink (do not rename the file):

# Example for Linux amd64 — substitute the platform name for other OS/arch
curl -sLO https://github.com/xiaods/k8e/releases/latest/download/k8e-sandbox-cli-linux-amd64
chmod +x k8e-sandbox-cli-linux-amd64
ln -s k8e-sandbox-cli-linux-amd64 k8e-sandbox-cli          # symlink, original file stays
# optionally move both into a PATH dir, e.g. ~/.local/bin/
./k8e-sandbox-cli ... connect                             # connect installs this skill + ensures PATH

(Windows: use mklink k8e-sandbox-cli.exe k8e-sandbox-cli-windows-amd64.exe in cmd.)

From then on, this skill and all examples use the plain name k8e-sandbox-cli — same binary.

If you only see a platform-suffixed name in the user's environment (no symlink yet), use that file directly: ./k8e-sandbox-cli-linux-amd64 status etc. All spellings are interchangeable; never tell the user they are missing a second binary.

Hard rules

1. All code and shell execution goes through k8e-sandbox-cli — never run python3, node, pip, npm, curl, compilers, or tests on the host for this goal.
2. Prefer auto session mode: k8e-sandbox-cli run "..." (creates/reuses session).
3. Parse JSON with jq unless --raw is used.
4. If the gateway is unreachable, tell the user to run k8e-sandbox-cli connect (local) or k8e-sandbox-cli connect --endpoint <host>:50051 --apikey <key> (remote). Multi-cluster: --profile <name> / ~/.k8e/sandbox/profiles.yaml (KIP-17).

Auth & multi-profile (KIP-14 / KIP-17 / #538)

Do not confuse these files:

mTLS bootstrap: first remote connect/login uses an API key once; CLI stores ca.crt + client.crt + client.key (private key never leaves the machine). Client certs last 90 days and auto-renew when <30 days remain. API keys default to 30-day TTL (k8e sandbox-apikey create name, override with --ttl 90d|never).

First authentication verifies the gateway using system trust, a cached CA, or an administrator-provided --ca-file /path/to/sandbox-ca.crt on connect/login. Obtain that CA through a trusted channel. Private-CA gateways require the CA on first use. --insecure-bootstrap explicitly bypasses server verification only when no CA is selected; this exposes the API key to server impersonation and must not be the default recovery step. login always authenticates the supplied API key, even with valid cached credentials. Concurrent CLI processes serialize credential initialization and renewal.

Profiles (~/.k8e/sandbox/profiles.yaml, override with K8E_SANDBOX_CONFIG):

# ~/.k8e/sandbox/profiles.yaml  — NOT /etc/k8e/config.yaml
version: 1
current_profile: default
profiles:
  default:
    endpoint: 10.0.0.1:50051
  prod:
    endpoint: sandbox.prod.example:50051
    cert_dir: ~/.k8e/sandbox-prod
    device_name: laptop-prod

k8e-sandbox-cli --profile prod connect --apikey <64-hex key>
k8e-sandbox-cli --profile prod run 'echo hi'
# or: export K8E_SANDBOX_PROFILE=prod

Priority: flags → env → profile → last-connect fallback (~/.k8e/sandbox/config.json) → defaults. Flag/env pairs: --endpoint/K8E_SANDBOX_ENDPOINT, --apikey/K8E_SANDBOX_APIKEY, --profile/K8E_SANDBOX_PROFILE. The cert dir has no flag: K8E_SANDBOX_CERT_DIR → profile cert_dir → ~/.k8e/sandbox. Other env: K8E_SANDBOX_SESSION_ID, K8E_SANDBOX_TENANT, K8E_SANDBOX_DEVICE_NAME, K8E_SANDBOX_CONFIG (profile file path).

Procedure (always)

1. Pre-flight

command -v k8e-sandbox-cli >/dev/null || { echo "k8e-sandbox-cli not on PATH; run connect again"; exit 1; }
k8e-sandbox-cli status

Require "available": true. If not available, stop and instruct the user to connect.

2. Plan

Decompose $ARGUMENTS into sandbox-safe steps (install deps → write files → run code → read outputs).

3. Execute (examples)

# Shell / bash (default)
k8e-sandbox-cli run 'echo hello'

# Python
k8e-sandbox-cli run "print(1+1)" --lang python

# Multi-line / files
k8e-sandbox-cli run 'pip install pandas' --lang bash
# write via stdin:
# cat analysis.py | k8e-sandbox-cli write <session_id> /workspace/analysis.py
# k8e-sandbox-cli run 'python3 /workspace/analysis.py' --session-id <session_id>
# push/pull local files (chunked streaming — constant memory, binary-safe,
# works for files of any size; prefer over write/read for real files):
# k8e-sandbox-cli push <session_id> ./analysis.py /workspace/analysis.py
# k8e-sandbox-cli pull <session_id> /workspace/results.csv ./results.csv

# Background exec (returns run_id immediately).
# A background run has NO lifetime cap by default. `--timeout N` caps it and
# the daemon SIGKILLs the run (whole process group) when N expires — only pass
# it for work you want bounded.
k8e-sandbox-cli run 'sleep 30; echo done' --background
k8e-sandbox-cli poll <run-id>            # wait + stream output

# Tenant reuse (share one session across CLI calls)
k8e-sandbox-cli run 'echo hi' --tenant my-project

# Sub-agent: child session sharing parent pod + workspace (no new pod)
k8e-sandbox-cli subagent <parent-sid>

# Expose a long-running service through the k8e API Gateway (KIP-24).
# No --timeout here: a cap would kill the server while you are still testing it.
k8e-sandbox-cli run "python3 -m http.server 8080 --bind 127.0.0.1" --background
k8e-sandbox-cli expose 8080     # -> {"url":"http://<gateway>/k8e/expose/<sid>/8080/",...}

Useful commands: run, write, read, list, push, pull, create, get, sessions, destroy, status, log, events, ps, poll, subagent, confirm, approve, snapshot, benchmark, catalog, expose, unexpose, exposed, allow-hosts, doctor, login, mcp-serve.

4. Report

Show stdout/stderr and exit codes from the CLI JSON. Do not claim host-side execution.