siamakerlab/vibe-coder-server

Vibe Coder Server

可自托管的Android开发服务器，将Claude Code、Gradle和Git作为子进程协调运行。 单Docker容器，仅需浏览器操作，可选Android companion客户端。在PC上启动后登录即可创建项目、发送提示、构建并下载APK——操作者无需本地安装SDK、JDK或Gradle。

快速参考

• 源码: https://github.com/siamakerlab/vibe-coder-server
• 维基（Android客户端指南、REST API、MCP目录）: https://github.com/siamakerlab/vibe-coder-server/wiki
• 问题反馈: https://github.com/siamakerlab/vibe-coder-server/issues
• 架构: linux/amd64, linux/arm64
• 最新标签: 0.10.0, latest
• 镜像大小: ~600 MB（Android SDK/Gradle/MCP包存储在绑定挂载卷中——见下文）
• 许可证: AGPL-3.0

快速开始（3分钟）

bash
mkdir -p ~/vibe-coder && cd ~/vibe-coder

curl -fsSL https://raw.githubusercontent.com/siamakerlab/vibe-coder-server/main/docker/compose.yml -o compose.yml
curl -fsSL https://raw.githubusercontent.com/siamakerlab/vibe-coder-server/main/docker/.env.example -o .env

# 编辑.env: 设置PUID/PGID（通过id -u; id -g获取）和主机端口，默认值也可直接使用
docker compose up -d

# 1. 浏览器访问 → http://<PC IP>:17880/setup （创建首个管理员用户）
# 2. 构建环境 → "Install/update all"（安装Android SDK，约5-15分钟）
# 3. 构建环境 → Claude登录卡片 → 选择4种方式之一
# 4. 项目 → 新建项目（空项目或Git克隆）→ 控制台/构建/下载

包含组件（v0.10.0）

• Claude Code CLI编排：每个项目一个持久子进程，流JSON IO，通过WebSocket中继实时控制台。
• 四种Claude认证方式：终端、文件上传、API密钥，以及半自动Web OAuth（script -q PTY包装，无需xterm.js）。
• 含60+服务器的MCP目录：10个分类，多选复选框，每个MCP的令牌表单，推荐★标记，信任等级。
• 一键构建环境安装器：Android SDK/Gradle缓存/Node+Claude CLI/MCP包，持久化到一个主机目录。
• 项目注册时Git克隆：支持公开+私有仓库（HTTPS PAT或自动生成ed25519 SSH密钥）。
• JSON API对等支持：所有浏览器功能均通过/api/*提供Bearer认证，供Android companion或第三方自动化使用。

镜像布局（~600 MB）

未捆绑（操作者首次运行时通过/env-setup页面安装到卷中）：

• Android SDK（~3-4 GB）
• Gradle依赖缓存（首次构建约1-2 GB）
• Claude OAuth凭证/API密钥
• 目录中的MCP服务器（npm install -g <pkg>）
• Playwright浏览器（可选，~300 MB）

配置（.env）

卷布局（v0.7.0+ 统一模式）

所有持久化数据存储在一个主机目录（./vibe-coder-data/）中。使用tar打包即可备份所有内容：工作区+数据库+Android SDK+Gradle+MCP+Playwright+Claude认证。

${VIBE_DATA_ROOT}/                          容器内路径
─────────────────                           ─────────
├── workspace/                  →  /workspace                       （源码+APK）
├── server/                     →  /data                            （SQLite+日志）
├── dev-tools/
│   ├── android-sdk/            →  /opt/android-sdk                 （3-4 GB）
│   ├── gradle/                 →  /home/vibe/.gradle               （1-2 GB）
│   ├── npm-global/             →  /home/vibe/.local                （MCP包）
│   ├── npm-cache/              →  /home/vibe/.npm                  （npx缓存）
│   ├── playwright/             →  /home/vibe/.cache/ms-playwright  （可选）
│   └── config/                 →  /home/vibe/.config               （工具配置）
└── claude/                     →  /home/vibe/.claude               （OAuth/API密钥/MCP注册）

v0.7.0修复了数据丢失bug：v0.7.0前MCP服务器存储在镜像的系统目录（/usr/local/lib/node_modules），导致docker compose pull && up -d时丢失。v0.7.0+将其路由到绑定挂载卷。详见维基的https://github.com/siamakerlab/vibe-coder-server/wiki/Upgrade-Guide%E3%80%82

备份与迁移

bash
docker compose stop
tar czf vibe-coder-data-$(date +%F).tar.gz vibe-coder-data/
docker compose start

# 在另一台机器上
scp vibe-coder-data-*.tar.gz user@newhost:~/vibe-coder/
ssh user@newhost 'cd ~/vibe-coder && tar xzf vibe-coder-data-*.tar.gz && docker compose up -d'

Web UI路由（v0.10.0）

所有路由位于根路径（v0.4.2+无/admin/*前缀）。除/setup、/login、/health外，均需Bearer令牌或会话cookie。

JSON接口（v0.10.0 供客户端使用）

完整参考+curl示例见https://github.com/siamakerlab/vibe-coder-server/wiki/REST-API-Reference%E7%BB%B4%E5%9F%BA%E3%80%82Retrofit%E6%8E%A5%E5%8F%A3%E8%A7%81https://github.com/siamakerlab/vibe-coder-server/wiki/Android-Client-Guide%E3%80%82 重点接口：

• POST /api/auth/login → Bearer令牌
• GET /api/projects、POST /api/projects/register（带sourceType=clone）
• GET /api/env-setup/components、POST /api/env-setup/install-all
• POST /api/env-setup/claude-auth/upload | api-key
• POST /api/env-setup/claude-login/start | submit | cancel
• GET /api/env-setup/mcp、POST /api/env-setup/mcp/install | unregister
• GET /api/settings/git-integrations、POST .../register | delete | ssh-keygen
• WebSocket: /ws/projects/{id}/console/logs、/ws/env-setup/{taskId}/logs

常用操作

bash
docker compose logs -f vibe-coder-server                # 查看服务器日志
docker compose restart vibe-coder-server                # 重启服务
docker exec -it vibe-coder-server bash                  # 进入容器shell（root用户）
docker exec -it --user vibe vibe-coder-server bash      # 进入容器shell（vibe用户）
docker exec -it --user vibe vibe-coder-server claude --version

# 升级（数据保留）
docker compose pull
docker compose up -d --force-recreate

vibe诊断工具（vibe-doctor，Web UI的CLI替代）

bash
docker exec -it vibe-coder-server vibe-doctor                # 交互式（推荐）
docker exec -it vibe-coder-server vibe-doctor check          # 仅诊断
docker exec    vibe-coder-server vibe-doctor install         # 非交互式批量安装
docker exec -it vibe-coder-server vibe-doctor android        # 仅安装Android SDK
docker exec -it vibe-coder-server vibe-doctor claude         # Claude认证助手
docker exec -it vibe-coder-server vibe-doctor mcp            # 基于提示的MCP选择器

故障排除

"Permission denied" — 卷权限错误

PUID/PGID与主机不匹配。通过id -u; id -g获取主机值，更新.env，然后执行docker compose up -d --force-recreate。

"Build failed: SDK location not found"

运行构建环境安装器（Web UI）或vibe-doctor android。

Claude显示"Not logged in"但UI显示✓

可能是用root用户运行claude login（需加--user vibe），或令牌过期（≥30天未使用——重新登录）。v0.6.2+的诊断工具可检测这两种情况。

MCP已安装但Claude无法识别

确保~/.claude/.mcp.json中有该条目。MCP目录UI会自动写入，手动安装需手动编辑。

Windows/WSL2构建缓慢

将项目源码放在WSL2的Linux侧（/home/...），而非/mnt/c/...（I/O慢5-20倍）。

完整故障排除目录：https://github.com/siamakerlab/vibe-coder-server/wiki/Troubleshooting

安全注意事项

• 仅限局域网内部使用：不要在公网IP暴露端口。远程访问需使用***（Tailscale/***）或带HTTPS+认证的反向代理。
• 管理员密码策略：≥8字符，混合字母+数字。
• 密码存储为BCrypt cost-12哈希。Bearer令牌也存储为哈希；仅在发放时返回明文。
• 10次登录失败→15分钟账户锁定（时间安全）。
• 所有磁盘操作通过PathSafety验证（无法从工作区逃逸..）。
• 无原始shell端点；无Web终端模拟器。

完整安全模型：https://github.com/siamakerlab/vibe-coder-server/wiki/Security-Model

构建说明（维护者）

bash
# 常规开发推送（仅amd64，快速2-3分钟）
docker buildx build --platform linux/amd64 \
    -f docker/Dockerfile \
    -t siamakerlab/vibe-coder-server:<ver> \
    -t siamakerlab/vibe-coder-server:latest \
    --push .

# 里程碑版本（多架构——通过arm64模拟较慢10-15分钟）
docker buildx build --platform linux/amd64,linux/arm64 ...

完整指南：https://github.com/siamakerlab/vibe-coder-server/blob/main/docker/README.md

相关链接

• 源码：https://github.com/siamakerlab/vibe-coder-server
• 维基：https://github.com/siamakerlab/vibe-coder-server/wiki
• 变更日志：https://github.com/siamakerlab/vibe-coder-server/blob/main/CHANGELOG.md
• 许可证（AGPL-3.0）：https://github.com/siamakerlab/vibe-coder-server/blob/main/LICENSE