内容
# VaultRun
[](https://github.com/nickvd7/vaultrun/actions/workflows/ci.yml)
[](https://pypi.org/project/vaultrun-sdk/)
[](https://github.com/nickvd7/vaultrun/pulls)
**自主托管的安全 AI 代理运行时。** — [vaultrun.dev](https://vaultrun.dev) · [llms.txt](https://vaultrun.dev/llms.txt) · [PyPI](https://pypi.org/project/vaultrun-sdk/)
VaultRun 允许 AI 代理在隔离的 Docker 沙盒中安全地执行代码、查询数据库、调用云 API 和管理文件，运行在您自己的基础设施上。无需外部 SaaS，无需数据离开您的网络。
> **最新：** VaultRun 现已开源 — 该 Apache 2.0 仓库包含以下所有内容，企业版 SSO（OIDC + SAML 2.0）可单独用于商业用途（mail@030.dev）。MCP 服务器支持标准输入输出和 HTTP（53 种工具 — Claude、OpenAI、OpenRouter、自定义代理）。请参阅 [更新日志](CHANGELOG.md) 和 [SSO 设置指南](docs/sso-setup.md)。
```
┌──────────────────────────────────────────────────────────────┐
│ 您的 AI 代理 (Claude, GPT-4o, 自定义, …) │
│ │
│ result = client.run(session_id, │
│ command="python", args=["analyze.py"]) │
└────────────────────────┬─────────────────────────────────────┘
│ API 密钥
▼
┌──────────────────────────────────────────────────────────────┐
│ VaultRun API (您的服务器，您的基础设施) │
│ │
│ • 每个会话的隔离 Docker 容器 │
│ • 执行 API — 无 shell 注入 │
│ • 工作空间中的路径遍历防护 │
│ • HMAC 签名审计日志 │
│ • 每个会话的 CPU / 内存 / 超时限制 │
│ • 默认禁用网络 │
└──────────────────────────────────────────────────────────────┘
```
## 快速入门
**先决条件：** Docker、Docker Compose、Go 1.25+
```bash
git clone https://github.com/nickvd7/vaultrun
cd vaultrun
cp .env.example .env # 将 MASTER_API_KEY 设置为强密码
make up # 启动 API + Postgres + Redis + 仪表盘
make bootstrap-key # 打印您的第一个 vr_... API 密钥
curl http://localhost:8080/health
```
在 `http://localhost:3000` 打开仪表盘。
## 包含内容
| 组件 | 描述 |
|---|---|
| **API 服务器** (`cmd/api`) | 基于 Gin 的 REST API — 会话、运行、文件、审计 |
| **CLI** (`cmd/cli`) | `vaultrun` 命令行工具 |
| **MCP 服务器** (`sdk/mcp`) | 53 工具的 MCP 服务器（标准输入输出 + HTTP） |
| **CI 运行器** (`cmd/ci-runner`) | GitHub webhook → 沙盒 CI + Slack/Teams 通知 |
| **仪表盘** (`apps/frontend`) | Next.js 管理界面 |
| **Go SDK** (`sdk/go`) | 类型化的 Go 客户端 |
| **Python SDK** (`sdk/python`) | Python 客户端 — [`pip install vaultrun-sdk`](https://pypi.org/project/vaultrun-sdk/) |
## 架构
```
vaultrun/
├── cmd/
│ ├── api/ Go API 服务器（Gin）
│ ├── cli/ Go CLI（vaultrun）
│ └── ci-runner/ GitHub webhook CI 运行器
├── internal/
│ ├── auth/ API 密钥哈希 + 验证
│ ├── audit/ HMAC 签名事件日志
│ ├── docker/ 容器 + 执行管理
│ ├── workspace/ 文件保险箱，路径遍历防护
│ ├── runner/ 命令执行编排
│ ├── db/ Postgres 查询（sqlx）
│ ├── policy/ 可插拔策略钩子（OPA-ready）
│ └── config/ 基于环境的配置
├── apps/
│ └── frontend/ Next.js 仪表盘（React + Tailwind）
├── sdk/
│ ├── go/ Go SDK
│ ├── python/ Python SDK
│ └── mcp/ MCP 服务器（53 工具）
├── migrations/ SQL 迁移（golang-migrate）
├── deployments/ Docker Compose + Dockerfiles
├── docs/ 架构、安全、API 参考
└── examples/ 使用示例
```
## MCP 服务器（53 工具）
MCP 服务器通过 Model Context Protocol 工具公开 VaultRun 的所有功能。
几秒钟内将其添加到 Claude Desktop、Claude Code 或任何 MCP 兼容平台。
### 标准输入输出传输（Claude Desktop / Claude Code）
```json
{
"mcpServers": {
"vaultrun": {
"command": "/path/to/vaultrun-mcp",
"env": {
"VAULTRUN_BASE_URL": "http://localhost:8080",
"VAULTRUN_API_KEY": "vr_your_key"
}
}
}
}
```
构建二进制文件：`go build -o vaultrun-mcp ./sdk/mcp/`
### HTTP 传输（OpenAI / OpenRouter / 自定义）
```bash
MCP_TRANSPORT=http \
MCP_AUTH_TOKEN=your-secret-token \
VAULTRUN_BASE_URL=http://localhost:8080 \
VAULTRUN_API_KEY=vr_your_key \
./vaultrun-mcp
# POST /mcp — JSON-RPC 2.0, Authorization: Bearer your-secret-token
```
### 工具类别
| 类别 | 工具 |
|---|---|
| **沙盒** | `create_session`, `list_sessions`, `get_session`, `delete_session`, `run_command`, `upload_file`, `read_file`, `list_files`, `delete_file`, `get_run`, `list_runs`, `get_session_stats`, `get_session_logs` |
| **镜像** | `list_images`, `pull_image` |
| **快照** | `create_snapshot`, `list_snapshots` |
| **工件** | `create_artifact`, `list_artifacts`, `list_audit_logs` |
| **GitHub** | `run_github_repo`, `github_post_comment` |
| **文件系统** | `fs_read_file`, `fs_write_file`, `fs_list_dir`, `fs_delete_file` |
| **S3** | `s3_list_buckets`, `s3_list_objects`, `s3_get_object`, `s3_put_object`, `s3_delete_object`, `s3_head_object` |
| **SSM** | `ssm_get_parameter`, `ssm_put_parameter`, `ssm_delete_parameter`, `ssm_list_parameters` |
| **机密管理器** | `sm_get_secret`, `sm_list_secrets` |
| **Lambda** | `lambda_list_functions`, `lambda_invoke` |
| **SQLite** | `sqlite_query`, `sqlite_execute`, `sqlite_schema` |
| **PostgreSQL** | `pg_query`, `pg_execute`, `pg_schema` |
| **MongoDB** | `mongo_find`, `mongo_insert_one`, `mongo_update`, `mongo_delete`, `mongo_aggregate`, `mongo_collections`, `mongo_generate_mongoose` |
完整文档：[sdk/mcp/README.md](sdk/mcp/README.md)
## GitHub CI 运行器
在 GitHub webhook 触发的 VaultRun 沙盒中运行 PR 测试套件。
```bash
GITHUB_TOKEN=ghp_... \
GITHUB_WEBHOOK_SECRET=your-secret \
VAULTRUN_BASE_URL=http://vaultrun \
VAULTRUN_API_KEY=vr_... \
SLACK_WEBHOOK_URL=https://... \ # 可选
TEAMS_WEBHOOK_URL=https://... \ # 可选
NOTIFY_ON_SUCCESS=false \ # 禁止绿色噪音
CI_TEST_COMMANDS='[["make","test"]]' \ # 默认
./ci-runner
```
- **Webhook 端点：** `POST /webhook`（HMAC-SHA256 验证）
- **健康检查：** `GET /healthz`
- 结果发布为 PR 评论 + 提交状态（`vaultrun-ci`）
- Slack Block Kit 和 Teams Adaptive Card 1.4 载荷
## REST API 参考
所有端点都需要 `X-API-Key` 或 `Authorization: Bearer <key>`。
### 会话
```
POST /api/v1/sessions 创建新会话
GET /api/v1/sessions 列出活动会话
GET /api/v1/sessions/:id 获取会话详情
DELETE /api/v1/sessions/:id 删除会话 + 容器 + 工作空间
```
**创建会话请求体：**
```json
{
"name": "my-session",
"image": "python:3.12-slim",
"network_enabled": false,
"cpu_limit": 1.0,
"memory_limit_mb": 512,
"timeout_seconds": 300
}
```
### 命令执行
```
POST /api/v1/sessions/:id/run 执行命令
GET /api/v1/sessions/:id/runs 列出会话的运行
GET /api/v1/runs/:id 获取运行详情
```
**执行命令请求体：**
```json
{ "command": "python", "args": ["script.py"], "timeout_seconds": 30 }
```
**响应：**
```json
{
"id": "uuid",
"status": "completed",
"exit_code": 0,
"stdout": "...",
"stderr": "",
"duration_ms": 412
}
```
### 文件保险箱
```
POST /api/v1/sessions/:id/files 上传文件（multipart）
GET /api/v1/sessions/:id/files 列出文件
GET /api/v1/sessions/:id/files/*path 下载文件
```
### 审计日志
```
GET /api/v1/audit?session_id=... 列出审计日志
```
### 密钥管理
```
POST /api/v1/keys 创建 API 密钥（需要主密钥）
GET /api/v1/keys 列出 API 密钥
```
完整 OpenAPI 规范：[docs/openapi.yaml](docs/openapi.yaml)
## CLI
```bash
export VAULTRUN_API_URL=http://localhost:8080
export VAULTRUN_API_KEY=vr_...
vaultrun session create --image python:3.12-slim --cpu 0.5 --mem 256
vaultrun session list
vaultrun file upload <session-id> ./script.py
vaultrun run <session-id> -- python script.py
vaultrun logs <run-id>
vaultrun session delete <id>
```
## Python SDK
```python
from sandbox_sdk import Client
client = Client("http://localhost:8080", api_key="vr_...")
session = client.create_session(image="python:3.12-slim", memory_limit_mb=256)
client.upload_file(session.id, "script.py", open("script.py", "rb"))
result = client.run(session.id, command="python", args=["script.py"])
print(result.stdout)
client.delete_session(session.id)
```
安装：[`pip install vaultrun-sdk`](https://pypi.org/project/vaultrun-sdk/)
## Go SDK
```go
import vaultrun "github.com/nickvd7/vaultrun/sdk/go"
client := vaultrun.New("http://localhost:8080", "vr_...")
session, _ := client.CreateSession(ctx, vaultrun.CreateSessionOptions{Image: "python:3.12-slim"})
client.UploadFile(ctx, session.ID, "script.py", scriptContent)
run, _ := client.Run(ctx, session.ID, vaultrun.RunOptions{Command: "python", Args: []string{"script.py"}})
fmt.Println(*run.Stdout)
```
## SSO / 身份验证
VaultRun 支持三种身份验证方法：
| 方法 | 方式 | 用例 | 版本 |
|---|---|---|---|
| **API 密钥** | `X-API-Key: vr_…` 头部 | 代理、SDK、CI | 核心（Apache 2.0） |
| **OIDC** | 浏览器重定向到 IdP → 会话 cookie | 仪表盘用户通过 Okta/Azure AD/Google | 企业版 |
| **SAML 2.0** | 浏览器重定向到 IdP → 会话 cookie | 企业 IdP（Okta、AD FS、OneLogin） | 企业版 |
SSO 登录自动配置 VaultRun API 密钥并颁发签名会话 cookie。OIDC 和 SAML 不授予主密钥权限。
SSO 作为 **VaultRun 企业版** 在单独的仓库中编译到 API 服务器中作为覆盖层（`go build -tags enterprise`）。核心构建如果设置了 `OIDC_*`/`SAML_*` 环境变量，则会拒绝启动，因此配置错误的部署会大声失败。
### 如何获取企业版
在 [vaultrun.dev/#enterprise](https://vaultrun.dev/#enterprise) 上选择路径 — 每个请求都会发送电子邮件到 **mail@030.dev**：
1. **评估** — 免费用于开发和测试；请求评估访问权限
2. **许可** — 生产 SSO；包括组织、IdP、实例/席位和时间表
3. **联系我们** — 采购、支持或自定义条款
请参阅 [docs/sso-setup.md](docs/sso-setup.md) 获取逐步设置指南（IdP 注册、证书、测试、故障排除），或 [docs/configuration.md](docs/configuration.md#sso--oidc--openid-connect) 获取环境变量参考。
## 安全
请参阅 [docs/security.md](docs/security.md) 获取完整的安全模型。
- 无 shell 执行 — 命令通过 Docker 执行 API
- 非 root 容器，禁用所有功能
- 默认禁用网络；启用时，每个会话的 iptables 允许列表
- 工作空间层面的路径遍历防护
- API 密钥存储为 SHA-256 哈希值，绝不以明文存储
- 每个操作的 HMAC 签名审计日志
- MCP HTTP 传输的速率限制 + 安全头部
- `MCP_AWS_ENABLED=true` 显式选择加入可防止环境 IAM 凭证激活
- OIDC：PKCE + 状态验证；SAML：XMLDSig 签名验证
- 会话 cookie：`HttpOnly`、`Secure`、`HS256` 签名
## 配置
所有配置均通过环境变量进行。请参阅 [.env.example](.env.example) 和 [docs/configuration.md](docs/configuration.md)。
**API 服务器（必需）：**
| 变量 | 默认值 | 描述 |
|---|---|---|
| `PORT` | `8080` | API 服务器端口 |
| `DATABASE_URL` | — | Postgres DSN（必需） |
| `MASTER_API_KEY` | — | 引导密钥（使用一次，然后禁用） |
**SSO（可选）：**
| 变量 | 描述 |
|---|---|
| `OIDC_ISSUER_URL` | 启用 OIDC — 例如 `https://accounts.google.com` |
| `SAML_IDP_METADATA_URL` | 启用 SAML — IdP 元数据 XML 的 URL |
| `SSO_SESSION_SECRET` | 启用 SSO 时需要 — `openssl rand -hex 32` |
**多区域（可选）：**
| 变量 | 描述 |
|---|---|
| `REGION` | 包含在 `/health` 响应中的区域标签 |
| `DATABASE_READ_URL` | 用于列表/获取查询的读取副本 DSN |
**MCP 服务器** (`MCP_TRANSPORT=http` 额外）：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `MCP_TRANSPORT` | `stdio` | `stdio` 或 `http` |
| `MCP_AUTH_TOKEN` | — | 承载令牌（HTTP 需要） |
| `MCP_PORT` | `:8090` | HTTP 传输的监听地址 |
| `MCP_SQLITE_PATH` | — | SQLite 数据库文件路径 |
| `MCP_PG_DSN` | — | PostgreSQL 连接字符串 |
| `MCP_MONGO_URI` | — | MongoDB 连接 URI |
## 开发
```bash
make test # 单元测试
make test-integration # 集成测试（需要运行的堆栈）
make fmt vet # 格式化 + 校验
make build # 构建 API + CLI 二进制文件
make lint # golangci-lint
# MCP 服务器
go test ./sdk/mcp/...
go build -o vaultrun-mcp ./sdk/mcp/
# CI 运行器
go test ./cmd/ci-runner/...
go build -o ci-runner ./cmd/ci-runner/
```
## 支持和反馈
| 主题 | 渠道 |
|-------|---------|
| **错误和功能请求**（开放核心） | [GitHub 问题](https://github.com/nickvd7/vaultrun/issues/new/choose) |
| **安全漏洞** | 私有 — 请参阅 [SECURITY.md](SECURITY.md) |
| **企业版 / SSO / 许可** | [vaultrun.dev/#contact](https://vaultrun.dev/#contact) → **mail@030.dev** |
请使用问题模板（版本、组件、重现步骤）。不要在问题中留下机密信息。
## 更新日志
请参阅 [CHANGELOG.md](CHANGELOG.md) 获取版本历史。
## 许可
VaultRun 是开放核心：
- 本仓库中的所有内容均在 **Apache 2.0** 许可下 — 请参阅 [LICENSE](LICENSE)。
- **VaultRun 企业版**（SSO：OIDC + SAML 2.0）位于单独的仓库中，遵循 VaultRun 企业版许可。
企业许可和支持： **[vaultrun.dev/#enterprise](https://vaultrun.dev/#enterprise)** → 电子邮件 **mail@030.dev**
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器