Allox CLI

面向 AI Agent 的可恢复执行工作区

从环境创建、任务执行到断点恢复，用一套 CLI 完成完整 Agent 工作流。

Features · Quick Start · Demo · Tests · Documentation

Allox 将隔离环境、Agent 工具、文件传输、当前会话和 Checkpoint 恢复统一到一个命令入口。它既适合开发者在终端交互使用，也提供稳定的结构化输出供 Agent、脚本和 CI 调用。

Features

可恢复工作区：支持手动、定时和操作成功后的 Checkpoint，可恢复 latest 或指定版本。
Stateful Session：创建或恢复后自动选中当前环境；后续命令可以省略 ID，销毁后自动清理。
Agent-ready 工具集：统一使用 Shell、File、Browser、Jupyter、Screenshot 和 MCP 能力。
Runtime Readiness：等待 Agent 服务真正可用，而不只是等待容器启动，并报告就绪耗时。
可靠文件传输：支持二进制流式与递归传输；下载使用临时 staging，并拒绝符号链接和路径逃逸。
MCP 原生入口：发现 MCP Server、列出工具并直接调用。
多环境配置：通过 Profile 切换 dev、staging、prod、自定义镜像或轻量执行环境。
自动化友好：按场景提供 table、json、yaml 和 raw 输出。

Quick Start

Install

当前版本从源码安装：

git clone https://github.com/AlloxOrg/allox-cli.git
cd allox-cli

uv sync --no-editable

激活虚拟环境：

# Linux / macOS
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

验证安装：

allox-cli --version
allox-cli --help

不激活虚拟环境时，可使用 uv run --no-editable allox-cli ...。开发中修改 src/allox_cli 后，执行：

uv sync --reinstall-package allox-cli

不建议直接执行 uv run allox-cli：它可能将项目切换为 editable 安装，覆盖当前安装方式。

Configure

Allox 当前使用 OpenSandbox 管理环境生命周期，默认使用 AIO Sandbox 提供 Agent Runtime。两者都需要在本机准备，但不需要手动运行它们的源码：OpenSandbox Server 通过 Python 包安装并作为本地服务启动，AIO Sandbox 通过 Docker 拉取并由 Server 按需创建。开始前请确认 Docker 已运行。

Start the Server

# 安装到当前 uv 虚拟环境
uv pip install opensandbox-server

# 生成本地 Server 配置并启动
opensandbox-server init-config ~/.sandbox.toml --example docker
opensandbox-server

在另一个终端验证：

curl http://127.0.0.1:8080/health
# {"status":"healthy"}

生产环境应在 ~/.sandbox.toml 中配置 API Key。仅限本地开发且明确接受无鉴权风险时，可设置 OPENSANDBOX_INSECURE_SERVER=YES。

Pull the Default Image

# 下载默认 Agent Runtime 到本机 Docker
docker pull ghcr.io/agent-infra/sandbox:latest

生产环境应固定具体 tag，避免使用 latest。

Initialize Allox

allox-cli config init
allox-cli config set connection.domain localhost:8080
allox-cli config set connection.protocol http
allox-cli config show

如果服务端开启了鉴权：

allox-cli config set connection.api_key YOUR_API_KEY

Allox 会依次读取命令行选项、环境变量、本地配置文件和内置默认配置，位置靠前的设置会覆盖后面的设置。需要在不同环境间切换时，可通过 --profile dev|staging|prod|custom|code 选择对应的 ~/.allox/<profile>.toml 配置文件。

Demo: End-to-End Agent Workflows

以下示例默认已经完成安装与配置。先确认 Docker、服务端和 Allox 配置可用：

docker info
curl http://127.0.0.1:8080/health
allox-cli config show

1. Complete Agent Workflow

创建环境后，Allox 会自动将其记录为当前 session。下面的操作均不需要重复传入 sandbox_id：

# 创建环境并等待 Runtime 就绪
allox-cli sandbox create --timeout 30m -o json
allox-cli session current -o json

# Shell
allox-cli aio exec -- python3 -c "print('hello from allox')"

# Jupyter；结果应包含 status: ok 和输出 4
allox-cli aio jupyter run -c "print(2 + 2)" -o json

# Browser；输出 CDP/VNC 地址，并保存截图到本地
allox-cli aio browser info -o json
allox-cli aio screenshot -f allox-demo.png -o json

# 单文件上传、读取和下载
allox-cli file upload ./README.md /tmp/allox-README.md -o json
allox-cli aio read /tmp/allox-README.md
allox-cli file download /tmp/allox-README.md ./README.from-allox.md -o json

# 递归目录传输
mkdir -p .allox-demo/nested
printf "hello\n" > .allox-demo/nested/result.txt
allox-cli file upload --recursive ./.allox-demo /tmp/allox-demo -o json
allox-cli file download --recursive /tmp/allox-demo ./allox-demo-output -o json

# 销毁当前环境；current session 会被自动清除
allox-cli sandbox kill -o json

# 预期提示不存在当前 session
allox-cli session current

# 本地生成：allox-demo.png、README.from-allox.md、.allox-demo/、allox-demo-output/
# 确认结果后可自行删除

2. Checkpoint and Restore

下面的 Bash 示例使用 jq 从 JSON 输出中读取 ID，完整演示“保存 V1 → 修改为 V2 → 恢复 V1 → 验证 → 清理”：

# 创建源环境并记录 ID
SOURCE_ID=$(allox-cli sandbox create --timeout 30m -o json | jq -r '.id')

# 写入 V1 并保存 Checkpoint
allox-cli aio exec -- sh -c "echo v1 > /home/gem/version.txt"
CHECKPOINT_ID=$(allox-cli checkpoint create --name v1 -o json | jq -r '.id')

