快速开始

几分钟内创建第一个 Workspace，在里面运行命令、传文件，最后删除它。你需要一套已经运行的 Kibotos；还没有部署时，可以先按在一台机器上试用自己装一套。

三条路径任选其一：

• 用 kibo：命令行，适合手工试用和写脚本。
• 用 E2B SDK：已经在用 E2B SDK 的程序，只改连接参数就能切换过来。
• 用 Go SDK：自己管理 Workspace 的 Go 程序。

用 kibo复制标题链接

前提条件复制标题链接

向部署方要下面三样东西：

1. 安装并注册复制标题链接

安装 kibo，用注册密钥换取你的 Operator 身份，然后删除已经用过的密钥：

sudo install -m 0755 kibo_1.2.3_linux_amd64 /usr/local/bin/kibo
umask 077
kibo context enroll --endpoint https://ctrl.example.com:18092 --key-file operator-enrollment.key
rm operator-enrollment.key

身份保存在本机的 context 目录，默认是 ~/.config/kibo/context。之后的命令都自动使用它，不需要再输入密钥或密码。

确认能连上 ctrl，输出里应有 Compatible yes：

kibo version

2. 选一个 Template复制标题链接

Template创建 Workspace 用的系统镜像，例如最小系统、编程工具链或桌面环境。 决定 Workspace 里预装了什么。列出部署方提供的 Template：

kibo template list

TEMPLATE         DEFAULT REVISION     SELECTION   DELIVERY
kibotos-minimal  sha256:8cb0f385e54a  SELECTABLE  READY

第一列是 Template ID。本页用 kibotos-minimal，你的部署里名字可能不同。

3. 创建 Workspace复制标题链接

创建一个 Workspace，把它的 ID 存进变量：

workspace_id=$(kibo workspace create --template kibotos-minimal -q)
echo "$workspace_id"

• 命令等到 Workspace 可以使用才返回，通常几秒。
• 不加 -q 时输出一段摘要，包括 CPU、内存、Volume 与网络设置。
• 默认配置：1 个 CPU、256 MiB 内存，不能访问网络，一个挂在 /data 的 Volume。参数见创建 Workspace。

4. 运行命令复制标题链接

在 Workspace 里运行一条命令，输出直接打印在本机：

kibo workspace exec "$workspace_id" -- uname -sr
kibo workspace exec "$workspace_id" -- sh -c 'echo "hello from $(hostname)"'

kibo 的退出码就是远端命令的退出码，可以直接用在脚本的判断里。kibo 自身失败时（例如找不到 Workspace）以 255 退出；被 --exec-timeout 终止的命令以 124 退出。见 kibo 退出码。

5. 上传与下载文件复制标题链接

上传一个本地文件，在 Workspace 里处理它，再把结果取回来：

printf 'hello kibotos\n' > notes.txt
kibo workspace file put "$workspace_id" notes.txt /data/notes.txt
kibo workspace exec "$workspace_id" -- sh -c 'wc -c /data/notes.txt > /data/result.txt'
kibo workspace file get "$workspace_id" /data/result.txt result.txt
cat result.txt

/data 是 Volume独立于任何 Workspace 存在的持久卷。一个 Workspace 最多绑定一个 Volume，默认挂载在 /data。，Workspace 停止再启动后数据还在。其他路径的保留规则见保证与边界。

6. 打开终端复制标题链接

打开一个交互式 shell，输入 exit 退出：

kibo workspace terminal "$workspace_id"

7. 访问网络复制标题链接

新建的 Workspace 默认不能访问网络。允许它访问公网，立即生效：

kibo workspace network set "$workspace_id" public-internet
kibo workspace exec "$workspace_id" -- curl -sS -o /dev/null -w '%{http_code}\n' https://example.com

只放行部分地址、让流量经你自己的代理离开（v0.3.0 或更新版本），见网络概览。

8. 删除复制标题链接

删除 Workspace，确认提示输入 y。随它一起创建的 Volume 也会删除：

kibo workspace delete "$workspace_id"

在脚本里删除时加 --yes 跳过确认。

用 E2B SDK复制标题链接

前提条件复制标题链接

• Node.js 22 或更新版本。
• 向部署方要 E2B 网关的 API key、域名（例如 sandbox.example）和可用的 Template 名称。
• 网关证书由私有 CA 签发时，还要这个 CA 的证书文件。

1. 安装 SDK复制标题链接

在一个新目录里安装 E2B 的 JavaScript SDK。2.46.1 是 Kibotos 验收使用的版本：

npm init -y
npm install e2b@2.46.1

2. 写程序复制标题链接

把下面的内容保存为 quickstart.mjs。它创建一个 sandbox，运行命令、读写文件，最后删除 sandbox：

import { Sandbox } from 'e2b';

const sandbox = await Sandbox.create('kibotos-minimal');
try {
  const result = await sandbox.commands.run('uname -sr');
  console.log(result.stdout);

  await sandbox.files.write('/tmp/notes.txt', 'hello kibotos\n');
  await sandbox.commands.run('wc -c /tmp/notes.txt > /tmp/result.txt');
  console.log(await sandbox.files.read('/tmp/result.txt'));
} finally {
  await sandbox.kill();
}

Kibotos 里 E2B 的 sandbox 就是 Workspace，kibotos-minimal 换成部署方给你的 Template 名称。

3. 运行复制标题链接

SDK 从环境变量读取 API key 与域名。下面假设 API key 保存在文件 e2b-api-key.txt 里，设好环境变量后运行程序：

export E2B_API_KEY="$(cat e2b-api-key.txt)"
export E2B_DOMAIN=sandbox.example
node quickstart.mjs

网关证书由私有 CA 签发时，运行前还要让 Node.js 信任这个 CA，例如 export NODE_EXTRA_CA_CERTS="$PWD/sandbox-ca.pem"。

用 Go SDK复制标题链接

前提条件复制标题链接

• Go 1.27 或更新版本，以及 Kibotos 仓库的一份检出。仓库公开之前，你需要它的读权限。
• ctrl 地址与一个 Template 的名称。
• 程序的注册密钥。由 Operator 用 kibo enrollment create --operator my-program --output my-program.key 生成。

1. 运行示例复制标题链接

examples/go/quickstart 连接 ctrl，创建 Workspace，运行命令，传文件，再删除 Workspace。第一次运行时用密钥换取身份，并保存到你指定的目录：

go run ./examples/go/quickstart -endpoint https://ctrl.example.com:18092 \
  -identity "$HOME/.local/state/kibotos-quickstart" -enrollment-key-file my-program.key

之后的运行复用这个目录，不再需要密钥。部署里没有 kibotos-minimal 时，加 -template。

2. 以它为起点复制标题链接

这个示例只导入 SDK 模块。要在自己的模块里使用 SDK，见 Go SDK。

注意复制标题链接

• E2B 网关覆盖 E2B 的基础能力，未提供的部分会明确返回错误，见不支持的能力。部署早于 v0.3.0 时，文件路径请写绝对路径。

排查复制标题链接

下一步复制标题链接

• 核心概念：Workspace、Template、Volume 与状态。
• kibo 命令行：其余命令，以及等待、幂等与结果查询。
• 生命周期：停止后保留什么、出了问题怎么恢复。
• API 概览：需要完整能力与兼容承诺的程序。
• 接入 Agent 平台：把 Agent 平台接入 Kibotos。
• E2B 兼容：网关支持的接口与行为差异。