Skip to content

Quick Start

Jump to bottom
Sia edited this page May 31, 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 (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: 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

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 and visible at /chat/history for searching old answers.

7.5. Optional: 2FA

Click 2단계 인증 in the left nav. Scan the otpauth URI or paste the Base32 secret into your Authenticator app, then verify with a 6-digit code. Future logins require the code after password. See Two-Factor Auth for the threat model + recovery.

8. Optional: Email notifications

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.

8.5. Optional: Slack / Discord / Telegram webhooks

Click Webhook 알림 in the nav. Slack incoming webhook URL, Discord webhook URL, and/or Telegram bot token + chat id — each provider can be left empty (only configured ones receive). Test message button per provider. SSRF whitelist enforces host families. See Webhook Notifications.

9. Optional: test on a real device (wireless ADB)

To check a build on a real device, use wireless ADB: the sidebar shows a connection badge; click connect to auto-discover devices on the same LAN (HOST network — see docker/compose.host.yml) or enter the phone's ip:port manually, then stream logcat. Or just sideload the APK from the build artifacts.

9.5. Optional: Publishing to stores

After a successful build, the build detail page shows Play Console upload and TestFlight upload cards. Both delegate to MCP servers (google-play-publisher / app-store-connect). Install + configure them at /env-setup/mcp first. See Publishing to Stores.

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