# 将当前工作区修改为 V2
allox-cli aio exec -- sh -c "echo v2 > /home/gem/version.txt"
allox-cli checkpoint list -o json

# 从 V1 Checkpoint 创建新环境，并自动切换 current session
RESTORED_ID=$(allox-cli checkpoint restore "$CHECKPOINT_ID" --timeout 30m -o json | jq -r '.id')

# 预期输出 v1
allox-cli aio exec -- cat /home/gem/version.txt

# 恢复会创建新环境，不会覆盖或销毁源环境
# 因此需要删除 Checkpoint，并显式清理恢复环境和源环境
allox-cli checkpoint delete "$CHECKPOINT_ID" -o json
allox-cli sandbox kill "$RESTORED_ID" -o json
allox-cli sandbox kill "$SOURCE_ID" -o json

3. Automatic Checkpoint

在 ~/.allox/config.toml 中启用后，Allox 只在指定操作成功时创建 Checkpoint：

# ~/.allox/config.toml
[checkpoint]
enabled = true
on_success = true
operations = ["run", "file.write", "file.upload", "aio.exec", "aio.jupyter"]
interval = "5m"
strict = false

也可以为当前 session 运行前台定时保存：

allox-cli checkpoint watch --interval 5m

strict = false 表示自动保存失败只产生警告，不改变原操作的成功结果。watch 会持续运行，按 Ctrl+C 停止。

4. MCP Discovery and Call

MCP Server 和工具随运行镜像而变化，调用前应先发现实际能力：

# 创建环境（如当前已有 session，可省略）
allox-cli sandbox create --timeout 30m -o json

# 发现 Server 和完整工具名
allox-cli aio mcp servers -o json
allox-cli aio mcp tools browser -o json

# 调用浏览器工具；具体工具名以 tools 输出为准
allox-cli aio mcp call browser browser_navigate \
  --args '{"url":"https://example.com"}'

allox-cli sandbox kill -o json

部分镜像没有启用全部 MCP Server，出现 404 不代表环境生命周期异常。Shell 和文件操作可分别回退到 allox-cli aio exec、allox-cli aio read 或 allox-cli file *。

详见 MCP Server 使用说明。

Command Reference

命令	用途
`allox-cli sandbox create/list/get/endpoint/renew/pause/resume/kill`	环境生命周期
`allox-cli session current/use/clear`	当前工作环境
`allox-cli aio exec/read/screenshot`	Shell、文件读取与截图
`allox-cli aio jupyter run`	Jupyter 代码执行
`allox-cli aio browser info`	获取 CDP/VNC 信息
`allox-cli aio mcp servers/tools/call`	MCP 发现与调用
`allox-cli checkpoint create/list/restore/delete/watch`	工作区保存与恢复
`allox-cli run`	通用命令执行
`allox-cli file cat/write/upload/download`	文件操作与传输
`allox-cli config init/show/set/path`	本地配置

使用 allox-cli <command> --help 查看完整参数。

Tests: Validation and Quality

Unit Tests

无需 Docker 或正在运行的服务端：

uv run pytest -m "not integration" -q
uv run ruff check src tests

End-to-End

准备完整运行环境后执行：

uv run pytest -m integration tests/test_integration_e2e.py -v

覆盖流程：

create → exec → screenshot → Jupyter → browser info
       → file upload/download → recursive transfer → kill

其他集成测试：

# MCP
uv run pytest -m integration tests/test_integration_mcp.py -v

# 自定义 Runtime image；先执行 docker/build.sh
uv run pytest -m integration tests/test_integration_custom_image.py -v

Documentation

MCP Server 使用说明介绍 MCP Server 发现、工具列表与调用流程。

自定义镜像指南说明如何构建和验证自定义 Runtime image；Code Interpreter 指南介绍轻量 Code Interpreter 镜像的配置与使用方式。

测试与验收记录按阶段整理：Phase 1覆盖基础生命周期与工具能力，Phase 2覆盖 Session、Profile、MCP 与脚本化能力，Phase 3覆盖自定义镜像。

Built With

Python 3.10+ — 主要开发语言。
Click — CLI 命令、参数解析与上下文管理。
Rich — 终端表格、状态面板和交互输出。
HTTPX — Runtime 健康检查与 HTTP 通信。
OpenSandbox — 环境生命周期、endpoint、execd、snapshot 与隔离能力。
AIO Sandbox — Shell、File、Browser、Jupyter、MCP 与 VSCode Agent Runtime。
Docker — 本地容器运行环境。
uv 与 Hatchling — 依赖管理、虚拟环境和 Python 包构建。
pytest 与 Ruff — 自动化测试、Lint 和代码质量检查。

License

Apache-2.0。完整许可证文本见 Apache License 2.0。

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assert		assert
assets		assets
docker		docker
docs		docs
examples/profiles		examples/profiles
src/allox_cli		src/allox_cli
tests		tests
.gitignore		.gitignore
.python-version		.python-version
README.md		README.md
pre_doc.md		pre_doc.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository navigation

About

Repository files navigation

Allox CLI

Features

Quick Start

Install

Configure

Start the Server

Pull the Default Image

Initialize Allox

Demo: End-to-End Agent Workflows

1. Complete Agent Workflow

2. Checkpoint and Restore

3. Automatic Checkpoint

4. MCP Discovery and Call

Command Reference

Tests: Validation and Quality

Unit Tests

End-to-End

Documentation

Built With

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Allox CLI

Features

Quick Start

Install

Configure

Start the Server

Pull the Default Image

Initialize Allox

Demo: End-to-End Agent Workflows

1. Complete Agent Workflow

2. Checkpoint and Restore

3. Automatic Checkpoint

4. MCP Discovery and Call

Command Reference

Tests: Validation and Quality

Unit Tests

End-to-End

Documentation

Built With

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages