VPS 开发工作站 mosabbir-maruf/ai-workstation-cli

AI Workstation

一个安全且可复用的 VPS 开发工作站，具备隔离的 Docker 项目、DeepSeek Harness、GitHub App 身份验证、SSH 预览以及简单的生命周期管理。

正在寻找 Web 控制台？请查看 AI Workstation Web Interface。

目录

- 概述
- 架构
- 安全模型
- 仓库结构
- 主机运行时结构
- 要求
- 克隆仓库
- 安装
- 配置
- GitHub 身份验证
- 日常工作流程
- CLI 参考
- 项目生命周期
- Harness 与 DSH 生命周期
- 预览与 SSH 隧道
- 通过 Cloudflare Tunnel 实现随处访问
- Git 工作流程
- 缓存管理
- 状态备份与恢复
- 更新与升级
- CI/CD
- 运维手册
- 故障排除
- 安全检查清单
- 设计决策
- 快速参考
- 贡献
- 安全
- 许可证
- 维护者

概述

AI Workstation 在远程 Linux VPS 上提供一个可复用的开发环境。
项目仍作为普通 Git 仓库保留在宿主机上的 ~/projects/ 下。只有当前选中的项目会被挂载到工作站容器的 /workspace。

工作站包含常见的开发者运行时和 DeepSeek Harness。DSH 安装和 DSH 状态持久化在一次性容器文件系统之外，从而允许替换容器/镜像而不会意外丢失 Harness 状态。

该系统有四个主要边界：

1. 宿主机管理层 — Docker、项目、运行时状态、密钥以及 ai CLI。
2. 工作站容器 — 隔离的开发者运行时加上所选项目。
3. GitHub 代理 — 通过 Unix 套接字进行 GitHub App 凭据流程，而不是在容器内使用 PAT 或宿主机 SSH 密钥。
4. 现有基础设施 — 现有的网关/反向代理栈保持独立。

架构

高层架构

INTERNET
│
┌──────────────┴──────────────┐
│ │
SSH :1182 HTTPS :443
│ │
▼ ▼
┌────────────┐ ┌─────────────────────┐
│ Mac / Admin│ │ Existing Reverse │
│ Client │ │ Proxy / Nginx │
└─────┬──────┘ └──────────┬──────────┘
│ │
SSH tunnel ▼
│ Existing application stack
▼
┌────────────────────────────────────────────────────────────────────────────┐
│ Ubuntu VPS / Host │
│ │
│ ┌──────────────────────┐ ┌───────────────────────────────────────┐ │
│ │ ~/projects/ │ │ ~/ai-workstation-cli/ │ │
│ │ │ │ │ │
│ │ project-a/ │ │ scripts/ai │ │
│ │ project-b/ │ │ docker/ │ │
│ │ active-project/ ─────┼──────►│ runtime/ │ │
│ │ │ │ secrets/ │ │
│ └──────────┬───────────┘ │ .env │ │
│ │ └────────────────┬──────────────────────┘ │
│ │ │ │
│ │ /workspace mount │ Docker Compose │
│ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ ai-workstation-cli │ │
│ │ │ │
│ │ 用户：sandbox（UID 1001） │ │ │ │ Node.js + Git + SSH client + ripgrep + fd + procps + tini │ │ │ │ │ │ │ │ /workspace ← 仅活动项目 │ │ │ │ /home/sandbox/.dsh ← 持久化 DSH 状态 │ │ │ │ /home/sandbox/.npm-global ← 持久化 DSH 安装 │ │ │ │ │ │ │ │ DSH: 127.0.0.1:4090 │ │ │ │ Bridge: 0.0.0.0:4091 │ │ │ │ App: 项目选择的开发端口 │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ ▲ │ │ │ Unix socket │ │ ┌──────────┴───────────┐ │ │ │ GitHub broker runtime│ │ │ │ github.sock │ │ │ └──────────┬───────────┘ │ │ │ │ │ GitHub App private key │ │ │ │ │ secrets/github-app.pem │ └────────────────────────────────────────────────────────────────────────────┘

数据流

Mac / 操作员 │ │ SSH ▼ 主机 CLI：ai │ ├── 项目选择 ├── Git 操作 ├── 工作站生命周期 ├── Harness 生命周期 ├── 应用生命周期 ├── 缓存维护 └── 预览/隧道生成 │ ▼ Docker 工作站 │ ├── 所选项目位于 /workspace ├── 持久化 DSH 状态 ├── 持久化 DSH 安装 ├── 应用运行时状态 ├── Harness 运行时状态 └── GitHub broker socket

组件职责

| 组件 | 职责 | 持久化 |
| scripts/ai | 主操作员 CLI | Git |
| docker/Dockerfile | 基础工作站镜像 | Git / GHCR |
| docker/compose.yml | 运行时、挂载、限制、端口 | Git |
| docker/entrypoint.sh | 容器引导与 DSH 安装 | Git |
| docker/app-runner.sh | 项目进程运行器 | Git |
| docker/harness.sh | DSH + bridge 生命周期 | Git |
| docker/github-app-credential-helper | 容器端 Git 凭据助手 | Git |
| scripts/lib/github.sh | GitHub App/broker 管理 | Git |
| broker/ | 主机端 broker 实现 | Git |
| runtime/dsh/ | DSH 状态/配置/历史 | 主机持久化 |
| runtime/npm-global/ | DSH 安装 | 主机持久化 |
| runtime/app/ | 应用 PID/日志状态 | 可丢弃 |
| runtime/harness/ | Harness PID/日志状态 | 可丢弃 |
| runtime/github-broker/ | Broker socket/运行时 | 运行时 |
| ~/projects/ | Git 工作副本 | 主机持久化 |
| GitHub Actions | ARM64 镜像构建/发布 | CI |
| GHCR | 容器镜像仓库 | 外部 |

安全模型

该工作站有意与敏感的主机能力隔离。

容器安全

当前运行时配置为：

- 以非 root 用户 sandbox（UID 1001）运行；
- 丢弃所有 Linux capabilities；
- 启用 no-new-privileges；
- 保持非特权；
- 限制内存为 512 MB；
- 限制 CPU 为 1.5 CPUs；
- 限制进程数为 256 PIDs；
- 将 /tmp 用作 noexec,nosuid；
- 避免主机网络；
- 避免主机 Docker socket；
- 避免挂载主机 ~/.ssh；
- 仅将活动项目挂载到 /workspace。

凭据边界

GitHub 凭据无需复制到工作站中。

Git inside container
│
▼
credential helper
│
▼
Unix socket
│
▼
host GitHub broker
│
▼
GitHub App authentication
│
▼
GitHub

凭据助手不会通过 Git 的凭据存储持久化 GitHub tokens。

密钥位置

敏感文件仅存在于主机：

.env
secrets/github-app.pem
runtime/dsh/.credentials.yaml

推荐权限：

.env 600
secrets/github-app.pem 600
runtime/dsh/ 700
runtime/dsh/.credentials... 600

切勿提交私钥、tokens、凭据或 .env。

仓库结构

ai-workstation-cli/
├── .env.example # 环境模板 ├── .gitignore # 忽略的密钥、运行时和 OS 文件 ├── CONTRIBUTING.md # 贡献者指南 ├── LICENSE # MIT 许可证 ├── README.md # 主要架构与用户文档 ├── SECURITY.md # 安全策略与披露流程 ├── install.sh # 主机安装与验证脚本 ├── update.sh # 快进更新与升级脚本 │ ├── .github/ │ ├── ISSUE_TEMPLATE/ │ │ ├── bug_report.yml # 结构化 bug 报告表单 │ │ ├── feature_request.yml # 结构化功能请求表单 │ │ └── config.yml # Issue 模板配置 │ ├── workflows/ │ │ └── image.yml # 多架构 GHCR 构建与发布工作流 │ └── pull_request_template.md # PR 提交模板 │ ├── broker/ │ └── github_broker.py # 宿主机侧 GitHub App 凭据代理 │ ├── config/ │ └── projects.yml # 项目配置注册表 │ ├── docs/ │ ├── github-app-setup.md # GitHub App 密钥操作指南 │ └── cloudflare-tunnel.md # 任意位置访问指南 │ ├── docker/ │ ├── Dockerfile # 基础多架构工作站镜像 │ ├── compose.yml # 运行时/安全配置 │ ├── entrypoint.sh # 容器引导与 DSH 设置 │ ├── app-runner.sh # 应用进程运行器 │ ├── harness.sh # DSH + 桥接生命周期 │ └── github-app-credential-helper# 容器侧凭据助手 │ └── scripts/ ├── ai # 主 CLI ├── github-app-credential-helper # 宿主机侧凭据助手 └── lib/ ├── github.sh # GitHub App/代理助手 ├── tunnel.sh # Cloudflare Tunnel 助手 └── ports.sh # 共享容器端口检测器

[!NOTE]
runtime/、.env、.venv/、secrets/ 以及 ~/projects/ 下的项目检出目录均为本地宿主机运行时路径，有意排除在版本控制之外。

宿主机运行时结构

~/
├── ai-workstation-cli/
│ ├── .env
│ ├── .venv/
│ ├── runtime/
│ │ ├── dsh/
│ │ ├── npm-global/
│ │ ├── app/
│ │ ├── harness/
│ │ └── github-broker/
│ └── secrets/
│ ├── github-app.pem
│ └── cloudflared-token # 隧道连接器令牌（可选） │ └── projects/ ├── project-a/.git ├── project-b/.git └── active-project/.git

只有选定的项目会被挂载到 /workspace。

要求

宿主机

- 带 Docker 的 Linux 宿主机。
- 支持 Docker Compose。
- Git。
- Python 3。
- sudo。
- 对将要管理的仓库具有 GitHub 访问权限。
- 对于已发布的多架构镜像，需要 Linux 宿主机（amd64 或 arm64），否则需在本地进行 Docker 构建。

随附的安装程序会验证 Docker、Git、Python 3、Docker 守护进程访问权限以及 Python 虚拟环境支持。

推荐的服务器配置

- SSH 密钥认证。
- 禁用密码认证。
- 禁用 root SSH 登录。
- 防火墙默认拒绝传入流量。
- 仅开放必需的公共端口。
- 开发端口绑定到 localhost。

克隆仓库

git clone https://github.com/mosabbir-maruf/ai-workstation-cli.git ~/ai-workstation-cli
cd ~/ai-workstation-cli

安装

./install.sh

安装程序会：

1. 验证宿主机先决条件；
2. 如有需要，安装 Python venv 支持；
3. 创建运行时/项目/密钥目录；
4. 从 .env.example 创建 .env；
5. 创建 Python 虚拟环境；
6. 安装所需的 Python 依赖；
7. 将 ai 安装到 /usr/local/bin/ai；
8. 验证安装结果。

然后：

ai doctor
ai github setup
ai github status
ai github test

配置

.env.example 当前包含：

IMAGE=ghcr.io/mosabbir-maruf/ai-workstation-cli:latest
DSH_VERSION=0.1.2-rc.1
ACTIVE_PROJECT=
ACTIVE_PROJECT_PATH=
AI_WORKSTATION_ROOT=
DSH_TRUSTED_HOSTS=
ALLOWED_HOSTS=
GITHUB_APP_ID=
GITHUB_INSTALLATION_ID=
GITHUB_BROKER_SOCKET=
GITHUB_BROKER_GID=
CLOUDFLARED_TOKEN_SET=
CLOUDFLARED_APP_HOSTNAME=
CLOUDFLARED_DSH_HOSTNAME=
CLOUDFLARED_APP_PORT=

CLI 在配置后还会在本地维护 GitHub App/broker 以及隧道相关的值。

规则

- 将 .env 保持私密。
- 切勿提交 .env。
- 将 secrets/github-app.pem 保持私密。
- 将 secrets/cloudflared-token 保持私密。
- 对于受控部署，优先使用受信任/固定版本的镜像引用。
- 当需要确定性行为时，固定 DSH_VERSION。

GitHub 身份验证

GitHub 访问通过 GitHub App 进行代理。不会将 PAT 或 SSH 私钥复制到工作站容器中。

完整操作指南（App 创建、私钥生成、将密钥复制到 VPS、macOS scp 修复）：docs/github-app-setup.md。

快速参考（在 VPS 上）：

ai github setup
ai github status
ai github test

私钥应位于 ~/ai-workstation-cli/secrets/github-app.pem（权限模式 600）。测试正常时会报告：

GitHub authentication: READY ✓

日常工作流程

启动

ai start

检查

ai status

启动活动项目

ai run

预览

ai preview

停止项目

ai app stop

停止工作站

ai stop

典型会话

ai doctor
ai start
ai run
ai preview

Work with DSH / editor / browser

ai app logs
ai status

ai app stop
ai stop

CLI 参考

命令行界面维护于 mosabbir-maruf/ai-workstation-cli。

运行：

ai

以查看内置命令列表。

项目

ai add
ai remove
ai list
ai use

ai add 会将 GitHub HTTPS 仓库克隆到 ~/projects/。

ai use 选择挂载到 /workspace 的项目。

Git

ai pull
ai push "commit message"

ai pull 使用仅快进（fast-forward-only）的 Git 行为。

ai push 在提交/推送之前检查暂存文件名中常见的敏感文件模式。

工作站

ai start
ai stop
ai restart
ai status
ai logs
ai shell
ai run
ai preview

应用

ai app stop
ai app restart
ai app status
ai app logs

Harness

ai harness start
ai harness stop
ai harness restart
ai harness status

DSH

ai dsh version
ai dsh update
ai dsh update

维护

ai cache
ai cache clear
ai cache clear --deps
ai cache clear --deps --yes
ai update
ai upgrade
ai doctor

GitHub

ai github setup
ai github status
ai github test

隧道（任意位置访问，可选）

ai tunnel setup
ai tunnel sync [port]
ai tunnel status
ai tunnel start
ai tunnel stop
ai tunnel logs

状态

ai state export
ai state import

项目生命周期

GitHub 仓库 │ ▼ ai add │ ▼ ~/projects/project-name │ ▼ ai use project-name │ ▼ ACTIVE_PROJECT / ACTIVE_PROJECT_PATH │ ▼ ai start │ ▼ Docker 工作站 │ ▼ ai run │ ▼ 开发服务器 │ ▼ ai preview │ ▼ 通过 SSH 隧道访问 Mac 浏览器

切换项目会复用同一个工作站镜像。

Harness 与 DSH 生命周期

DSH 安装、DSH 状态和 Harness 运行时元数据被有意分开。

runtime/npm-global/
└── DSH 安装

runtime/dsh/
└── DSH 状态/配置/历史

runtime/harness/
└── PID/日志/运行时元数据

在容器内部：

DSH
└── 127.0.0.1:4090
▲
│
│ 本地桥接 │ Bridge └── 0.0.0.0:4091 │ ▼ 主机: 127.0.0.1:4090

这使得 DSH 服务可以保持容器内部运行，同时仍可通过 SSH 隧道在本地访问。

预览与 SSH 隧道

开发端口有意不对外公开。

当前固定的主机绑定包括：

127.0.0.1:3000
127.0.0.1:3001
127.0.0.1:5173
127.0.0.1:8080
127.0.0.1:8000
127.0.0.1:4090 -> container:4091

项目开发服务器可能使用其他端口，例如 5173。

运行：

ai preview

示例：

Detected app port(s): 5173

SSH tunnel command:

ssh -N \
-L 5173:172.20.0.2:5173 \
-L 4090:172.20.0.2:4091 \
mosabbir-cloud

