Self-host quickstart

Start MulticaCopy Anchor Link

On the machine that will run the service:

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

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

git fetch --tags --depth 1
git checkout $(git tag -l 'v*' --sort=-v:refname | head -1)

Confirm the services are readyCopy Anchor Link

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.

Choose how to accessCopy Anchor Link

Log in and create a workspaceCopy Anchor Link

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 [email protected]: 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.

Connect a computerCopy Anchor Link

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:

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

Then point the CLI at your service. Pick where the Multica service runs:

multica setup self-host

When the service is on another machine, pass the two URLs you configured above. The command first checks <server-url>/health, then opens a browser to complete login. After login it stores local credentials and starts the daemon. A Server not reachable error at this step means the probe could not get a 200 from /health. There are three likely causes: the proxy forwards everything to a web release that does not forward the path; the proxy does not route /health to the backend at all; or a lower-level failure (DNS, TLS, firewall, timeout, 5xx from the backend). See Troubleshooting.

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

Complete the first runCopy Anchor Link

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.

Check for a pinned image tagCopy Anchor Link

Both images resolve as ${MULTICA_IMAGE_TAG:-latest} (docker-compose.selfhost.yml, services.backend.image / services.frontend.image), and .env.example ships MULTICA_IMAGE_TAG=latest.

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

Back up PostgresCopy Anchor Link

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.

Pull the new images and recreate the containersCopy Anchor Link

On an existing install both commands 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 --ff-only
make selfhost

As in step 2, 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 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 /healthCopy Anchor Link

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.

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