deepx

<h1 align="center">deepx</h1>

<p align="center"> GPU 云的统一命令行 — 租机、跑训练、传数据、idle 自动回收。一套命令打通从市场浏览到训练落盘。 </p>

---

deepx 是什么

deepx 是一个面向 GPU 云的统一命令行工具，把租机、SSH、远程拷贝、网盘上传、idle 自动停机等动作收敛到一个二进制。当前后端是 matpool；要接 AWS / vast.ai 等其他云，实现 internal/adapter/types.go 里的 Adapter 接口即可。

deepx 跟普通 CLI 不一样的地方有两点：

1. 命令保持原子性。CLI 不打包"租机+SSH+conda+tmux"这种工作流；复合 SOP 放在

skills/ 让 AI agent 自己组合，业务怎么变形 CLI 都不卡你。 2. release 路径上挡了两道闸门（registry 成员 + 硬白名单），agent 写错脚本或环境变量串味也不会误删生产机器。默认 rent 和 claim 都自动写 guard，临时实验机器才显式 --no-whitelist。

> deepx 同时面向 Claude Code 等 AI agent。skills/ 目录里 5 个 SKILL.md 让 agent > 直接租机器、跑训练、上传 ckpt——无需额外配置。

核心能力

GPU 实例全生命周期

deepx compute market --gpu A30                                # 浏览市场
deepx compute rent   --gpu A30 --name baseline --purpose "PTv3 30ep"
deepx compute exec   mk0001 -- 'tmux new -s train -d "bash /mnt/train.sh"'
deepx compute cp     mk0001 ./code/ remote:/mnt/code/        # SSH 上的 rsync，增量同步
deepx compute cp     mk0001 remote:/mnt/runs/v1/best.pth ./   # 断点续传下载
deepx compute prune                                           # 清掉 stale registry/guard

网盘双向

deepx storage ls    runs                                      # 不需要在跑机器
deepx storage cp    ./model.pth remote:checkpoints/v14/       # 上传到 matpool 网盘
deepx storage cp    remote:datasets/s3dis.zip ./              # 下载
deepx storage quota                                           # 看配额

文件落网盘后，任意机器从 /mnt 直接读，跨会话/跨机器无感。compute cp 走 SSH 上的 rsync（要求机器在跑），storage cp 走 matpool HTTP API（不要求机器在跑）。

idle 自动回收

deepx doctor schedule install --interval 600                  # 装 LaunchAgent / systemd timer
deepx doctor sweep                                            # 手动跑一次（dry-run）
deepx doctor sweep --yes                                      # 真扫真删

后台 reconciler 每 10 分钟读 nvidia-smi + ps，连续 3 tick idle 就 release。

绝大多数机器不会被扫到——默认 rent / claim 都进 guard list。临时实验需带

--no-whitelist 才会成为 sweep 候选。

多 adapter / 凭证三层链

deepx adapter ls                                              # 列所有内置 adapter
deepx adapter use matpool                                     # 切默认 adapter
deepx auth login                                              # 凭证按 3 层链解析

每个 adapter 通过 CredentialSchema() 声明字段，CLI 不写死。matpool 要 USERNAME + PASSWORD，未来 vast.ai 只要 API_KEY。凭证解析顺序：环境变量 → 项目级 .env → 用户级 .env。

单一安全栏杆（hard guard list）

| 写入入口 | 行为 | |---|---| | compute rent | 默认写 guard（purpose 作为 reason）；--no-whitelist 关闭 | | compute claim | 永远写 guard——claim 的语义就是"长期持有" | | compute guard add | 显式手动 add（少用，因为前两条已覆盖大多数情况） | | compute prune | 唯一的自动删除入口；只删 adapter 已确认死亡的条目 |

详见 docs/SAFETY.md。

快速开始

安装

macOS / Linux —— 一键装（amd64 / arm64 自动识别）：

curl -fsSL https://raw.githubusercontent.com/deepshape-ai/deepx/main/scripts/install.sh | bash

