k8e-sandbox-skill

name: k8e-sandbox-skill description: K8E sandbox skill — execute code and shell commands in gVisor/Kata/Firecracker-isolated pods. All code execution must go through the sandbox, never on the host. Trigger when user asks to run, execute, test, try, install, analyze code or data files. user-invocable: true

K8E Sandbox

All code execution goes through k8e-sandbox-cli — never run code directly on the host. Each session is a gVisor/Kata/Firecracker-isolated pod with kernel-level egress enforcement. Mistakes can't damage the host.

Trigger keywords (English): "run this", "execute", "test it", "install X", "check if this works", "analyze this data"

Trigger keywords (中文): "帮我跑", "运行", "试试", "执行", "测试", "安装并使用", "分析这个CSV", "处理这个文件", "看看输出", "帮我算"

Pre-flight

Before any sandbox operation, check that the CLI is authenticated to the gateway:

# Local mode (on the K8E server) — auto-discovery, no login needed
# Remote mode — check for valid mTLS certificate
if ! k8e-sandbox-cli status 2>/dev/null | jq -e .available >/dev/null 2>&1; then
  echo "⚠ Sandbox not reachable. For remote access, log in first:"
  echo "  k8e-sandbox-cli login --endpoint <server-ip>:50051 --apikey <your-api-key>"
  exit 1
fi

If the sandbox is unreachable, ask the user:

"I need K8E sandbox access to run code securely. For a remote cluster, provide:

• The server address (e.g. <server-ip>:50051)
• Your API key (get it from the server: k8e sandbox-apikey create my-agent)

I'll run k8e-sandbox-cli login --endpoint <server-ip>:50051 --apikey <your-key> to set up mTLS credentials."

After a successful login, credentials are cached in ~/.k8e/sandbox/ (client.crt, client.key, ca.crt) and auto-renewed — no need to set environment variables per session.

mTLS Setup (remote access)

The sandbox gateway uses mTLS with dynamically-issued client certificates. First-time setup:

# Obtain a client certificate (valid 30 days, auto-renewed)
k8e-sandbox-cli login --endpoint <server-ip>:50051 --apikey k8e-abc123...

Credentials are cached in ~/.k8e/sandbox/ and auto-renew when expiring within 7 days. No API key env vars needed after the initial login.

If the server's IP/hostname changes, the cached CA cert will no longer match. Clear the cache and log in again:

rm -f ~/.k8e/sandbox/ca.crt ~/.k8e/sandbox/client.crt ~/.k8e/sandbox/client.key
k8e-sandbox-cli login --endpoint <new-ip>:50051 --apikey <your-key>

Environment

Download the platform-specific binary (~44MB) from GitHub Releases.

# Download and make executable
curl -sLO https://github.com/xiaods/k8e/releases/latest/download/k8e-sandbox-cli-linux-amd64
chmod +x k8e-sandbox-cli-linux-amd64

# On the K8E server node, auto-discovery works automatically
./k8e-sandbox-cli-linux-amd64 run "echo hello"

# From a remote client, log in once (obtains mTLS client certificate)
# (Get the API key from the server: k8e sandbox-apikey create my-agent)
./k8e-sandbox-cli-linux-amd64 login --endpoint <your-public-ip>:50051 --apikey k8e-abc123...

# After login, subsequent commands work without --apikey:
./k8e-sandbox-cli-linux-amd64 run "echo hello"

Command Reference

k8e-sandbox-cli run <code> [--lang python|bash|node|ts] [--session-id <id>] [--tenant <id>] [--timeout <seconds>] [--raw]

Code source: argument > stdin. Language default: bash.

Mode table

Session lifecycle

Auto-sessions persist across run calls within the same process. Use --tenant to persist across process restarts. Use manual mode when you need custom runtime or egress settings.

Egress rules

Default allowed hosts (kernel-level Cilium eBPF enforcement): pypi.org, files.pythonhosted.org, registry.npmjs.org, github.com, raw.githubusercontent.com

Override with --allowed-hosts on create. Everything else blocked.

Typical Scenarios

Scenario 1: Quick code execution (most common)

→ k8e-sandbox-cli run "print('hello')" --lang python
→ parse JSON output, display stdout to user

No session management needed. CLI auto-creates and reuses.

Scenario 2: Install package then use it

1. k8e-sandbox-cli run "pip install pandas" --lang bash
2. k8e-sandbox-cli run "python3 -c 'import pandas; print(pandas.__version__)'" --lang bash

Same auto-session reused across both calls.

Scenario 3: Write file, execute, read results

1. k8e-sandbox-cli write $SID /workspace/analyze.py <<'PYEOF'
   import pandas as pd
   df = pd.read_csv('/workspace/data.csv')
   print(df.describe())
   PYEOF

2. echo "name,value\na,1\nb,2" | k8e-sandbox-cli write $SID /workspace/data.csv

3. k8e-sandbox-cli run "python3 /workspace/analyze.py" --session-id $SID

4. k8e-sandbox-cli read $SID /workspace/result.json --raw | jq .

Scenario 4: Custom egress + explicit session

1. SID=$(k8e-sandbox-cli create --runtime gvisor --allowed-hosts pypi.org,api.example.com | jq -r .session_id)
2. k8e-sandbox-cli run "curl -s https://api.example.com/data" --session-id $SID
3. k8e-sandbox-cli destroy $SID

Scenario 5: Parallel sub-agents

1. SUB1=$(k8e-sandbox-cli subagent $PARENT | jq -r .session_id)
2. SUB2=$(k8e-sandbox-cli subagent $PARENT | jq -r .session_id)
3. k8e-sandbox-cli run "python3 task_a.py" --session-id $SUB1 --raw &
4. k8e-sandbox-cli run "python3 task_b.py" --session-id $SUB2 --raw &
5. wait

Sub-agents share parent /workspace PVC, communicate via files. Max depth 1.

Scenario 6: Human approval for destructive actions

1. k8e-sandbox-cli confirm $SID "delete /workspace/production-data"  →  blocks, outputs approval prompt to stderr
2. Show the stderr output to user — they copy the approve command
3. Command returns {"approved": true} on success

For non-blocking registration: add --no-wait, get approval_id, call k8e-sandbox-cli approve $AID later.

Scenario 7: Workspace snapshot save/restore

# Save current workspace
k8e-sandbox-cli snapshot save $SID my-analysis

# Later, restore from snapshot into a new session
SID=$(k8e-sandbox-cli snapshot restore my-analysis | jq -r .session_id)
k8e-sandbox-cli read $SID /workspace/result.json --raw

Error reference

JSON error output format:

{"error":"description","detail":"specific cause"}
{"ok":false,"error":"reason"}

Isolated runtimes

Use --runtime firecracker only when /dev/kvm is available. gVisor is the recommended default — no KVM required.

Your role

Do:

• Run ALL code through k8e-sandbox-cli run, never on host
• Use --lang python for .py code, --lang bash for shell commands
• Use --raw for long-running output (training, streaming)
• Use jq to parse JSON output: k8e-sandbox-cli run "..." | jq -r .stdout
• Auto-manage sessions (default mode) unless custom settings needed
• Show stderr from confirm to user verbatim

Don't:

• Never run python3, node, pip, npm, curl directly on host
• Never use k8e-sandbox-cli run with sudo
• Don't create sessions manually when auto-mode works