ExecGo 生态中的数据面运行时：用 Rust 实现任务的异步提交、调度、执行与持久化，对外提供 HTTP API 与 CLI，可作为 ExecGo 控制面背后的执行后端。
它面向的核心场景是为通用或成熟 Agent 提供可靠执行底座：Claude Code、Codex、Hermes Agent、OpenClaw 等上层 agent 继续负责规划与工具选择，ExecGo 控制面负责任务治理，execgo-runtime 负责把进程级真实执行落盘、隔离、取消、审计和恢复。
当前版本：1.1.0（详见 版本与标签）。
execgo-runtime 在单进程中托管 HTTP 服务，通过 SQLite（WAL）与任务目录持久化状态；调度器将队列中的任务派发到 internal shim 子进程执行用户命令或脚本。runtime 采用“单一版本、多能力面”的设计：启动时探测宿主环境，暴露 capability manifest，并在任务提交时解析 requested/effective execution plan。支持健康检查、就绪探针、Prometheus 指标、任务取消与超时控制、本机资源账本，以及 Linux 上可选的 linux_sandbox 与 cgroup 能力（详见 架构说明）。
在 Agent 接入链路中，runtime 不理解自然语言，也不替代 Agent 的决策循环。它只接收明确的执行请求，并提供稳定的任务 ID、状态机、stdout/stderr、result、事件与资源/沙箱审计信息，让上层 Agent 可以把执行结果继续用于后续推理或回放。
一条任务的关键链路如下：
POST /api/v1/tasks
-> validate request
-> resolve execution_plan
-> write SQLite + tasks/<id>/request.json
-> ResourceLedger reservation
-> fork internal-shim
-> run command/script
-> write result.json + stdout.log + stderr.log
-> GET status/events/metrics
这意味着 runtime 的边界非常明确：HTTP 服务负责接收、调度、恢复和观测，internal shim 负责真实进程执行；上层 ExecGo/Agent 负责规划、重试策略和业务语义。
| 能力 | 说明 |
|---|---|
| HTTP API | 提交任务、查询状态、取消、事件流、健康检查、Prometheus 指标 |
| CLI | serve / submit / status / wait / kill / run |
| 持久化 | SQLite 元数据；tasks/<id>/ 下 request.json、result.json、stdout/stderr |
| 调度与恢复 | shim 子进程执行；重启后可对非终态任务做恢复相关处理 |
| 自适应能力 | 环境探测、capability API、显式降级、requested/effective execution plan |
| 资源与沙箱 | 默认进程级；Linux 可选 linux_sandbox（命名空间、cgroup 等）；本机 ResourceLedger 做 reservation/release |
| 治理语义 | control_context.tenant 支持租户软配额聚合；control_context.owner 支持 owner-gated kill |
| 项目 | 说明 |
|---|---|
| Rust | 1.74+（MSRV；建议当前 stable，与 CI 一致。edition = "2021" 表示语言 edition，不是 Rust 工具链版本） |
| 操作系统 | 开发与 CI 覆盖 Linux、macOS；沙箱 / cgroup 完整能力仅在 Linux |
| 平台 | 依赖 Unix 进程组、信号、wait4 等；Windows 非目标平台 |
cargo install execgo-runtime --version 1.1.0git clone https://github.com/iammm0/execgo-runtime.git
cd execgo-runtime
cargo build --release
# 二进制：target/release/execgo-runtime从 GitHub Container Registry 拉取（main 分支成功构建后可用）：
docker pull ghcr.io/iammm0/execgo-runtime:latest
docker run --rm -p 8080:8080 -v execgo-data:/data ghcr.io/iammm0/execgo-runtime:latest或从源码本地构建：
docker build -t execgo-runtime:local .
docker run --rm -p 8080:8080 -v execgo-data:/data execgo-runtime:local默认监听 0.0.0.0:8080，数据目录 /data。详见 部署说明。
cargo build --release
cargo testcargo run -- serve --listen-addr 127.0.0.1:8080 --data-dir ./data数据目录下会生成 runtime.db 与 tasks/<task_id>/。
cargo run -- submit --json '{"execution":{"kind":"command","program":"/bin/sh","args":["-c","echo hello"]}}'cargo run -- run --json '{
"execution": {
"kind": "command",
"program": "/bin/sh",
"args": ["-c", "echo $GREETING && sleep 1"],
"env": {
"GREETING": "hello from execgo-runtime"
}
},
"limits": {
"wall_time_ms": 30000,
"memory_bytes": 536870912,
"pids_max": 32,
"stdout_max_bytes": 65536,
"stderr_max_bytes": 65536
},
"sandbox": {
"profile": "process",
"workspace_subdir": "quickstart"
},
"control_context": {
"tenant": "demo",
"owner": "local-user",
"control_plane_mode": "manual"
},
"metadata": {
"purpose": "quickstart"
}
}'运行结束后可查看：
curl -sS http://127.0.0.1:8080/api/v1/runtime/resources
curl -sS http://127.0.0.1:8080/api/v1/tasks/<task_id>/events
ls -la ./data/tasks/<task_id>如果任务带 control_context.owner，取消时需要传入匹配 owner：
cargo run -- kill --owner local-user <task_id>chmod +x scripts/quickstart.sh
./scripts/quickstart.sh在临时目录启动服务、提交任务并等待结束，退出时清理。
| 子命令 | 作用 |
|---|---|
serve |
启动 HTTP 服务（serve --help 查看全部参数） |
submit |
提交任务（--json 或 --file） |
status <task_id> |
查询状态 |
wait <task_id> |
轮询至终态（可选 --timeout-ms） |
kill <task_id> |
请求取消 |
run |
提交并等待完成（submit + wait） |
默认 --server http://127.0.0.1:8080。
| 变量 | 说明 |
|---|---|
RUST_LOG |
日志级别，如 info、debug；未设置时由程序默认 tracing 配置 |
EXECGO_RUNTIME_URL |
在 ExecGo 控制面配置：指向本服务根 URL（无尾斜杠亦可） |
EXECGO_RUNTIME_ID |
可选：覆盖 runtime 节点 ID |
EXECGO_RUNTIME_DEFAULT_CAPABILITY_MODE |
可选：默认 capability 策略，adaptive 或 strict |
EXECGO_RUNTIME_DISABLE_LINUX_SANDBOX |
可选：禁用 Linux sandbox 探测能力 |
EXECGO_RUNTIME_DISABLE_CGROUP |
可选：禁用 cgroup 能力 |
EXECGO_RUNTIME_CAPACITY_MEMORY_BYTES / EXECGO_RUNTIME_CAPACITY_PIDS |
可选：覆盖 ResourceLedger 容量探测 |
EXECGO_RUNTIME_OWNER |
可选：CLI kill 默认 owner header |
服务端常用参数见 CLI 文档（并发上限、队列长度、GC、grace 时间等）。
租户软配额通过 serve --tenant-quota 配置，例如：
cargo run -- serve \
--listen-addr 127.0.0.1:8080 \
--data-dir ./data \
--tenant-quota demo=slots:2,memory:1073741824,pids:128配额只在任务设置了匹配的 control_context.tenant 时生效。
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/api/v1/tasks |
提交任务 |
GET |
/api/v1/tasks/:id |
任务状态（含输出片段） |
POST |
/api/v1/tasks/:id/kill |
取消 |
GET |
/api/v1/tasks/:id/events |
事件列表 |
GET |
/api/v1/runtime/info |
runtime ID、版本、启动时间与平台摘要 |
GET |
/api/v1/runtime/capabilities |
宿主环境探测结果、基础语义、增强能力、降级告警 |
GET |
/api/v1/runtime/config |
非敏感运行配置摘要 |
GET |
/api/v1/runtime/resources |
本机资源 capacity/reserved/available 与活动 reservation |
GET |
/healthz |
存活（响应中含 version） |
GET |
/readyz |
就绪（校验存储） |
GET |
/metrics |
Prometheus 文本 |
完整 JSON 模型与示例见 API 参考。
在 ExecGo 中设置环境变量：
EXECGO_RUNTIME_URL=http://127.0.0.1:8080
指向正在运行的 execgo-runtime 根地址；控制面通过该 URL 调用上述 API。
推荐链路：
- 通用 Agent 通过 ExecGo adapter 提交结构化 action。
- ExecGo 将需要进程执行、资源限制或沙箱策略的 action 翻译为
type=runtime任务。 execgo-runtime执行任务并持久化 request/result/stdout/stderr。- ExecGo 将状态与结果归一化返回给 Agent，用于继续推理、重试、取消或审计。
| 文档 | 内容 |
|---|---|
| docs/README.md | 文档索引 |
| docs/architecture.md | 架构与执行流程 |
| docs/api.md | HTTP API 与 JSON |
| docs/cli.md | 命令行参数 |
| docs/deployment.md | 部署、Docker、CI/CD、标签 |
| docs/development.md | 本地开发、测试、风格 |
欢迎通过 Issues 反馈缺陷与需求，通过 Pull Request 提交改动。
建议流程：
- Fork 本仓库，从
main创建分支。 - 本地执行
cargo fmt、cargo clippy --all-targets --all-features -- -D warnings、cargo test。 - 提交信息清晰说明动机与行为变化（可与 development.md 对齐）。
- 发起 PR，等待 CI 通过后再合并。
若你认为发现了安全漏洞，请不要在公开 Issue 中讨论；请通过仓库维护者提供的私密渠道报告（可在 GitHub 用户主页或组织说明中查找联系方式）。在未有 SECURITY.md 前，也可先开 私有 沟通渠道联系维护者。
本项目使用 MIT 许可证发布，完整条款见仓库根目录的 LICENSE 文件。