默认装到 $HOME/.local/bin/deepx。重跑同一条命令即升级到最新 release，同版本自动跳过。脚本会用 release 一起发布的 checksums.txt 校验 sha256。

Windows —— 去 Releases 下

deepx_<ver>_windows-amd64.zip，解压后把 deepx.exe 放进 PATH。

从源码构建（开发者）：

git clone https://github.com/deepshape-ai/deepx.git
cd deepx && make install                                      # → $HOME/.local/bin/deepx
BIN_DIR=/opt/local/bin make install                           # 自定义目录

make build / make install 都先跑 scripts/preflight.sh 校验 GOROOT / GOPROXY—— 出问题不偷改 env，直接退出并打印修复命令。单二进制无运行时依赖（除系统 ssh 与可选 sshpass）。

作为 Claude Code plugin 安装

deepx 同时是一个 Claude Code plugin（打包 5 个 skill，见下方「AI 技能集成」）。

marketplace 一键装：

/plugin marketplace add deepshape-ai/deepx
/plugin install deepx

或直接拷 skill 文件：

git clone https://github.com/deepshape-ai/deepx.git /tmp/deepx
mkdir -p ~/.claude/skills && cp -r /tmp/deepx/skills/deepx-* ~/.claude/skills/

重启 Claude Code 即生效。

配置凭证

matpool 需要 USERNAME（手机号）+ PASSWORD。三层 fallback，命中即用：

# 方式 1：环境变量
export DEEPX_MATPOOL_USERNAME=13800138000
export DEEPX_MATPOOL_PASSWORD=...

# 方式 2：项目本地 .env
echo 'USERNAME=13800138000'  >  .deepx/secrets.matpool.env
echo 'PASSWORD=...'          >> .deepx/secrets.matpool.env

# 方式 3：全局 .env（chmod 600）
mkdir -p ~/.config/deepx/secrets
echo 'USERNAME=13800138000'  >  ~/.config/deepx/secrets/matpool.env
echo 'PASSWORD=...'          >> ~/.config/deepx/secrets/matpool.env
chmod 600 ~/.config/deepx/secrets/matpool.env

deepx auth login                                              # 逐字段打印命中来源

env 文件写裸键（USERNAME=…，不带 DEEPX_MATPOOL_ 前缀），KEY=VALUE 和

export KEY=VALUE 都行。mode > 0600 时 stderr 警告。

五分钟跑通

deepx auth login
deepx compute market --gpu A30
deepx compute rent  --gpu A30 --name baseline --purpose "PTv3 30ep"     # → mk0001
deepx compute exec  mk0001 -- 'tmux new -s train -d "bash /mnt/train.sh"'
deepx compute cp    mk0001 ./code/ remote:/mnt/code/
deepx status                                                            # 一屏总览

deepx --help 看完整命令树，docs/COMMANDS.md 是逐 flag 参考。

命令参考

| 分组 | 子命令 | |---|---| | auth | login / logout | | adapter | ls / use <name> / info [name] / test | | compute | ls · market · rent · release · claim · stat · exec · cp · prune · snapshot {ls,info} · guard {add,ls} | | storage | ls [path] · quota · cp <src> <dst> · rm <path>... | | balance | show | | doctor | health · sweep · schedule {install,uninstall} | | status | [adapter\|auth\|compute\|doctor] —— --json 形状稳定 |

AI 技能集成

skills/ 目录里 5 个 SKILL.md 让 Claude Code 等 agent 即装即用：

