deepx

deepx

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

介绍 · 核心能力 · 快速开始 · 命令参考 · AI 技能 · 安全

---

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