# Install Withvibe

> Help a user install WithVibe on their own laptop or server for the first time. Trigger when a user asks to install, set up, get started with, try, or run WithVibe locally — including phrasings like "how do I install withvibe", "I want to try withvibe", "set up withvibe on my mac", "withvibe quick start", or "what do I need to run withvibe". This is the friendly first-time-user path; it assumes the user wants the easiest install (npm registry) unless they say otherwise, walks them through prerequisites with OS-appropriate commands, runs the guided `withvibe init`, and verifies the stack came up.

- Skill: `withvibe/install-withvibe` (Agent Skill)
- Install (CLI): `npx skillmds@latest add withvibe/install-withvibe`
- Raw SKILL.md: https://api.skillmd.com/api/skills/withvibe/install-withvibe/raw
- Safety review: WARNING
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: withvibe (https://skillmd.com/u/withvibe)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/withvibe/install-withvibe

---


# Install WithVibe (user guide)

You're helping a real person — probably a developer trying WithVibe for the first time — get the stack running on their machine. They don't want to read docs; they want it working. Your job is to be the friendly guide who explains each step, runs commands with their permission, and bails them out if something breaks.

The CLI does the heavy lifting (`withvibe doctor`, `withvibe init`, `withvibe start`). You're the front desk.

## The happy path

This is what 90% of installs look like. Stick to it unless the user says otherwise.

1. **Confirm goal** — quick check: "Want me to walk you through installing WithVibe on this machine?" (default yes, but they may want to install on a server they SSH into).
2. **Detect OS** — `uname -s` plus `uname -m`, so the prerequisite commands are correct.
3. **Run `withvibe doctor`** if the CLI is already installed; otherwise jump to step 4.
4. **Install the CLI** — `npm install -g withvibe`. Needs Node 20+.
5. **Install missing prerequisites** — Docker, Docker Compose, `gh` (only with explicit user permission, using the right package manager for their OS).
6. **Run `withvibe init`** — interactive by default; it'll prompt for install dir, ports, Anthropic API key, optional Google OAuth.
7. **Start the stack** — `withvibe start` (or `init` may have done this for you).
8. **Verify** — open the URL it printed, confirm the login screen loads.

Always **announce before you act** when running anything that touches the user's machine (brew install, apt install, docker pull, mutating state). They should be able to interrupt between steps.

## Step 1 — Prerequisites

WithVibe needs:

| Tool | Why | Minimum |
| ---- | --- | ------- |
| **Node.js** | Runs the `withvibe` CLI | 20+ |
| **Docker** | Runs the api/web/postgres/traefik containers | 24+ |
| **Docker Compose** | Orchestrates the stack | v2 (bundled with Docker Desktop) |
| **An Anthropic API key** | The agent runtime | Any tier — workspace can override per-user later |

Optional but commonly wanted:

- **`gh` (GitHub CLI)** — needed if envs will clone private repos
- **Google OAuth client ID/secret** — only if the user wants Google Sign-In; otherwise they can use local auth

### OS-aware install commands

Only run these with explicit user permission. Show the command first, ask "want me to run it?", then execute.

**macOS** (Homebrew):
```bash
brew install node docker gh
open -a Docker            # start Docker Desktop
```
If they don't have Homebrew, point them at <https://brew.sh> rather than installing it for them — it touches `/opt/homebrew` and they should consent.

**Linux** (Debian/Ubuntu):
```bash
# Node 20 via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Docker via Docker's official repo (don't use distro packages — too old)
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER     # log out and back in for this to take effect

# gh
sudo apt-get install -y gh
```

**Linux** (Fedora/Rocky/RHEL):
```bash
sudo dnf install -y nodejs docker gh
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
```

**Windows**: recommend WSL2 + Docker Desktop. WithVibe runs inside the WSL2 distro (Ubuntu), not on Windows directly. From inside WSL2, the Debian/Ubuntu commands above apply.

## Step 2 — Get the CLI

```bash
npm install -g withvibe
withvibe --version
```

If they get `EACCES` errors, suggest one of:
- `sudo npm install -g withvibe` (works but ties global packages to root)
- Set up an npm prefix in `$HOME` — `mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global && export PATH=~/.npm-global/bin:$PATH` (cleaner long-term)

`npm install -g withvibe` is the published CLI from <https://github.com/withvibe/withvibe-cli> (Apache 2.0). If the registry install fails or they want the latest unreleased CLI, they can build from source — but for first-time installs, push back gently toward the registry path.

## Step 3 — Doctor

Once the CLI is on PATH:

```bash
withvibe doctor
```

This prints a checklist of what's present and what's missing (Docker, Docker Compose, gh, free ports, etc.). Read it back to the user in plain language — "Docker is good. You're missing `gh` — want me to install it?" Loop on missing items until doctor is green.

Don't proceed to `init` while doctor still has blocking failures. Warnings (e.g. `gh` not installed but no private repos planned) are fine to skip.

## Step 4 — Init

```bash
withvibe init
```

This is interactive. It asks for:

- **Install directory** — where `.env`, `docker-compose.yml`, and state will live. Default is fine (`~/.withvibe` or similar — let the CLI default).
- **Anthropic API key** — paste it. Tell the user this is workspace-level; individual users can override later. Get one at <https://console.anthropic.com/settings/keys>.
- **Google OAuth** (optional) — only ask if the user wants Google Sign-In. Skip if they don't know what it is; they can add it later via `withvibe configure`.
- **Public URLs** — for a local install, the CLI will default to `http://localhost:3000` (web) and `http://localhost:3001` (api). For a server install, they'll need real URLs and probably Traefik (see "Server install" below).
- **Ports** — accept defaults unless something is already bound.

If the user wants a hands-off install with all defaults: `withvibe init -y` (after they've still answered the API-key prompt — that one's non-defaultable).

## Step 5 — Start and verify

```bash
withvibe start                                # if init didn't already start it
withvibe status                               # should show all containers Up
curl -fsS http://localhost:3000 > /dev/null   # web responds
```

Open the web URL the CLI printed. They should see a login screen. First sign-in creates the workspace owner account.

If `status` shows a container restarting or `withvibe logs <service>` reveals an error, common culprits:
- **Postgres won't start** — port 5432 already in use locally; re-run `init` to pick a different host port.
- **API health failing** — usually a bad/missing `ANTHROPIC_API_KEY`. `withvibe configure` to fix.
- **Web → API CORS / cookie issues** — `WEB_PUBLIC_URL` and `API_PUBLIC_URL` mismatched. Re-run `init` or edit the install dir's `.env`.

## Server install (advanced)

If the user is installing on a public server (not laptop) and wants HTTPS:

1. They need a domain pointed at the server's IP (A record).
2. During `init`, opt into **Traefik** when prompted, and provide:
   - A base domain (e.g. `withvibe.example.com`)
   - An email for Let's Encrypt
3. Ports 80 and 443 must be free on the server.
4. WithVibe envs will get subdomains like `<env-id>.<base>` — make sure the DNS A record is a wildcard (`*.<base>`) or the env URLs won't resolve.

If they're behind a corporate proxy / can't use Let's Encrypt, they need **BYOCERT mode** — they bring their own fullchain + key. `withvibe configure` walks them through it.

## When things go wrong

- **`withvibe: command not found` after npm install** — npm's global bin dir isn't on PATH. `npm config get prefix` then add `<prefix>/bin` to PATH.
- **Docker permission denied** — user not in the `docker` group; they need to log out and back in after `usermod -aG docker $USER`.
- **`init` hangs at "pulling images"** — check internet, check `docker login ghcr.io` isn't required (the images are public by default).
- **Stack starts but login redirects in a loop** — `COOKIE_DOMAIN` or URL mismatch. Re-run `init` and let it set URLs to whatever the user is actually browsing to.
- **They want to start over** — `withvibe uninstall` removes containers + state. Their `.env` is preserved unless they pass `--purge`.

## What to suggest after install

Once the stack is up and they've logged in, useful next steps to mention:

- Create a workspace, invite teammates.
- Add their first repo and create an env.
- Install plugins (e.g. the roadmap plugin) via the workspace admin Plugins page.
- If they want to build their own plugin: there's a separate `withvibe-plugin-creator` skill for that.

Don't dump all of this on them at once — install is enough for one session. Offer one next step matched to whatever they mentioned wanting.