Skip to content

deepshape-ai/deepx

BranchesTags

Repository files navigation

deepx

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

Release Go License

介绍 · 核心能力 · 快速开始 · 命令参考 · 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/ 目录里 4 个 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）。

配置凭证

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/ 目录里 4 个 SKILL.md 让 Claude Code 等 agent 即装即用：

Skill 覆盖 触发关键词
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 排序"

数据目录

~/.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/                         4 个 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。

文档

License

MIT，见 LICENSE。

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

v1.0.1 Latest
May 20, 2026
+ 1 release

Packages

 
 
 

Contributors

Languages