URLs:
App : http://127.0.0.1:5173
DSH : http://127.0.0.1:4090

容器 IP 和应用端口是运行时值，不得硬编码。

通过 Cloudflare Tunnel 实现随处访问

SSH 隧道是默认方式（零公网攻击面）。Cloudflare Tunnel 是可选的替代方案，用于在不从自己的机器运行 SSH 的情况下，从任何地方使用应用和 DSH。一切都在 Cloudflare 仪表板中完成。

完整指南（仪表板设置、路由表单、多应用主机名、故障排除）：docs/cloudflare-tunnel.md。

快速参考（在 VPS 上）：

ai tunnel setup
ai tunnel status
ai preview # prints Anywhere URLs, flags any dashboard port edit

结果：https://app.example.com 和 https://dsh.example.com，各自位于 Cloudflare Access 策略之后。

[!IMPORTANT]
DSH 的设置页面（模型、插件）按上游设计仅限回环访问：在任何非 localhost 地址上，浏览器客户端都会拒绝加载它们（settings are unavailable in this browser），且没有任何服务器或隧道设置能改变这一点。请通过 SSH 地址（http://127.0.0.1:4090，令牌来自 ai preview）一次性输入 API 密钥，然后对其他所有操作（聊天、会话、工作区）使用公共 URL。详情：docs/cloudflare-tunnel.md。

绑定地址（自动）

ai run 会自动将开发服务器绑定到 0.0.0.0，以便 SSH 预览和隧道都能访问它——无需编辑 package.json：

- Vite / Astro / SvelteKit / Nuxt / Angular：追加 --host 0.0.0.0。
- Next.js：追加 -H 0.0.0.0。
- 你在 dev 脚本中自行设置的 --host / -H / 0.0.0.0 始终优先（绝不会被覆盖）。
- 后端应用（Express / Nest / Fastify / Hono / ...）：不会注入任何标志。这些应用默认绑定所有接口，或遵循工作站已导出的 HOST=0.0.0.0 环境变量——只需确保代码没有硬编码 localhost（在指定主机时使用 process.env.HOST）。
- 非 JS 后端（Python / Go / ...）不由 ai run 启动：请手动绑定 0.0.0.0（Flask --host=0.0.0.0，uvicorn --host 0.0.0.0，Django runserver 0.0.0.0:8000 外加 ALLOWED_HOSTS）。

ai run 会打印当前模式：Bind: auto (--host 0.0.0.0) 或 Bind: project config。

Git 工作流

GitHub 是项目源代码的唯一事实来源。

典型工作流：

ai use my-project
ai start
ai run

develop

ai pull
ai push "feat: implement feature"

ai app stop
ai stop

工作站不要求将 PAT 或主机 SSH 私钥挂载到容器中。

缓存管理

检查

ai cache

此命令为只读。

安全清理

ai cache clear

在工作站运行时，清理可回收的 Docker 构建器缓存和 npm 缓存。

它不会有意删除：

- DSH 状态；
- DSH 安装；
- .env；
- Git 仓库；
- Docker 镜像；
- Docker 容器；
- Docker 卷。

依赖清理

ai cache clear --deps

经确认后，删除 ~/projects 下的 node_modules 目录。

非交互式：

ai cache clear --deps --yes

推荐：

ai app stop
ai cache clear --deps
ai run

依赖会根据项目的锁文件重新安装。

状态备份与恢复

项目源代码由 GitHub 保护。DSH 状态是独立的，应单独备份。

导出

ai state export

将状态归档存储在某处受保护的位置，最好存放在主机之外。

导入

ai state import

仅导入受信任的归档。

推荐的恢复流程：

ai stop
ai state import /path/to/backup.tar.gz
ai start
ai dsh version

备份建议在生产/运维环境中，请使用常规加密且异机存放的状态导出副本。

当前系统提供导出/导入功能；自动异地备份仍属于运维职责。

更新与升级

有三个独立的更新层。

CLI/仓库

ai update

或：

./update.sh

工作站镜像

