Skip to content

Quick Start

Jump to bottom
wody edited this page May 24, 2026 · 6 revisions

Quick Start (Docker)

Get a working server in under 3 minutes on any host with Docker.

1. Prepare host directory

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

Open .env and set a strong PostgreSQL password (v0.14.0+ requirement — compose refuses to start with an empty value):

VIBECODER_IMAGE=siamakerlab/vibe-coder-server:latest
VIBECODER_DB_PASSWORD=CHANGE_ME_to_a_strong_password   # MUST be set
PUID=1000          # match `id -u` on host
PGID=1000          # match `id -g` on host
TZ=Asia/Seoul
VIBE_PORT=17880
VIBE_DATA_ROOT=./vibe-coder-data

2. Boot

docker compose up -d                         # starts postgres + vibe-coder-server
docker compose logs -f vibe-coder-server     # watch first-boot output

The postgres:17-alpine sidecar comes up first (compose waits for its healthcheck before launching the server).

Once you see >>> URL : http://..., open that URL in any browser.

3. Create admin account

Browser → http://<PC IP>:17880/setup

The form creates the first admin user. After login you'll land on the dashboard.

Auto-create on first boot: set VIBECODER_ADMIN_USERNAME and VIBECODER_ADMIN_PASSWORD in .env before the first up -d. Change password from /password immediately afterwards.

4. Install build environment

The browser-driven path (recommended):

  1. Click Build environment in the left nav.
  2. Click the top-right ⚡ Install/update all button. (Or pick cards individually for Android SDK only / MCP only.)
  3. The progress page shows live install logs and elapsed time. Android SDK download is 3-4 GB / 5-15 min.

Equivalent CLI path:

docker exec -it vibe-coder-server vibe-doctor

5. Authenticate Claude Code

On the Build environment page, the Claude login card offers four options:

  • 0. Web OAuth (★ recommended) — Click "Login via web". A new tab opens to Anthropic, you paste the resulting code back into a single field. No terminal, no other machine.
  • 1. Terminal — docker exec -it --user vibe vibe-coder-server claude login. Most direct if you have shell access.
  • 2. File upload — Generate .credentials.json on another machine (claude login there) and upload it through the form.
  • 3. API key — Paste an ANTHROPIC_API_KEY directly. Bypasses OAuth.

See Claude Authentication for the comparison matrix.

6. Create your first project

Browser → /projects → New project

Source modes:

  • Empty (default): empty folder + CLAUDE.md template. Tell Claude what to scaffold from the console.
  • Template (v0.18.0+): pick a built-in scaffold — compose-basic, compose-mvvm-hilt, compose-mvvm-room, wear-os, or android-tv. Each template seeds a starterPrompt so the first Claude turn already has context to work with.
  • Clone: git URL. Public works out of the box. Private needs a PAT (/settings/git-integrations) or SSH key.

After creation, click into the project and use the Console tab to send prompts. Builds tab queues debug builds and serves APKs.

7. Optional: General Chat without a project (v0.13.0+)

Click Chat in the left nav. Claude runs in a hidden __scratch__ ghost project — useful for one-off questions, code snippets, or "rubber duck" sessions that shouldn't pollute a real project's history.

The conversation is still saved to conversation_turns (v0.16.0+) and visible at /chat/history for searching old answers.

8. Optional: Email notifications (v0.17.0+)

Browser → /settings/email to configure SMTP (host / port / user / password / from). The server can then alert you on:

  • Build failure / first success
  • Claude session waiting on user input for > N minutes
  • Disk usage threshold (85 % default)
  • SSH key / PAT nearing expiry

See Email Notifications for the trigger matrix.

9. Optional: Android emulator (v0.19.0+, scaffolding only)

Click Emulator in the left nav. The page shows KVM availability, installed AVDs, and running devices, with a manual launch guide. Full in-browser noVNC mirroring ships in the :full image variant — see Emulator for the migration path.

10. Upgrade later (data preserved)

cd ~/vibe-coder
docker compose pull
docker compose up -d --force-recreate

Everything under ./vibe-coder-data/ is preserved. See Data Volumes & Backup for the layout.

Clone this wiki locally