沙箱范例 —— 由你的 AI Agent 驱动

本指南中的所有范例都从你的 Agent 工具链（pi、Claude Code 或 Codex）出发，通过 /k8e-sandbox skill 驱动。你用自然语言描述目标，skill 会在隔离的沙箱 Pod 内替你运行 k8e-sandbox-cli。你不需要自己敲 CLI 命令 —— 但每个范例都会展示 skill 在幕后实际做了什么，让你始终清楚发生了什么。

前置条件

  1. 完成快速开始的第 3 步：下载 CLI、connect，并把 skill 安装到你的 Agent 工具链。
  2. 在你的工具链中调用 skill：
    • pi：/skill:k8e-sandbox <目标>（或直接自然语言提问）
    • Claude Code：/k8e-sandbox <目标>
    • Codex：$k8e-sandbox <目标>（或从 /skills 选择）

skill 每次运行都遵循同样的循环：预检（status 检查）→ 规划 → 在沙箱中执行 → 汇报真实输出。按顺序完成下面的关卡 —— 每一关都建立在前一关之上。

💡 没有使用 Agent 工具链？ K8E 也原生支持 E2B 协议——官方 e2b SDK（Python/JS）零修改即可使用。见使用官方 E2B SDK 操作沙箱，那里有完全不需要 skill 的 SDK 驱动范例（创建、执行、文件、watch、pause/resume）。

第 1 关 —— Hello World：跑马灯动画

你对 Agent 说：

"用 Python 写一个跑马灯动画，在沙箱里运行"

skill 会执行（预检 + 执行）：

k8e-sandbox-cli status                              # 预检：网关是否可用？
k8e-sandbox-cli run --lang python --raw <<'EOF' |
import sys, time
msg = "K8E SANDBOX "
for i in range(40):
    sys.stdout.write("\r" + msg[i % len(msg):] + msg[:i % len(msg)])
    sys.stdout.flush()
    time.sleep(0.1)
print()
EOF
  sed -u -n 's/^data: {"stdout":"\(.*\)"}$/\1/p' | base64 -d

你会看到跑马灯在终端里实时滚动 —— 回车符把光标拉回行首，所以文字是滑动的， 而不是一行行堆下来。

为什么要接管道？

--raw 去掉了 CLI 的 JSON 包装，但吐出来的是服务端的 SSE 帧格式，不是纯文本：

data: {"stdout":"S1QgU0FOXkFCWCA="}
data: {"exit":0}

每一帧的载荷是 base64 编码的——这样输出里的换行和 ANSI 转义就永远不会破坏帧边界。 上面的 sed + base64 -d 会把流还原成程序真正打印出来的字节。 不加 --raw 也能拿到同样的文本，只是要等命令结束才一次性返回：

k8e-sandbox-cli run --lang python <<'EOF' | jq -r .stdout
print("hello from the sandbox")
EOF

较新的 k8e-sandbox-cli 会直接打印明文 —— 解码已经移进 CLI（k8e PR #671）， run --raw 不再需要管道。确认你用的是哪个版本：

k8e-sandbox-cli run --raw "echo hi" | head -1

打印 hi 就去掉管道；打印 data: {"stdout":"…"} 就保留。 两者互斥——管道会把明文全部过滤掉。

整个过程宿主机上没有任何 Python —— 全部运行在隔离 Pod 内。

试一试： 用同样的方式要求一个 bash 单行（echo 'hello from sandbox'）或 TypeScript 片段（--lang ts）。skill 会为你选择语言。

第 2 关 —— 数据脚本：文件与依赖

你对 Agent 说：

"在沙箱里安装 pandas，并运行一个打印版本号的脚本"

skill 会执行（创建会话 → 写入文件 → 安装 → 运行 → 读回）：

SID=$(k8e-sandbox-cli create | jq -r .session_id)   # 显式会话，下面复用它
k8e-sandbox-cli write $SID /workspace/script.py <<'PYEOF'
import pandas as pd
print("pandas", pd.__version__)
PYEOF
k8e-sandbox-cli run "pip install pandas" --session-id $SID
k8e-sandbox-cli run "python3 /workspace/script.py" --session-id $SID
k8e-sandbox-cli read $SID /workspace/script.py
k8e-sandbox-cli list $SID                            # 查看 /workspace 中的变化
k8e-sandbox-cli destroy $SID                         # 完成后清理

