Home

Vibe Coder Server — Wiki

Self-hostable Android development server orchestrating Claude Code, Gradle, and Git as child processes. Browser-only operation, optional Android companion client. Ships as a two-container docker compose stack (vibe-coder-server + postgres:17-alpine) since v0.14.0.

Table of contents

Getting started

• Quick Start (Docker) — 3-minute setup
• Data Volumes & Backup — unified ./vibe-coder-data/ layout
• Architecture Overview — modules, child processes, persistence

Build environment

• Build Environment Setup — Android SDK / Gradle / Node
• Claude Authentication — terminal / file upload / API key / web OAuth
• MCP Catalog — 60+ servers, checkbox UI, per-MCP tokens
• Git Integration — PAT + SSH key for private repo clone
• Custom Agents — ~/.claude/agents/*.md CRUD UI (v0.31.0+)
• Build Cache Management — Gradle / Android / npm cache size + cleanup (v0.28.0+)
• APK Signature Inspection — apksigner verify inline on build detail (v0.28.0+)
• Dependency Audit — Gradle dependency tree + coord extraction (v0.32.0+)
• Build Automation — Cron schedule + external webhook trigger (v0.33.0+)
• Code Analysis — Gradle wrapper / code stats / workspace grep (v0.35.0+)

API for clients (Android, CLI, scripts)

• REST API Reference — every endpoint with curl + Retrofit examples
• WebSocket Protocol — auth flow + frame types
• Android Client Guide — repository pattern + auth + key flows
• [[CLI (vibe)|CLI]] — bundled bash MVP (v0.34.0+)
• PWA & VS Code extension — installable web app + IDE integration (v0.39.0+)
• Keyboard Shortcuts — g p / ? / etc (v0.30.0+)
• Multi-Console — N-pane multi-project console (v0.36.0+)
• Multi-Agent Sub-Agent Pool — independent Claude child per (project, agent) (v0.44.0+)

Security & sessions

• Security Model — auth, CSRF, IP block, path safety
• Two-Factor Auth (TOTP) — RFC 6238, Authenticator-compatible (v0.26.0+)
• Users & Roles — admin / member, /users SSR (v0.37.0+)
• Audit Log — what gets recorded, how to filter (v0.15.0+)

Operations / notifications

• Conversation History — prompts/responses persisted in PG (v0.16.0+)
• Conversation Search & Archive — cross-project /history, export/import, auto-archive (v0.30.0/v0.31.0/v0.33.0)
• Email Notifications — SMTP config + triggers (v0.17.0+)
• Webhook Notifications — Slack / Discord / Telegram (v0.27.0+)
• Web Push — VAPID browser push (v0.46.0+ — payload-less)
• Disk Usage Monitor — workspace filesystem polling + threshold alerts (v0.29.0+)
• Backup & Restore — /backup tar.gz + pg_dump guide (v0.34.0+)

Releases & deployments

• Git Workflow — read-only diff/log + commit/push (v0.18.0+)
• Publishing to Stores — Play Console (v0.22.0+) + TestFlight (v0.23.0+) via MCP
• Android Emulator — diagnostics → AVD lifecycle → noVNC (:full image) (v0.19.0/v0.24.0/v0.25.0)
• Kubernetes (Helm chart) — single-replica k8s deployment (v0.47.0+)
• Troubleshooting — common errors + fixes
• Upgrade Guide — version migration paths

Project status (2026-05-24, v0.47.0)

Layer	Version
Server image (slim)	siamakerlab/vibe-coder-server:latest (linux/amd64; current = v0.47.0)
Server image (full / emulator + noVNC)	siamakerlab/vibe-coder-server:full (linux/amd64; v0.38.0-full, ~3-4 GB)
Sidecar	postgres:17-alpine (v0.14.0+)
Base OS	Ubuntu 26.04 LTS (Resolute Raccoon) since v0.38.0
Kotlin	2.2.20 / Ktor 3.1.2 / JDK 17 / Exposed 0.55.0 + PostgreSQL JDBC 42.7.4
Email	Jakarta Mail 2.1.3 + Angus 2.0.3 (v0.17.0+)
Webhook	java.net.http.HttpClient (JDK 11+ stdlib, no external deps) (v0.27.0+)
Web Push	VAPID P-256 self-implemented via java.security + java.net.http (v0.46.0+ — payload-less)
TOTP	RFC 6238 self-implemented (no external deps) (v0.26.0+)
Archives	Apache Commons Compress 1.27.1 (v0.34.0+ — tar.gz streaming)
Bundled CLI	cli/vibe bash + curl (jq optional) (v0.34.0+)
Bundled VS Code extension	vscode-extension/ v0.2.0 (server v0.43.0+ — TreeView + status bar + WS subscribe; not yet on Marketplace)
PWA	manifest + service worker (v0.39.0+, push event handler v0.46.0+)
Multi-user	admin_users.role (admin/member/viewer); SSR + JSON API + WebSocket all enforced (v0.37.0+ / v0.40.0 / v0.45.0)
Multi-agent	SubAgentSessionManager — independent Claude child per (project, agent) (v0.44.0+)
Kubernetes	helm/vibe-coder-server/ minimal chart (v0.47.0+)
noVNC	/emulator/vnc/* reverse proxy with admin auth (v0.42.0+) — no host-side port 6080 exposure needed
Wire	v0.26.0 added LoginRequestDto.totpCode. v0.20.0 promoted PROMPT_TEMPLATES + DTOs. v0.21.0 added ClaudeStatusDto.usagePercent/resetAt. v0.44.0–v0.47.0 are server-internal only (no Android shared/ changes). Android client last wire sync: v0.7.2.

Highlights of v0.12.4 — v0.47.0

Version	Headline change
v0.47.0	Phase 26 — /settings/* admin guard sweep + /usage (Claude /status raw viewer) + minimal Helm chart
v0.46.0	Phase 25 — Web Push (VAPID P-256 + service-worker push handler + /settings/push; payload-less, zero external deps)
v0.45.0	Phase 24 — JSON API + WebSocket viewer_readonly / admin_only role guards (extends SSR-only enforcement from v0.40.0)
v0.44.0	Phase 23 — Real multi-agent sub-agent process pool (SubAgentSessionManager, /projects/{id}/agents/...)
v0.43.0	Phase 22 — VS Code extension full (v0.2.0): Projects TreeView + status bar + live console WS subscribe + 7 palette commands
v0.42.0	Phase 21 — /emulator/vnc/* HTTP + WebSocket reverse proxy through vibe_session admin auth (no host-side port 6080 exposure)
v0.41.0	Phase 20 — Console @ Agent dispatch dropdown (loads GET /api/agents, injects Use the <agent> sub-agent to prefix)
v0.40.0	Phase 19 — viewer role + requireWriteAccessOrRedirect on destructive POST endpoints + admin-only guards on /audit//settings//backup
v0.39.0	Phase 18 — PWA (manifest + service worker) + VS Code extension scaffold (5 commands, zero npm deps)
v0.38.0	Phase 17 — Ubuntu 26.04 LTS rebase (eclipse-temurin:17-{jdk,jre}-resolute); slim + :full both
v0.37.0	Phase 16 — Multi-user / role (admin / member) + /users SSR (admin only)
v0.36.0	Phase 15 — /multi-console?projects=… (iframe grid, ≤ 6 panes) + GET /api/agents dispatch JSON
v0.35.0	Phase 14 — Gradle wrapper UI + code stats (LoC / languages) + workspace grep /code-search
v0.34.0	Phase 13 — /backup SSR (tar.gz workspace stream + pg_dump guide) + bundled cli/vibe bash MVP
v0.33.0	Phase 12 — Cron build schedule + external POST /api/webhooks/build/{id} + conversation auto-archive (30-day cutoff → JSON dump)
v0.32.0	Phase 11 — /projects/{id}/deps dependency audit + /projects/{id}/env-files whitelist editor + /logs cross-project build-log grep
v0.31.0	Phase 10 — /agents UI for ~/.claude/agents/*.md + conversation export/import + prompt-suggestions API
v0.30.0	Phase 9 — build history chart (inline SVG) + global /history conversation search + keyboard shortcuts (g p, ?, …)
v0.29.0	Phase 8 — Source zip download (/projects/{id}/zip) + disk usage monitor (dashboard card + 85% alert)
v0.28.0	Phase 7 — APK signature inspection inline + Gradle/Android/npm cache cleanup UI
v0.27.0	Phase 6 — Slack / Discord / Telegram webhook notifier (parallel to SMTP, SSRF whitelist)
v0.26.0	Phase 5 — 2FA TOTP (RFC 6238 self-impl) + session idle timeout (default 30 min)
v0.25.0	Phase 4 (2/2) — :full image with Xvfb + noVNC + compose.full.yml example
v0.24.0	Phase 4 (1/2) — AVD lifecycle (create / launch / stop) + :full entrypoint
v0.23.0	Phase 3 — TestFlight upload (.ipa) via app-store-connect MCP delegation
v0.22.0	Phase 2 — Play Console upload (AAB) via google-play-publisher MCP delegation
v0.21.0	Phase 1 — Claude usage monitor + threshold email/webhook alert + dashboard card
v0.20.0	Prompt template wire promoted to shared/ (PromptTemplateDto)
v0.19.0	Android Emulator scaffolding — /emulator diagnostics + ADB install
v0.18.0	Git push (POST /git/commit) + project templating (6 starter prompts)
v0.17.0	SMTP email alerts + /settings/email
v0.16.0	Persistent conversation history (PG conversation_turns + /history)
v0.15.0	Operational /audit log + file syntax highlighting
v0.14.0	Breaking — SQLite → PostgreSQL sidecar (fresh-start; workspace preserved)
v0.13.0	Turn cancel + tool render + file edit + prompt templates + General Chat
v0.12.4	Security audit — CSRF / WS Origin / IP block / FK cascade

Repositories

• Server: https://github.com/siamakerlab/vibe-coder-server (this repo)
• Android client: vibe-coder-android — same shared/ module (DTOs / ApiPath / WsFrame) must stay in sync. See Android Client Guide for the integration playbook.

License

GNU Affero General Public License v3.0. SaaS deployments must release modifications under the same license.