Self-host quickstart

Self-hosting Multica has two parts:

They can be the same machine or separate ones. Self-hosting replaces only the Multica Cloud part.

This guide uses Docker Compose. For Kubernetes deployments, see the Self-hosting guide in the repository.

Before you start

The machine running the Multica service needs:

• Docker Engine or Docker Desktop, with docker compose working
• Git, Make, curl, and OpenSSL
• Ports 3000 and 8080 free on the machine

Confirm Docker and Compose are available first:

docker info
docker compose version

Multica uses Compose v2, invoked as docker compose. The legacy docker-compose v1 is not supported.

The computer also needs at least one AI coding tool installed and logged in, such as Claude Code, Codex, or Cursor. The Multica CLI is installed in step 5.

1. Start Multica

On the machine that will run the service:

git clone --depth 1 https://github.com/multica-ai/multica.git
cd multica
make selfhost

On first run, make selfhost will:

1. Create .env from .env.example
2. Generate a random JWT_SECRET, PostgreSQL password, and MULTICA_VCS_SECRET_KEY (the encryption key for self-hosted Git integrations)
3. Pull the PostgreSQL, Multica backend, and Multica frontend images
4. Create persistent volumes and start the three containers
5. Wait until the backend starts answering health checks

Running make selfhost again reuses the existing .env and volumes; it does not regenerate secrets.

2. Confirm the services are ready

Check container status:

docker compose -f docker-compose.selfhost.yml ps

postgres should show healthy, and backend and frontend should be running. Then check the backend, the database, and migrations:

curl -fsS http://localhost:8080/readyz

The expected response is:

{"status":"ok","checks":{"db":"ok","migrations":"ok"}}

The backend container runs database migrations on every startup before serving; there is no manual migration command to run.

3. Choose how to access

Local access

Open http://localhost:3000 directly. You also won't need to pass any URLs when running multica setup self-host later.

Remote access

Docker Compose binds 3000 and 8080 to 127.0.0.1 only. Do not switch this to 0.0.0.0 to expose the ports to the public internet; use a reverse proxy with HTTPS instead.

The example below uses two domains:

• app.example.com: the Multica web app
• api.example.com: the API, health checks, and daemon connections

First set the public URLs in .env:

FRONTEND_ORIGIN=https://app.example.com
MULTICA_APP_URL=https://app.example.com
MULTICA_PUBLIC_URL=https://api.example.com

With this configuration all browser traffic stays on the app domain, so cookies never cross domains and COOKIE_DOMAIN is not needed. If the browser talks to the api domain directly instead, you must set it — see Environment variables.

Then set up DNS and proxy the local ports with Caddy:

app.example.com {
    # Hand browser WebSockets straight to the backend
    @ws path /ws /ws/*
    handle @ws {
        reverse_proxy 127.0.0.1:8080 {
            flush_interval -1
        }
    }

    # Everything else goes to the frontend, which forwards API and login requests
    handle {
        reverse_proxy 127.0.0.1:3000
    }
}

api.example.com {
    reverse_proxy 127.0.0.1:8080 {
        flush_interval -1
    }
}

Caddy obtains TLS certificates and forwards WebSockets. After editing .env, recreate the containers with up -d so the new configuration takes effect:

docker compose -f docker-compose.selfhost.yml up -d
curl -fsS https://api.example.com/readyz

4. Log in and create a workspace

Open http://localhost:3000 locally, or the https://app.example.com you just configured, and enter your email to request a verification code.

No email service is configured by default. After requesting a code, read it from the backend logs:

docker compose -f docker-compose.selfhost.yml logs backend \
  | grep "Verification code"

The logs contain a line like:

[DEV] Verification code for you@example.com: 123456

Enter the code and create your first workspace. Once Resend or SMTP is configured, codes are sent by email and members no longer need to read container logs — see Auth setup.

5. Connect a computer

Run the commands below on the computer that runs your AI coding tools, which is not necessarily the server running Docker.

Install the Multica CLI first:

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash

Windows PowerShell

irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex

If the Multica service runs on this same computer:

multica setup self-host

If the Multica service runs on another machine, pass the two URLs you configured earlier:

multica setup self-host \
  --server-url https://api.example.com \
  --app-url https://app.example.com

The command first checks <server-url>/health, then opens a browser to complete login. After login it stores local credentials and starts the daemon.

Confirm the connection:

multica daemon status

The output should show:

• Daemon: running
• Agents listing the AI coding tools installed on this machine
• Workspaces greater than 0

6. Complete the first run

Back in Multica, once an online runtime appears in the runtime list, create an agent and assign it your first issue.

When the run shows as completed and the agent's reply appears in the timeline, the self-hosted service, the computer, and the AI coding tool are all connected. For detailed steps, see steps 3-5 of the quickstart.

Common admin commands

Run all of these from the multica repository directory:

# Check status
docker compose -f docker-compose.selfhost.yml ps

# Tail backend logs
docker compose -f docker-compose.selfhost.yml logs -f backend

# Apply .env changes
docker compose -f docker-compose.selfhost.yml up -d

# Stop the services, keeping the volumes
docker compose -f docker-compose.selfhost.yml down

To upgrade to the latest published images:

git pull --ff-only
docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d
curl -fsS http://localhost:8080/readyz

Two ways to upgrade a Docker Compose install. On an existing install they produce the same result — the selfhost target in the Makefile runs the same docker compose pull + up -d, and additionally creates .env when it is missing and waits on /health before printing a status summary. Pick whichever you prefer:

cd multica
git pull
make selfhost

cd multica
git pull
docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d

What git pull actually does

git pull updates docker-compose.selfhost.yml itself — new environment variables, new services, changed healthchecks. It is not how you get a new Multica version.

The version you end up running is resolved by docker compose pull, which asks GHCR what the tag points at right now. A checkout that is months out of date will still pull today's latest images; conversely, git pull alone changes nothing until you pull images and recreate the containers.

grep MULTICA_IMAGE_TAG .env
# MULTICA_IMAGE_TAG=v0.4.5   ← pinned: edit to `latest` (or the release you want) first

Your .env is not overwritten

make selfhost only generates .env when the file is missing. Re-running it on an existing install leaves your JWT_SECRET, Postgres password, email settings, and FRONTEND_ORIGIN exactly as they were.

Back up Postgres first

Migrations are forward-only, so take a dump before upgrading a deployment you care about:

docker compose -f docker-compose.selfhost.yml exec -T postgres \
  pg_dump -U multica multica > multica-backup.sql && gzip multica-backup.sql

Use your own POSTGRES_USER / POSTGRES_DB from .env if you changed them from the multica defaults. Data lives in the named volume multica_pgdata, which survives docker compose down — but not down -v.

Migrations run themselves

As in Step 1, the backend container runs ./migrate up on startup (docker/entrypoint.sh) before serving traffic. There is no separate upgrade command — bringing up the new image is the migration step. Watch it happen:

docker compose -f docker-compose.selfhost.yml logs -f backend

Migrations run automatically when the backend starts; migrations that backfill historical data (such as 103) complete the backfill automatically too. In rare cases the automatic backfill fails with refusing to drop legacy daily rollups — see Troubleshooting.

Verify with /readyz, not /health

/health is a liveness probe — it returns {"status":"ok"} as long as the process is up, including when migrations failed. /readyz (server/cmd/server/router.go:680; /healthz is an alias) checks the database and the applied migration set, so it is the one that catches a bad upgrade:

curl -s localhost:8080/readyz
# {"status":"ok","checks":{"db":"ok","migrations":"ok"}}

Anything other than HTTP 200 with both checks ok means the new version did not finish migrating — check the backend logs before sending traffic at it.

Kubernetes

Helm has its own upgrade path: set images.backend.tag / images.frontend.tag to the release you want in your values file, then helm upgrade. Changing the tag changes the pod spec, so Kubernetes pulls the new image and rolls the Deployments — this is the reliable route.

kubectl -n multica rollout restart is not an upgrade on its own. The chart ships pullPolicy: IfNotPresent (deploy/helm/multica/values.yaml), so a node that already has that tag cached reuses the old image and the restart silently changes nothing — the same class of trap as a pinned MULTICA_IMAGE_TAG. If you want to track a floating tag that way, set images.backend.pullPolicy / images.frontend.pullPolicy to Always first. See the Self-hosting guide.

Common issues

For more scenarios, see Troubleshooting.

Next steps

• Auth setup — configure email, Google login, and signup scope.
• Environment variables — the full server configuration reference.
• Self-hosting guide — Kubernetes, upgrades, and manual deployment.
• Desktop app — connect Desktop to a self-hosted service.