你会看到 pandas 2.x.y 以及文件列表。包安装开箱即用 —— 默认出口白名单包含 pypi.org、registry.npmjs.org 和 github.com。

试一试： 让 Agent 分析你描述的 CSV（"加载这个 CSV，打印行数和每个数值列的平均值"）。skill 会写入脚本、运行，并把数字展示给你 —— 全程在沙箱内完成。

第 3 关 —— 克隆仓库并构建

你对 Agent 说：

"把 https://github.com/user/repo.git 克隆到沙箱并构建"

skill 会执行（创建会话时克隆，然后按语言构建）：

SID=$(k8e-sandbox-cli create --git-repo https://github.com/user/repo.git --git-ref main | jq -r .session_id)
k8e-sandbox-cli run "ls -la /workspace/repo" --session-id $SID
k8e-sandbox-cli run "cd /workspace/repo && go build ./..." --session-id $SID          # Go
# 或：cd /workspace/repo && npm install && npm run build                              # Node
# 或：cd /workspace/repo && pip install -r requirements.txt                           # Python

你会看到构建日志流式返回，skill 汇报通过/失败及退出码。你可以继续迭代（"修复失败的测试再跑一次"），skill 会复用同一个沙箱，因此状态会在多轮之间保持。

试一试： 指定运行时——"克隆后用 Go 构建"或"运行它的测试套件"——skill 会把你的请求映射为正确的命令。

第 4 关 —— 构建并验证 Vue 网站

你对 Agent 说：

"在沙箱里创建一个 Vite + Vue 网站，构建它，并验证它能正常服务"

skill 会执行（脚手架 → 安装 → 构建 → 验证 → 本地预览）：

SID=$(k8e-sandbox-cli create | jq -r .session_id)
k8e-sandbox-cli run "npm create vite@latest my-app -- --template vue" --session-id $SID
k8e-sandbox-cli run "cd /workspace/my-app && npm install" --session-id $SID
k8e-sandbox-cli run "cd /workspace/my-app && npm run build" --session-id $SID
k8e-sandbox-cli run "ls -la /workspace/my-app/dist && head -30 /workspace/my-app/dist/index.html" --session-id $SID
k8e-sandbox-cli run "grep -o '<title>[^<]*</title>' /workspace/my-app/dist/index.html" --session-id $SID
k8e-sandbox-cli run "cd /workspace/my-app && (npm run dev >/dev/null 2>&1 &) && sleep 3 && curl -s http://localhost:5173/ | head -20" --session-id $SID
k8e-sandbox-cli destroy $SID

你会看到构建后的 dist/ 列表、<title> 标签，以及 dev server 在 :5173 上的响应 —— 在沙箱内用 curl 验证。你的 Vue 网站在不碰宿主机的情况下完成了脚手架、构建和冒烟测试。

在浏览器里打开（KIP-24）： 通过 k8e API Gateway 暴露 dev server，直接打开返回的 URL：

k8e-sandbox-cli expose 5173 --session-id $SID
# -> {"url":"http://<gateway>/k8e/expose/<sid>/5173/",...}

任何能访问网关的主机都可以打开该 URL。停止服务用 k8e-sandbox-cli unexpose 5173 --session-id $SID。参见 Sandbox CLI → 暴露服务。

你学到了什么

关卡你提出skill 运行你得到
1在沙箱里跑跑马灯run --lang python --raw实时动画输出
2安装 pandas 并运行脚本create → write → run → read/list → destroy版本号 + 文件列表
3克隆并构建仓库create --git-repo → 按语言构建构建日志 + 退出码
4脚手架并验证 Vue 网站npm create → install → build → curl构建产物 + dev server 冒烟测试

模式始终一致：你描述目标，/k8e-sandbox skill 把它变成 k8e-sandbox-cli 调用，一切都在隔离 Pod 中运行。 原始命令参考见 Sandbox CLI。

最近更新: