内容
# 容器列表
**开源、自托管、代理原生沙盒。**
您可以自带代理 — Cursor、Claude Code、OpenCode 或您自己的 MCP 客户端。
我们为您运行沙盒。
```
代理： "创建一个名为 'blog' 的沙盒" → containarium create
代理： "配置 SSH 以便我可以访问它" → containarium ssh-config sync
代理： "在 ':8080' 内安装 Caddy" → shell_exec （通过 agent-box MCP）
代理： "在 blog.example.com 上公开它" → containarium expose-port
curl https://blog.example.com → 你好，世界
```
[](LICENSE)
[](go.mod)
[](https://youtu.be/IBDDD_tb8FY)
🌐 **项目站点：** [containarium.dev](https://containarium.dev) · 🎬 **55 秒演示：** [youtu.be/IBDDD_tb8FY](https://youtu.be/IBDDD_tb8FY) · 🚀 **直播应用：** [helloworld.demo.containarium.dev](https://helloworld.demo.containarium.dev)
---
## 为什么是“代理原生”？
人工智能代理越来越多地成为开发基础设施的主要用户。
他们希望构建、安装、部署和验证 — 不是在人类的笔记本电脑上
（太吵闹、太有风险、太本地化），而是在一个沙盒中：
- **持久性**：代理运行之间的状态得以保留。
- **隔离性**：一个行为不端的安装程序不会影响您的机器。
- **真实性**：一个完整的 Linux 环境，带有 `systemd`、真实的网络，
以及在开放的互联网上托管事物的能力。
- **由结构化工具驱动**：不是由代理在 TTY 中输入命令，
而是受 MCP 驱动的，类型限定、安全。
这就是 Containarium 为您提供的沙盒。 它作为一个自托管的
单主机平台（一个 VM → 许多隔离的 LXC 容器）运行，
通过 MCP 公开其管理界面，并附带一个在容器内运行的
第二个 MCP 服务器，以便代理可以 `shell_exec` 和直接编辑文件。
您可以自带代理。 我们为您运行沙盒。
---
## 快速入门
### 1. 在新的 Ubuntu 虚拟机上自行托管（5 分钟）
```bash
curl -fsSL https://raw.githubusercontent.com/footprintai/containarium/main/hacks/install.sh \
| sudo bash
```
这将安装 Containarium + Incus + 依赖项，启动守护进程，
并为您提供 `http://localhost:8080` 处的 API。
### 2. 创建您的第一个沙盒
```bash
sudo containarium create alice --ssh-key ~/.ssh/id_ed25519.pub
sudo containarium list
```
### 3. 配置 SSH 以便 `ssh alice` 直接生效
```bash
containarium ssh-config sync
# 添加条目到 ~/.containarium/ssh_config。
# 然后在 ~/.ssh/config 中添加一行：
# Include ~/.containarium/ssh_config
ssh alice # 通过哨兵连接
```
### 4. 将您的代理指向沙盒
在 `~/.cursor/mcp.json` 或 `~/.claude.json` 中：
```jsonc
{
"mcpServers": {
"containarium-box": {
"command": "ssh",
"args": ["alice", "agent-box"]
}
}
}
```
现在，Claude Code、Cursor 或任何 MCP 代理都可以调用
`shell_exec`、`read_file`、`write_file`、`list_directory`、
`move_file`、`delete_file` 直接在 Alice 的容器内。
### 5. 使其在公共主机名上可访问
```bash
containarium expose-port alice \
--container-port 8080 \
--domain blog.example.com
```
哨兵上的 Caddy 为 `blog.example.com` 终止 TLS 并
转发到 `alice-container:8080`。`curl https://blog.example.com`
访问 Alice 在端口 8080 上提供的任何内容。
---
## 四个基本操作
Containarium 中的每个操作都有一个 CLI 动词（规范）和
一个 MCP 工具（薄包装器，委托给相同的 Go 函数）。参见
[CLAUDE.md](CLAUDE.md) 以获取约定。
### `agent-box` — 盒子内的 MCP 服务器
在每个容器内运行。通过 stdio 访问（通常由
客户端 SSH 包装）。公开 Linux 原生操作：
| 工具 | 功能 |
|---|---|
| `shell_exec` | 运行 shell 命令，捕获 stdout/stderr/exit，受超时（默认 30 秒，最多 10 分钟）和 256 KiB 输出限制 |
| `read_file` | 字节范围或 `head=N` 行或 `tail=N` 行 |
| `write_file` | 原子写入，`mkdirp` （临时 + 重命名） |
| `list_directory` | 类型/大小/mtime，隐藏过滤 |
| `move_file` | 原子重命名，目标上的 `mkdirp` |
| `delete_file` | 单文件删除（拒绝目录，因此递归删除通过 `shell_exec`，明确爆炸半径） |
资源（代理通过 MCP `resources/read` 获取的只读数据）：
| URI | 返回内容 |
|---|---|
| `containarium://ci-context` | 当前 CI 运行的 JSON 元数据（PR 编号、提交 SHA、失败测试等），如果盒子不是 CI 盒子，则返回 `{"available": false}` |
| `containarium://ci-prompt` | 静态 Markdown 剧本，告诉代理如何在盒子内调试失败的 CI 运行（先读什么，如何迭代，不要做什么）。每个盒子的内容相同；与 `ci-context` 配对使用以获取每个运行的数据。 |
可选沙盒：当设置 `AGENTBOX_ROOT` 时，每个文件操作路径都相对于该根目录，并具有边界感知前缀检查。默认情况下未设置 = 无约束。参见
[`internal/agentbox/`](internal/agentbox/) 以获取 Go 实现。
### `mcp-server` — 平台 MCP 服务器
在主机上运行。公开盒子外部的管理操作：
`create_container`、`list_containers`、`delete_container`、
`start_container`、`stop_container`、`expose_port`、`get_metrics`、
`get_system_info`。参见 [`cmd/mcp-server/`](cmd/mcp-server/)。
### `containarium` CLI
与平台 MCP 相同，加上更深入的管理。顶级动词：
```
containarium create 创建一个新容器
containarium list 列出所有容器
containarium delete 删除容器
containarium expose-port 在公共主机名上公开容器端口
containarium ssh-config 生成自包含的 ssh_config
containarium route 管理代理路由（低级）
containarium passthrough 管理 TCP/UDP 直通规则
containarium token 发布 API 的 JWT 令牌
containarium info 系统信息
containarium version 打印版本
```
运行 `containarium <verb> --help` 以获取完整选项。
### 哨兵 — sshpiper + Caddy + PROXY-protocol
哨兵是一个小型、始终在线的虚拟机（e2-micro 在 GCP 免费层有效）
负责：
- 接收端口 22 上的 SSH（sshpiper 按用户名路由到正确的后端）。
- 接收 443 上的 HTTPS（Caddy 使用 TLS 直通或
PROXY-protocol 感知转发到后端 Caddy）。
- 在后端 spot-VM 终止时保持静态 IP / DNS A 记录，以便后端可以是短暂的。
参见 [docs/SENTINEL-DESIGN.md](docs/SENTINEL-DESIGN.md) 以获取完整
设计。
---
## 架构
```
代理（Cursor / Claude Code / OpenCode）
│
│ JWT（访问；tt=access，jti，scopes）
│ MCP over stdio ──┐
│ │ ┌── refresh ──> POST /v1/tokens/refresh
v ▼ │ （单次使用；旧 jti 被吊销）
ssh user@box → sshpiper → agent-box （在容器内）
│
│ HTTPS （mTLS 上游；PROXY-protocol v2）
v
哨兵（e2-micro，始终在线）
├── sshpiper （端口 22） ：按用户名路由；每个用户 fail2ban
├── Caddy + PROXY-protocol （443） ：按主机名 / SNI 后缀路由
└── /wake/ 源 IP 允许列表 ：仅限受信任的代理
│
v
+-------------------------------------------------+
| 后端 VM（spot 或裸金属 GPU 节点） |
| |
| Incus（LXC） ── 容器 |
| ├── alice-container ：SSH + agent-box |
| │ └── /run/secrets/* : tmpfs, 0440 alice |
| └── bob-container ：ZFS 支持的存储 |
| |
| Containarium 守护进程 |
| ├── JWT 认证（iss/aud/jti/scopes） |
| ├── 管理 RBAC + 容器所有者授权 |
| ├── 镜像摘要门控（REQUIRE + VERIFY） |
| ├── 密钥 ── Postgres（信封加密） |
| │ │ |
| │ v |
| │ KMS ── Vault Transit / GCP KMS |
| │ （主密钥可吊销） |
| └── 审计日志 ── Postgres + SHA-256 哈希 |
| 链（验证 CLI） |
+-------------------------------------------------+
```
单个哨兵可以支持多个后端 VM — 一个“池” — 并且单个部署可以运行多个池（每个隔离）。参见
[docs/MULTI-POOL.md](docs/MULTI-POOL.md)。
**安全控制表面**（所有环境变量均可选择，默认为关闭以确保升级安全；参见 [`docs/security/OPERATOR-SECURITY-RUNBOOK.md`](docs/security/OPERATOR-SECURITY-RUNBOOK.md)）：
| 环境变量 | 层 | 效果 |
| --- | --- | --- |
| `CONTAINARIUM_REQUIRE_IMAGE_DIGEST=true` | API | 拒绝没有 `@sha256:<64hex>` 的镜像 |
| `CONTAINARIUM_VERIFY_IMAGE_DIGEST=true` | API | 在注册表索引（预拉取 + 后拉取）中验证摘要 |
| `CONTAINARIUM_ALLOWED_IMAGE_REGISTRIES` | API | 限制守护进程从哪些 simplestreams 远程仓库拉取 |
| `CONTAINARIUM_KMS_BACKEND={none,inproc,vault,gcp}` | 密钥 | 通过外部 KMS 对 DEK 进行信封加密 |
| `CONTAINARIUM_REQUIRE_ENVELOPE=true` | 密钥 | 拒绝旧的仅主密钥行（阶段 E 退休门） |
| `CONTAINARIUM_POSTGRES_URL_FILE` / `_PASSWORD_FILE` | 密钥 | 从磁盘而非环境变量获取数据库凭证 |
| `CONTAINARIUM_WAKE_TRUSTED_PROXIES` | 哨兵 | `/wake/` 的源 IP 允许列表 |
| `OTEL_BEARER_REQUIRED=true` | 遥测 | 收集器拒绝未带令牌的 OTLP 提交 |
---
## 它与众不同
### vs. SaaS 沙盒（e2b、Modal、Replit）
这些为您提供 AI 代理的沙盒，但仅作为托管 SaaS：
- **自托管**：Containarium 在您的基础设施上运行
（$5 虚拟机、您的家庭实验室、企业数据中心）。e2b、Modal
和 Replit 仅提供 SaaS — 您的代码、数据和客户
都通过他们的计算。
- **许可证**：Apache 2.0，无 CLA。分叉、出售、运行。
- **表面**：完整的 Linux 容器，具有 `systemd`、真实网络
命名空间、GPU 直通。不是每个调用的进程沙盒。
- **传输**：从第一天起原生 MCP，而不是带有 MCP
附加的自定义 SDK。
### vs. Docker AI 沙盒 (`sbx`)
Docker 的 `sbx run claude` 和 Containarium 都称为
“AI 沙盒”，但它们位于同一频谱的对端：
- **位置**：`sbx` 在开发人员的笔记本电脑上运行
（microVM，主机隔离）。Containarium 在您托管的 VM 上运行
（LXC，多租户，通过哨兵可公开访问互联网）。
- **持久性**：`sbx` 是会话形的（工作区挂载，无
文档化的“给我一个可以重启并有主机名的盒子”）。Containarium
容器无限期存活，带有 ZFS 快照和 30 天保留期。
- **公开访问**：`containarium expose-port alice --domain
blog.example.com` 是一个动词。`sbx` 是本地限定的；没有
公共主机名故事。
- **代理表面**：`sbx` 是 CLI-first (`sbx run <agent>`).
Containarium 是 MCP 原生 — 两个 MCP 服务器（盒子内的
`agent-box` + 平台 `mcp-server`）以及相同的表面通过
CLI、SSH、REST/gRPC 和 Web UI。
- **许可证**：`sbx` CLI 免费；团队策略（Docker Admin Console）
是付费订阅。Containarium 是 Apache 2.0 — 包括
审计日志、RBAC、KMS 集成以及此页面上的所有内容。
如果您阻止代理执行 `rm -rf` 操作的笔记本电脑，
`sbx` 是更轻量的工具。如果您为您的代理（或客户的代理）
提供一个具有公共互联网访问的持久 Linux 盒，Containarium
是合适的形状。
### vs. 开发环境平台（Codespaces、Gitpod、Coder）
那些是持久的 IDE。Containarium 是一个持久的 **盒子** —
代理驱动的，不是开发者驱动的，没有 IDE 假设，SSH 作为 API：
- Containarium 环境通过 SSH 和 MCP 访问。任何 IDE 都有效
（Vim、JetBrains Remote、VS Code Remote、Cursor 的远程开发 — 您的
调用）。
- 成本：开源路径中没有按小时计费。自行托管成本仅为
您的底层 VM。
- 持久性：容器无限期存活；Codespaces 在不活动后自动删除。
### vs. 应用程序容器平台（Docker、Kubernetes）
LXC 是一个 **系统** 容器，而不是应用程序容器。每个
容器都有 `systemd`、真正的 init、真正的用户、真正的包管理器、
真正的 `sudo`。您可以在 Containarium 容器内运行 Docker；反之
则不是真正的事情。
如果您的代理将 `apt install` 一半 Linux 发行版，编辑
`/etc` 中的配置文件，运行数据库并重启 — LXC 是合适的形状。
如果您的代理运行单个 Python 进程，Docker 或 Modal 是
可以的。
这不是“另一种运行 Pod 的方式” — 它给代理一个
**硬化、SSH 原生的立足点** 在您的集群中 **而无需
提供 kube-apiserver 令牌**：盒子以 `automountServiceAccountToken:
false` 满足 `restricted` Pod 安全配置文件。
后端编译在 `k8s` 构建标签后，因此默认守护进程
永远不会拉取 `client-go`。它是 **实验性**：控制平面
已实现并在每次更改时与 [kind](https://kind.sigs.k8s.io/) 进行 CI 测试；
代理端数据平面（agent-box 镜像 + 端到端 SSH 通过 sshpiper）仍在落地中。
设计、拓扑结构和 BYO 集群集成：
[docs/K8S-AGENT-BOX-RUNTIME-DESIGN.md](https://github.com/footprintai/containarium/blob/main/docs/K8S-AGENT-BOX-RUNTIME-DESIGN.md).
### Web UI
一个基本的 `/webui/` 仪表板，适用于不想输入 CLI 的用户：
容器列表、生命周期控制、指标、基于浏览器的终端。
精致的 UI 有意成为云产品的关注点 — 开源 Web UI
功能齐全，但不具风格。
### 持久存储（ZFS）
容器在 VM 重启和 spot 终止后存活。ZFS 处理
压缩、快照（默认每天）和校验和。
### 哨兵高可用性
哨兵本身是 e2-micro（免费层）。它：
- 在 ~10 秒内检测 spot 抢占，提供维护页面。
- 在 ~85 秒内自动重启 spot VM。
- 持有静态 IP，以便 DNS 不会随着后端轮换而更改。
### 监控和可观察性
VictoriaMetrics + Grafana 自动配置。每个容器 CPU、
内存、磁盘、网络。基于 Webhook 的警报。SSH 审计日志每个用户。
### 安全基元
- **无特权 LXC 容器**：容器 root ≠ 主机 root。
- **每个用户的代理帐户**：哨兵上的 `/usr/sbin/nologin`，
用户只能通过代理连接到他们的容器。
- **每个用户 fail2ban**：攻击一个账户不会封禁
另一个账户。
- **ClamAV + Trivy** 跨所有后端扫描。
- **AppArmor 配置文件** 每个容器。
- **AGENTBOX_ROOT 沙盒** 以在运行时限制 agent-box 文件操作。
**零信任控制**（在 v0.17 → unreleased 行中推出；参见 [`docs/security/OPERATOR-SECURITY-RUNBOOK.md`](https://github.com/footprintai/containarium/blob/main/docs/security/OPERATOR-SECURITY-RUNBOOK.md)）：
- **具有 `iss` / `aud` / `jti` / `tt` / `scopes` 的 JWT**：32 字节
最低秘密强制执行；在启动时强制执行；单次使用刷新的令牌；
基于 jti 的吊销；每个工具的 MCP 范围传播到服务器端门控。
- **管理员 RBAC + 每个容器所有者身份验证** 在 API 表面；
集群操作仅限管理员，容器操作仅限所有者。
- **租户机密的 KMS 信封加密** （Vault Transit 或 GCP
Cloud KMS），带有迁移工具和主密钥退休门控。
- **tmpfs `--delivery=file`** 用于不应在
`/proc/<pid>/environ` 中可见的机密。
- **审计日志与 SHA-256 哈希链** + `containarium audit verify`
以检测篡改。
- **镜像注册表允许列表 + 预拉取 simplestreams 摘要验证 + 拉取后 `volatile.base_image` 防御深度** 用于供应链强化。
- **安全.md** 具有 90 天的协调披露窗口；
`gosec` / `govulncheck` / `trivy` 在 CI 中运行。
# 使用选项创建
containarium create ml-dev \
--ssh-key ~/.ssh/id_ed25519.pub \
--gpu 0 \
--stack gpu \
--memory 16GB \
--cpu 4
# 生命周期
containarium list
containarium info
containarium start alice
containarium stop alice
containarium delete alice
### 网络配置
```bash
# 在公共主机名上暴露容器端口
containarium expose-port alice \
--container-port 8080 \
--domain blog.example.com
# 低级路由管理
containarium route add api.example.com --target 10.0.3.42:3000
containarium route list
containarium route delete api.example.com
# 原始TCP/UDP直通（无TLS终止）
containarium passthrough add --port 50051 \
--target-ip 10.0.3.150 --target-port 50051
```
### SSH配置
```bash
# 输出到stdout（预览）
containarium ssh-config show
# 写入 ~/.containarium/ssh_config（单行 `Include` 以连接）
containarium ssh-config sync
containarium ssh-config sync --sentinel sentinel.example.com # 通过sentinel
containarium ssh-config sync --identity ~/.ssh/containarium_ed25519
```
### 身份验证
```bash
# 生成访问和刷新令牌对（仅限CLI；从不通过API公开）。
# 访问令牌寿命短（默认15分钟）并验证API。
# 刷新令牌寿命长且单次使用 — 通过POST /v1/tokens/refresh交换为新对。
containarium token generate \
--username admin \
--roles admin \
--secret-file /etc/containarium/jwt.secret
# 使用访问令牌
curl -H "Authorization: Bearer <access-token>" http://localhost:8080/v1/containers
# 检查令牌的声明（jti，作用域，过期，验证）
containarium token inspect <token> --secret-file /etc/containarium/jwt.secret
# 通过jti撤销泄漏的令牌（幂等；从 `audit query` 或 `token inspect` 读取）
containarium token revoke <jti> --reason "leak_2026_05_22"
containarium token list-revoked
# 为仅具有所需作用域的代理生成最小权限令牌 — 服务器端门控强制执行此操作，即使代理忽略
# 过滤器。
containarium token generate \
--username alice-agent \
--scopes containers:read,containers:write \
--secret-file /etc/containarium/jwt.secret
```
参见 [`docs/security/OPERATOR-SECURITY-RUNBOOK.md`](docs/security/OPERATOR-SECURITY-RUNBOOK.md)，了解完整的令牌生命周期、泄漏响应手册和代理最小权限作用域目录。
---
## 部署
### 手动安装（推荐用于快速入门）
```bash
curl -fsSL https://raw.githubusercontent.com/footprintai/containarium/main/hacks/install.sh \
| sudo bash
```
参见 [`hacks/README.md`](hacks/README.md)，了解脚本的作用。
### Terraform（推荐用于生产环境）
```bash
cd terraform/gce
cp examples/single-server-spot.tfvars terraform.tfvars
vim terraform.tfvars # 设置 project_id, admin_ssh_keys, allowed_ssh_sources
terraform init
terraform apply
```
参见 [`terraform/gce/README.md`](terraform/gce/README.md)，了解变量。
### 系统要求
- **主机操作系统**：Ubuntu 24.04 LTS 或更高版本（容器可以是任何受支持的操作系统）。
- **Incus 6.19+** 需要Docker-in-LXC支持。Ubuntu 24.04的默认仓库提供6.0.0，存在AppArmor漏洞
([CVE-2025-52881](https://ubuntu.com/security/CVE-2025-52881))；
使用 [Zabbly Incus仓库](https://pkgs.zabbly.com/) 获取当前版本。
- **ZFS内核模块** （用于磁盘配额）。
- 内核模块：`overlay`、`br_netfilter`、`nf_nat` （Docker-in-容器需要这些）。
```bash
# 通过Zabbly快速安装Incus
curl -fsSL https://pkgs.zabbly.com/key.asc | \
sudo gpg --dearmor -o /usr/share/keyrings/zabbly-incus.gpg
echo 'deb [signed-by=/usr/share/keyrings/zabbly-incus.gpg] \
https://pkgs.zabbly.com/incus/stable noble main' | \
sudo tee /etc/apt/sources.list.d/zabbly-incus-stable.list
sudo apt update
sudo apt install incus incus-tools incus-client
incus --version # 6.19 或更高版本
```
---
## API
Containarium 暴露：
- **REST API** 在 `http://localhost:8080` （gRPC-gateway over gRPC服务，JWT身份验证）
- **gRPC** 在 `:50051` （mTLS，主要由CLI使用）
- **两个MCP服务器** ：`mcp-server` （平台）和 `agent-box` （盒中盒）
OpenAPI / Swagger UI 在
`http://localhost:8080/swagger-ui/`。
令牌颁发 **仅限CLI** ，设计如此；守护进程没有“通过API颁发令牌”的端点，因为如果有，任何具有API访问权限的人都可以铸造管理员令牌。
---
## 硬化笔记
### SSH密钥卫生
- 每个用户都有自己的密钥对。 **绝不** 在用户之间共享密钥 — 共享会破坏撤销、审计和每用户fail2ban。
- 同一个密钥可以验证到sentinel代理帐户和容器。这是支持的流程：更简单，用户无需
安全损失，因为代理帐户是`nologin`，仅通过路由。
- 轮换：用户生成新密钥，管理员替换容器中的
`authorized_keys` 内容。
### 代理盒沙盒
如果您运行不受信任的代理，请将 `AGENTBOX_ROOT` 设置为项目目录：
```bash
# 在容器中
export AGENTBOX_ROOT=/srv/project
agent-box # 现在所有文件操作仅限于 /srv/project
```
`shell_exec`故意不限于LXC容器边界本身 — 按设计，这是工具的契约。如果您需要
更严格的隔离，请在更受限制的容器中运行agent-box（例如
嵌套LXC，或进一步chrooto用户帐户）。
### 网络
- 后端虚拟机默认 **没有公共IP** ；它们通过
Cloud NAT延伸并仅通过sshpiper接受入站流量。
- Sentinel允许列表：配置Terraform中的`allowed_ssh_sources`
（或手动配置防火墙规则）以锁定谁可以访问端口22。
---
## 比较FAQ
**为什么不使用Docker / Podman？**
Docker适用于应用程序容器。Containarium使用LXC系统
容器 — 每个容器都是完整的Linux操作系统，真正的`systemd`，原生SSH，
Docker-in-LXC有效，持久文件系统。如果您的代理将
`apt install`并重启，您需要LXC。
**为什么不使用Kubernetes？**
K8s编排许多节点上的应用程序容器。
Containarium在单个（或几个）
节点上运行许多完整的Linux环境。形状不同，问题不同。
**为什么不使用Vagrant？**
Vagrant在开发人员的本地机器上编排虚拟机。Containarium
在共享远程基础设施上托管环境，供多个代理使用。
**为什么不使用Dev Containers / VS Code Remote Containers？**
Dev Containers是项目范围的、IDE耦合的、单开发人员。
Containarium为许多用户（或一个用户的许多代理）提供他们自己的
持久盒子，基于共享基础设施，IDE无关。
**为什么不使用Codespaces / Gitpod？**
浏览器-IDE-即服务，按小时计费，供应商锁定。Containarium
是自托管的，持久的，基于SSH/MCP的，没有按小时计费的开源版本。
**为什么不使用e2b / Modal / Daytona？**
最接近的同类 — AI代理的沙盒。它们是SaaS-only的，
通常优化用于短寿命、按调用执行的流程。
Containarium是自托管的，原生MCP，并为您提供完整的
持久Linux盒。选择e2b如果您想要托管-only和短暂的；
选择Containarium如果您想要自托管，持久的，
您的数据在您的基础设施上。
**为什么使用LXC？**
- 每个容器运行一个完整的Linux操作系统，带有`systemd`。
- SSH访问是一流的。
- Docker-in-LXC有效（与脆弱的Docker-in-Docker相比）。
- 真正的持久文件系统，真正的用户，真正的`sudo`。
- 为代理“感觉像一个VM” — 与托管
云VM相同的表面积，资源成本的几分之一。
---
## 用例
- **AI代理沙盒** （主要）：Cursor，Claude Code，Cline，
OpenCode，自定义代理 — 都达到相同的MCP表面。
- **共享开发者环境**：许多开发者，一个主机，SSH
跳转服务器与每用户隔离。
- **ML / GPU实验**：GPU直通到LXC。
- **教育，训练营，工作坊**：每个学生隔离的Linux
没有每个学生的虚拟机。
- **CI /构建基础设施**：长期运行的构建主机，保持
运行间的缓存温暖。
- **演示/测试基础设施**：启动一个真正的Linux环境，测试，
关闭。
---
## 现实世界中的使用
Containarium演示过的地方：
- **2026-06-04 — AI Agent Night, Taipei.** 当大奖
抽奖（自定义振动键盘）遇到问题 — 活动没有办法
运行抽奖 — 我们启动了Containarium并在现场编写了一个
幸运抽奖选择器来挽救抽奖活动。仍然在线：
[lucky-draw.demo.containarium.dev](https://lucky-draw.demo.containarium.dev/)。
在其他地方演示了Containarium？打开一个PR并将其添加在这里。
---
## 状态
- **生产部署** 在GCP（多区域）和裸金属GPU
节点上。
- **API稳定** （protobuf定义为gRPC-gateway）。
- **Apache 2.0** ，无CLA，接受社区PR。
- 积极维护：查看 `main` 和最近
版本的提交历史。
---
## 路线图
- **已发货（2026-06）**：实验性 **[Kubernetes后端](#kubernetes-backend-experimental)**
— 将盒子作为pod运行在集群中，您操作集群，通过SSH访问
像LXC盒子一样，使用sshpiper网关，默认拒绝NetworkPolicy和主机密钥
固定。在 `kind` 上进行了端到端验证；位于 `k8s` 构建标签后。
参见 [docs/K8S-AGENT-BOX-RUNTIME-DESIGN.md](docs/K8S-AGENT-BOX-RUNTIME-DESIGN.md)。
- **2026年第二季度（进行中）**：`agent-box` MCP，`ssh-config` CLI，
`expose-port` CLI，演示记录。
- **2026年第三季度**：`agent-box`二级（MCP Roots，背景进程
管理），演示驱动的文档和示例。
- **2026年第四季度**：OSS v1.0切割 — 稳定API表面，贡献
指南。
如果您想推动某个项目，请创建一个问题或PR — 社区工作
是受欢迎的，我们每周都会进行分类。
---
## 贡献
- 阅读 [CLAUDE.md](CLAUDE.md)，了解CLI优先原则（每个新
平台操作作为`containarium <verb>`首先落地；MCP包装它）。
- 检查 [现有问题和PR](https://github.com/footprintai/Containarium/issues)。
- 为新功能添加测试。
- 如果用户可见的行为发生变化，请更新文档。
无CLA。Apache 2.0意味着您可以自由使用、修改和重新分发。
我们欢迎符合项目定位的PR，并拒绝不符合的PR（例如
“让我在OSS守护进程中添加多租户”进入云仓库讨论，而不是此处）。
---
## 许可证
Apache License 2.0 — 参见 [LICENSE](LICENSE)。
---
## 致谢
- [Incus](https://linuxcontainers.org/incus/) — 现代LXC管理器。
- [sshpiper](https://github.com/tg123/sshpiper) — SSH反向代理。
- [mcp-go](https://github.com/mark3labs/mcp-go) — Go MCP服务器库。
- [Caddy](https://caddyserver.com/) — TLS /反向代理，支持
PROXY协议。
- [Cobra](https://cobra.dev/) — CLI框架。
- [Terraform](https://terraform.io/) — 基础设施即代码。
---
## 支持
- **项目站点**： [containarium.dev](https://containarium.dev) — 概述、托管云、CI的GitHub Actions、PR预览。
- **文档**： [docs/](docs/) 目录。
- **问题**： [GitHub Issues](https://github.com/footprintai/Containarium/issues)。
- **演示视频**： [YouTube上的55秒快速演示](https://youtu.be/IBDDD_tb8FY)。
- **实时演示应用**： [helloworld.demo.containarium.dev](https://helloworld.demo.containarium.dev)。
- **组织**： [FootprintAI](https://github.com/footprintai)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器