ai upgrade

该镜像从 GHCR 拉取。

仅 DSH

ai dsh update

推荐的 DSH 升级方式：

ai state export
ai dsh update
ai harness restart
ai dsh version

DSH 更新不需要重建基础镜像，因为安装位于持久化的 runtime/npm-global 中。

CI/CD

工作站镜像在 GitHub Actions 中为 Linux amd64 和 arm64 构建。

Push to main
│
▼
.github/workflows/image.yml
│
├── checkout
├── QEMU (multi-arch)
├── Docker Buildx
├── GHCR login
├── build linux/amd64,linux/arm64
├── push :latest
├── push :
├── inspect published images
└── clean old tagged versions

已发布的引用：

ghcr.io/mosabbir-maruf/ai-workstation-cli:latest
ghcr.io/mosabbir-maruf/ai-workstation-cli:

为什么使用 SHA 标签？

latest 很方便。提交 SHA 标签为回滚和调试提供了确定性的镜像引用。

对于受控部署：

IMAGE=ghcr.io/mosabbir-maruf/ai-workstation-cli:

比仅依赖 latest 更可取。

运维手册

每日开始

ai doctor
ai start
ai status
ai run
ai preview

开发期间

ai status
ai app logs
ai harness status
ai shell

切换项目

ai use another-project
ai run
ai preview

配置隧道后，ai preview 还会打印 Anywhere URL，并标记任何仪表盘端口编辑。无需额外命令。

首次任意位置访问（一次性）

仪表盘：

Zero Trust -> Networks -> Tunnels -> Create tunnel (Cloudflared)
-> copy the connector token
Tunnel -> Public hostnames -> Add (after connector is running):
app.example.com -> http://127.0.0.1:
dsh.example.com -> http://127.0.0.1:4090
Zero Trust -> Access -> policy for both hostnames

VPS（连接器安装 = 在 amd64 VPS 上使用 Debian 64 位，在 ARM VPS 上使用 arm64 位）：

ai tunnel setup
ai tunnel status

验证：

ai run
ai preview

从任意位置打开 https://app.example.com 和 https://dsh.example.com。

首次输入 API 密钥（一次性）：DSH 设置页面仅在回环地址上加载，因此请通过 SSH 输入一次密钥 — Mac 终端 ssh -N -L 4090::4091 （IP 来自 ai preview），然后访问 http://127.0.0.1:4090（+ 来自 ai preview 的令牌）→ Settings → Models → Apply。日常使用仍通过公共 URL。

具有任意位置访问权限的新项目（每个项目一次性）

仪表盘：为项目添加一个公共主机名：

.example.com -> http://127.0.0.1:

VPS：无需运行任何与隧道相关的程序。日常切换保持如下：

ai use
ai run
ai preview

一天结束时

ai app stop
ai stop

DSH 升级前

ai state export
ai dsh update
ai harness restart
ai dsh version

工作站重大变更前

ai state export
ai doctor

故障排查

工作站已停止

ai start

然后：

ai status

DSH/Harness 已停止

ai harness status
ai harness restart

如果工作站本身已停止：

ai start

应用启动失败

ai app status
ai app logs

如果依赖需要干净重装：

ai app stop
ai cache clear --deps
ai run

GitHub 认证失败

ai github status
ai github test

检查 broker 和 GitHub App 配置。

不要将 PAT 或主机 SSH 私钥复制到工作站作为变通方案。

如果 ai github test 失败并报 Algorithm 'RS256' could not be found，说明缺少 Python cryptography 后端。修复方法：docs/github-app-setup.md。

隧道失败或提供了错误的端口

ai tunnel status
sudo journalctl -u cloudflared -n 50
ai preview

常见原因：仪表板隧道中缺少公共主机名、切换项目后应用端口错误（ai preview 会打印确切的仪表板编辑内容）、连接器令牌被吊销（重新运行 ai tunnel setup）、开发服务器阻止公共主机名（在 Vite/Next.js 中允许它），或缺少 Cloudflare Access 策略。

