withvibe
Sign in
Self-hosting

Self-host overview

withvibe is designed to run on your own infrastructure first. This page covers the components, the operational model, and what to plan for before rolling it out to a team.

Components

A withvibe deployment has three long-running services:

  • Web — Next.js app. The UI for workspaces, envs, chat, and the agent gate.
  • API — NestJS service. Handles auth, persistence (Postgres + Prisma), the chat stream, and env orchestration: it drives the host Docker daemon directly (Docker-out-of-Docker) to spawn one container per env.
  • Postgres — metadata only (users, workspaces, envs, sessions). Code lives in the per-env containers and in your Git remote.

Each env is an ephemeral container (plus optional sidecars: code-server, qa-browser) that the API creates and tears down on demand — not a service you run yourself.

What runs where

Web and API are stateless containers. Postgres is the only persistent service (a named Docker volume). Each env is its own container, isolated by Docker, with its own filesystem and process tree, created on demand by the API.

Docker socket access
The API mounts /var/run/docker.sockto spawn env containers on the host daemon — that grants it root-equivalent access to the host. In production, run the API on a dedicated host or use a rootless / DinD setup so a compromised env can't pivot to your control plane.

Capacity planning

  • Per-env memory: ~512 MB idle, more during builds/tests. Plan for the biggest dev container your repo currently needs, plus 256 MB for the agent process.
  • Concurrency: a 16 GB runner host comfortably holds ~20 idle envs. Active envs use more.
  • API throughput: the chat stream is long-lived SSE. Tune your reverse proxy timeouts (Cloudflare, Nginx) accordingly — see the docker compose page for an example.

Secrets

  • INTERNAL_JWT_SECRET — required, signs session JWTs (generate with openssl rand -hex 32)
  • DATABASE_URL — Postgres connection string (built from POSTGRES_*)
  • ANTHROPIC_API_KEY — needed for agent runs; can be left blank in .env and set later from the workspace UI
  • GITHUB_TOKEN — optional, default credential for cloning repos (per-workspace tokens override it)
  • GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET — optional, enables Google login

Upgrading

Releases follow semver. Migrations are run automatically on API startup via Prisma. Pin a specific tag in production rather than tracking main.

Next

Continue with Docker compose for a working single-host setup.

PreviousSlackNext Install