There are three ways to stand up withvibe. They all end at the same place — the CLI writing ~/.withvibe and bringing the Docker stack up — they just differ in how much you do by hand.

Which one?

Option	Best for	Images
1. Script	Fastest start; also installs Node/Docker for you	Prebuilt (pulled)
2. npm CLI	You already have Docker + Node; no curl-pipe	Prebuilt (pulled)
3. Source	Customizing the code, air-gapped, contributing	Built locally

Option 1 — From the bootstrap script

The lowest-friction path: one line that also installs missing prerequisites.

macOS / Linux:

curl -fsSL https://withvibe.dev/install.sh | bash

Windows (PowerShell):

irm https://withvibe.dev/install.ps1 | iex

The script:

detects your OS;
ensures Node.js ≥ 20 (installs it if missing, with your consent);
ensures Dockeris installed and running — auto-installs Docker Engine on Linux; on macOS/Windows it points you to Docker Desktop (it can't start that for you);
installs the withvibe CLI from npm;
runs withvibe init to pull the images and start the stack.

Non-interactive (CI / unattended) — default HTTP/localhost install:

curl -fsSL https://withvibe.dev/install.sh | bash -s -- --yes

Inspect before you pipe

Running a remote script straight into a shell executes it as you. To read it first:
curl -fsSL https://withvibe.dev/install.sh -o install.sh
less install.sh && bash install.sh

Option 2 — From the npm CLI

If you already have Docker running and Node.js ≥ 20, or you'd rather not pipe a script, install the CLI from npm and run it. Same command on macOS, Linux, and Windows:

npm i -g withvibe && withvibe init

withvibe init pulls the five prebuilt images from ghcr.io/withvibe/*, writes ~/.withvibe/.env + docker-compose.yml, generates secrets, picks free ports, and starts the stack. Zero-prompt HTTP/localhost variant:

npm i -g withvibe && withvibe init -m from-registry --yes

(pnpm add -g withvibe / npx withvibe init work too — npm just needs no extra PATH setup.)

Option 3 — From source

Builds the images locally from the repo's Dockerfiles instead of pulling them. Use this to customize the code, run without registry access (air-gapped), or contribute.

Prerequisites: Git, Docker, Node.js ≥ 20.

git clone https://github.com/withvibe/withvibe.git
cd withvibe

# get the CLI — either install it from npm…
npm i -g withvibe
# …or build it from this checkout instead:
#   pnpm install && pnpm --filter withvibe build && (cd packages/cli && pnpm link --global)

withvibe init -m from-source

-m from-source runs docker build for api, web, and the sidecar images against the Dockerfiles in your checkout (the multi-stage builds handle the pnpm install/compile inside Docker), then brings the stack up. Run it from inside the clone so the CLI auto-detects the repo root.

Source = control plane only, still needs Docker

Building from source still produces and runs Docker containers. There is no Docker-free install — environments are containers the API spawns. The bare pnpm dev workflow in the repo README is a contributor dev loop, not a deployment method.

Custom domain & HTTPS

Applies to all three options. The --yes path takes localhost-friendly defaults (HTTP, no TLS). To put it on a real domain, run withvibe configure → Traefik → Change base domain, then pick how TLS is handled:

Let's Encrypt (automatic) — give a base domain + ACME email; the cert is issued and renewed for you. Needs public DNS pointing at the host and ports 80/443 reachable.
Bring your own certificate— already have a cert (corporate CA, wildcard, or air-gapped with no outbound 443)? Choose this and give the paths to your PEM cert + key. They're copied into ~/.withvibe/certs/and Traefik serves them directly — no Let's Encrypt involved. Re-run configure to rotate.

Or skip the bundled Traefik entirely and terminate TLS at your own reverse proxy / load balancer in front of port 3000 (withvibe configure → Traefik → Disable) — see Routing.

For Let's Encrypt: point your DNS A record at the server before reconfiguring so the TLS challenge can complete, and open ports 80/443 in the firewall. After any change, withvibe restart.

Per-env subdomains with your own cert

Traefik also routes per-env subdomains (app.env-abc123.your-domain). With a bring-your-own cert, those are only valid if your certificate covers them — use a wildcardcert, or accept that env subdomains won't have a trusted cert.

After install

Open the stack (https://your-domain, or the URL printed by withvibe status for a localhost install) and register the first user — they become the workspace owner. Then add secrets from the UI under Settings:

Anthropic API key — required for agent runs
GitHub token — for cloning repos
Google OAuth — optional, only if you want Google login

Verify

withvibe status     # are the containers up?
withvibe doctor     # preflight diagnostic

Upgrading

Never re-run init on a live install

withvibe init regenerates the Postgres password and session secret and clears configured API keys — it will brick existing data. Use withvibe upgrade to move to a new release.

Want full control over the compose file instead of the managed install? See Docker compose. For the architecture and capacity planning, start with the Self-host overview.

Install