预览失败

ai status
ai preview

从客户端机器运行生成的 SSH 命令，并验证应用正在检测到的端口上监听。

镜像问题

docker image ls ghcr.io/mosabbir-maruf/ai-workstation-cli
ai doctor

对于确定性部署，请使用带 SHA 标签的镜像。

安全检查清单

[ ] 已启用 SSH 密钥认证 [ ] 已禁用 SSH 密码认证 [ ] 已禁用 Root SSH 登录 [ ] 防火墙默认拒绝传入 [ ] 仅开放必需的公共端口 [ ] 工作站以非 root 身份运行 [ ] 工作站未启用特权 [ ] 已丢弃所有 Linux capabilities [ ] 已启用 no-new-privileges [ ] 未挂载主机 Docker socket [ ] 未挂载主机 ~/.ssh [ ] 未使用主机网络 [ ] 仅活动项目挂载到 /workspace [ ] .env 未被跟踪 [ ] GitHub 私钥未被跟踪 [ ] Cloudflare Tunnel 令牌未被跟踪 [ ] Cloudflare Access 策略保护隧道主机名 [ ] DSH 凭据受到保护 [ ] GitHub 认证使用 broker/App 流程 [ ] 开发端口仅限 localhost [ ] DSH 状态有恢复备份 [ ] 镜像来源可信

运行：

ai doctor

定期执行。

设计决策

一个工作站，多个项目通用工具应包含在镜像中。项目源码保留在镜像之外，这样新项目就不需要新镜像。

仅挂载活动项目

只有选定的仓库会暴露给工作站。这减少了对无关项目的意外访问。

持久化 DSH 安装

DSH 可以独立于基础工作站镜像进行更新。

持久化 DSH 状态

DSH 状态属于工作流数据，而不是一次性的容器状态，因此它存放在容器之外。

不使用 Docker socket

挂载 /var/run/docker.sock 会让容器获得对宿主机 Docker 守护进程的访问权限，并大大增加影响范围。此架构有意避免这样做。

不使用宿主机 SSH 密钥

GitHub 访问通过代理方式实现，而不是将 ~/.ssh 挂载到工作站中。

仅本地开发端口

Development servers should not accidentally become public services. SSH tunneling provides private operator access.

Prebuilt multi-arch image

The production VPS consumes a prebuilt amd64/arm64 image instead of compiling the image locally.

Quick Reference

PROJECTS
ai add
ai remove
ai list
ai use

GIT
ai pull
ai push "commit message"

WORKSTATION
ai start
ai stop
ai restart
ai status
ai logs
ai shell
ai run
ai preview

APP
ai app stop
ai app restart
ai app status
ai app logs

HARNESS
ai harness start
ai harness stop
ai harness restart
ai harness status

DSH
ai dsh update [version]
ai dsh version

MAINTENANCE
ai cache
ai cache clear
ai cache clear --deps
ai cache clear --deps --yes
ai update
ai upgrade
ai doctor

GITHUB
ai github setup
ai github status
ai github test

TUNNEL
ai tunnel setup
ai tunnel sync [port]
ai tunnel status
ai tunnel start
ai tunnel stop
ai tunnel logs

STATE
ai state export
ai state import

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on development workflow, branch naming, coding standards, shell scripting guidelines, and validation requirements before opening a pull request.

Security

Security is foundational to AI Workstation. To report a security vulnerability or learn more about our container isolation boundaries, credential helper architecture, and defense-in-depth model, please consult SECURITY.md.

License

This project is licensed under the MIT License. See LICENSE for the full license text.

Maintainer

Developed and maintained by Mosabbir Maruf.

GitHub Profile

Maintainer Notes

This repository is the source of truth for the workstation infrastructure and operator tooling.

Keep the following out of Git:

- host runtime state;
- project working copies;
- .env;
- private keys;
- DSH credentials;
- temporary files;
- caches.

Use GitHub for project source and the state export mechanism for DSH/workstation recovery.