| Skill | 覆盖 | 触发关键词 | |---|---|---| | deepx-auto-research | long-horizon 总编排 / 10 铁律 / 8 阶段 SOP / 训推一体 / 部署 SOP | "auto research"、"端到端训练上线"、"训推一体"、"long-horizon" | | deepx-machine | 租机/SSH/cp/release/balance/prune | "租 GPU"、"租服务器"、"开机器跑训练" | | deepx-storage | matpool 网盘 ls/quota/cp/rm | "上传到网盘"、"下载 ckpt" | | deepx-recycle | doctor sweep / schedule / 调阈值 | "自动停机"、"sweep 误杀"、"防止 GPU 忘关" | | deepx-experiment | 实验落盘规范 / 多 agent 协调 | "实验记录"、"多 agent 实验"、"ROI 排序" |

deepx-auto-research 是总编排层 —— 把上面 4 个分项 skill 串成一个能跨天、能跨失败、能安全上生产的 long-horizon 闭环。

数据目录

~/.config/deepx/
├── config.toml                  默认 adapter
├── guard.toml                   硬白名单（rent / claim 自动写；prune 自动删 stale）
├── secrets/<adapter>.env        chmod 600
└── state/
    ├── state.json               registry（原子写 + .bak 兜底）
    ├── token-<adapter>.json     token 缓存（按 adapter 分隔）
    ├── audit.jsonl              rent / release / claim / guard-add / guard-prune 审计
    └── doctor-state.json        sweep 状态

audit.jsonl 每行一条 JSON，超 ~1 MiB 原子重写为最近 5000 条；LaunchAgent / systemd 写出的 doctor.{stdout,stderr}.log 每次 sweep 起始 size-check，超 ~5 MiB 改名 .1。

安全模型

release 类操作必须依次通过两道独立闸门：

1. Registry 成员：release 只动本 CLI 租的机器，不在 ~/.config/deepx/state/state.json 的 ID 一律拒绝。 2. 硬白名单：~/.config/deepx/guard.toml 内的机器永不释放。

写入：rent（默认）/ claim（无条件）/ guard add（手动）
删除：活的条目只能手动改文件——CLI 不提供 guard remove。

compute prune 自动剪掉 adapter 已确认死亡的条目（唯一的自动删除路径，audit 留痕）

详见 docs/SAFETY.md。

仓库布局

cmd/deepx/                      CLI 入口，每 namespace 一个文件
internal/adapter/               Adapter 接口 + matpool 实现（含 fs.go 网盘）
internal/{auth,config,doctor,
  guard,ssh,state}/             凭证 / 路径 / idle sweep / 硬白名单 / ssh argv / registry
skills/                         5 个 SKILL.md 给 agent 用
docs/                           ARCHITECTURE / SAFETY / TESTING / COMMANDS / ADAPTERS
scripts/                        preflight.sh / install.sh（远程一键装）/ uninstall.sh
Makefile                        build / test / install / release（5 平台 cross-compile）
.github/workflows/              ci.yml (PR 跑测试+5 平台 build) / release.yml (tag 触发发版)

开发

make build                      # → dist/deepx
make test                       # 单元测试，无网络
make test-integration           # 真 matpool 端到端：login → market → rent → exec → cp → release（≤5 分钟）
make release                    # cross-compile 5 平台 → dist/release/*.{tar.gz,zip} + checksums.txt
make fmt vet tidy

# 发版（仅 maintainer）
git tag v1.2.3 && git push --tags    # → release.yml 自动 build + 发 GitHub Release

make test-integration 把 deepx 二进制当 subprocess 跑全链路，凭证按

DEEPX_<ADAPTER>_<FIELD> 注入。怎么进 shell（direnv / 源 .env / rc 文件 / CI secret）由用户自定。两个无凭证安全测试（registry 拒绝、guard 拒绝）无条件跑。详见 docs/TESTING.md。

文档

docs/ARCHITECTURE.md — 模块布局、adapter 契约、状态写入安全
docs/SAFETY.md — 安全栏杆、确认门、审计、凭证
docs/COMMANDS.md — 全部命令、flag、环境变量
docs/ADAPTERS.md — 新增云后端的步骤
docs/TESTING.md — 测试契约
skills/*/SKILL.md — agent SOP

License

MIT，见 LICENSE。

Summary

Install to Claude Code