Self-host quickstart

This page walks you through running the Multica server (backend + frontend + PostgreSQL) on your own machine or server with Docker. When you're done, your data is fully under your control — including workspaces, issues, comments, and agent configuration.

Agent execution still relies on the daemon you run locally plus the AI coding tools installed on that machine — exactly like Cloud. Self-host swaps out the server layer, not the execution layer.

Prerequisites

• Docker installed and able to run docker compose
• Git (optional, but recommended so you can pull the source)
• A machine that can stay up (local / internal network / cloud host all work)
• At least one AI coding tool installed on the machine running the daemon (not necessarily the one running the server — your dev laptop works)

1. Pull the project and start the backend

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

make selfhost will:

1. Generate a .env from .env.example if missing, with a random JWT_SECRET
2. Pull the official Docker images (PostgreSQL, Multica backend, Multica frontend)
3. Bring up every service using docker-compose.selfhost.yml
4. Wait until the backend's /health endpoint is ready

For ongoing production probes after startup, use /readyz when you want the check to fail on database or migration problems.

The backend container runs database migrations automatically on startup (docker/entrypoint.sh runs ./migrate up before the server starts) — you'll see the migration output in the backend logs. Version upgrades are handled the same way.

Once it's up:

• Frontend: http://localhost:3000
• Backend: http://localhost:8080

2. Important: keep production safety on

3. Configure the email service (optional but recommended)

Without email configured, your users can't receive verification codes by email; the server prints generated codes to stdout instead.

Two delivery backends are supported — pick whichever fits your network:

Option A — Resend (cloud / public-internet deployments):

1. Sign up at Resend and get an API key

2. Verify a sending domain you control

3. Set these in .env:

   RESEND_API_KEY=re_xxxxxxxxxxxx
   RESEND_FROM_EMAIL=[email protected]

Option B — SMTP relay (internal networks / on-premise):

Use this when the deployment can't reach api.resend.com, or you already have an internal mail relay (Exchange, Postfix, on-prem SendGrid, etc.). SMTP_HOST takes priority over Resend when both are set.

SMTP_HOST=smtp.internal.example.com
SMTP_PORT=587                  # default 25; use 587 for STARTTLS submission
SMTP_USERNAME=multica          # leave empty for unauthenticated relay
SMTP_PASSWORD=...
RESEND_FROM_EMAIL=[email protected]  # reused as the From: header

Then restart: docker compose -f docker-compose.selfhost.yml restart backend.

For more auth configuration (OAuth, signup allowlist) and the full SMTP variable reference, see Auth setup and Environment variables → Email.

4. First login + create a workspace

Open http://localhost:3000:

• Enter your email
• Grab the verification code from your configured email backend (Resend or SMTP relay); if neither is configured, copy it from the server container stdout — look for the [DEV] Verification code line
• Do not use 888888 unless you explicitly set MULTICA_DEV_VERIFICATION_CODE=888888 on a non-production private instance
• Log in and create your first workspace

5. Point the CLI at your own server

The CLI install is the same as in Cloud quickstart → 2. Install the CLI — Homebrew / script / PowerShell, pick one.

5a. Same machine

If the CLI and the server run on the same host, the defaults already work:

multica setup self-host

That points the CLI at http://localhost:8080 (backend) and http://localhost:3000 (frontend), takes you through browser login, stores the PAT locally, and starts the daemon automatically.

5b. Cross-machine: front with a reverse proxy

Because the compose stack only listens on 127.0.0.1, a daemon on a different machine cannot reach http://<server-ip>:8080 directly — and you do not want it to, since the default JWT_SECRET would otherwise be reachable from the open internet. Put a reverse proxy on the server that terminates TLS and forwards to 127.0.0.1:8080 (backend) and 127.0.0.1:3000 (frontend), then point the CLI at the public HTTPS URL:

multica setup self-host \
  --server-url https://<your-domain> \
  --app-url https://<your-domain>

A minimal Caddyfile that fronts both the frontend and the backend (with WebSocket support, which the daemon and the web app both need) on a single hostname:

multica.example.com {
    # WebSocket route — must come before the catch-all
    @ws path /ws /ws/*
    handle @ws {
        reverse_proxy 127.0.0.1:8080 {
            flush_interval -1
        }
    }

    # Backend API
    handle /api/* {
        reverse_proxy 127.0.0.1:8080
    }

    # Everything else → frontend
    reverse_proxy 127.0.0.1:3000
}

After bringing the proxy up, set FRONTEND_ORIGIN=https://multica.example.com in the server's .env and restart the backend — otherwise the WebSocket origin check will reject the browser (Troubleshooting → WebSocket can't connect).

Cloudflare Tunnel is another solid option — it gives you TLS and a public hostname without exposing any port on the host at all. An Nginx equivalent (separate app. / api. hostnames, proxy_set_header Upgrade for WebSockets) works just as well; the key requirements are TLS termination and forwarding the Upgrade header on /ws.

6. Create an agent + assign your first task

Same flow as Cloud — see Cloud quickstart → Steps 5-6.

7. Schedule the usage rollup (required for the Usage dashboard)

Pick one of the supported options — only one is needed.

Option A — External cron / systemd-timer (simplest). Run the rollup every 5 minutes from any out-of-band scheduler. It's idempotent and watermark-driven, so missed ticks catch up:

# /etc/cron.d/multica-rollup — every 5 minutes
*/5 * * * * root docker compose -f /path/to/multica/docker-compose.selfhost.yml \
  exec -T postgres psql -U multica -d multica \
  -c "SELECT rollup_task_usage_hourly();" >/dev/null

Option B — Swap Postgres for an image that ships pg_cron. Replace pgvector/pgvector:pg17 in docker-compose.selfhost.yml with an image that has both pgvector and pg_cron (supabase/postgres, or a custom build), set shared_preload_libraries=pg_cron, restart, then register the job once:

CREATE EXTENSION IF NOT EXISTS pg_cron;
SELECT cron.schedule(
  'rollup_task_usage_hourly',
  '*/5 * * * *',
  $$SELECT rollup_task_usage_hourly()$$
);

Option C — Backfill history first (upgrade path). If you're upgrading from v0.3.4 → v0.3.5+ and have existing task_usage rows, migration 103 will abort migrate up with refusing to drop legacy daily rollups: ... until the hourly table is seeded. Run the bundled backfill once, then set up Option A or B:

docker compose -f docker-compose.selfhost.yml exec backend \
  ./backfill_task_usage_hourly --sleep-between-slices=2s

--sleep-between-slices=2s throttles read pressure on a busy DB. After it finishes, restart the backend container (migrations run on startup) and the upgrade completes.

Full reference — including the Kubernetes CronJob template and the upgrade order — lives in the repo's SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup.

Kubernetes deployment (alternative)

If you already run a Kubernetes cluster, the repo also ships a Helm chart at deploy/helm/multica/. It's the equivalent of make selfhost for k8s — same backend image, frontend image, and pgvector/pgvector:pg17 Postgres, packaged as Deployments / Services / Ingresses with one ConfigMap rendered from values.yaml. Authored against k3s + Traefik + local-path and should work on any cluster with an Ingress controller and a default ReadWriteOnce StorageClass.

The chart does not template secret values. It references a Secret named multica-secrets by name, so real JWT / DB / Resend / Google keys never need to live in git or in values.yaml. Create the namespace + Secret once with kubectl:

kubectl create namespace multica

kubectl -n multica create secret generic multica-secrets \
  --from-literal=JWT_SECRET="$(openssl rand -hex 32)" \
  --from-literal=POSTGRES_PASSWORD="$(openssl rand -hex 16)" \
  --from-literal=RESEND_API_KEY="" \
  --from-literal=GOOGLE_CLIENT_SECRET="" \
  --from-literal=CLOUDFRONT_PRIVATE_KEY="" \
  --from-literal=MULTICA_DEV_VERIFICATION_CODE=""

Then install the chart:

git clone https://github.com/multica-ai/multica.git
cd multica
helm install multica deploy/helm/multica -n multica

Defaults assume the hostnames multica.dev.lan (web) and api.multica.dev.lan (backend). Add them to /etc/hosts (or local DNS) pointing at any node IP where your Ingress is reachable. To use different hostnames, copy deploy/helm/multica/values.yaml, edit ingress.frontend.host / ingress.backend.host and the matching backend.config.appUrl / frontendOrigin / localUploadBaseUrl / googleRedirectUri, then install with -f my-values.yaml.

On a cold cluster the backend can stay Running but not Ready for a few minutes while it waits on Postgres and runs migrations — a startupProbe absorbs this, so the pod should not restart. Once it's Ready:

curl -H "Host: api.multica.dev.lan" http://<ingress-ip>/healthz
# {"status":"ok","checks":{"db":"ok","migrations":"ok"}}

Then open http://multica.dev.lan and continue at Step 4 — First login above. Point the CLI at your Ingress hostnames:

multica setup self-host \
  --server-url http://api.multica.dev.lan \
  --app-url http://multica.dev.lan

To pull the latest images without changing the chart, kubectl -n multica rollout restart deploy/multica-backend deploy/multica-frontend. To pin a specific Multica release, set images.backend.tag / images.frontend.tag in your values file and helm upgrade. helm -n multica uninstall multica removes the workloads but keeps the PVCs and Secret; kubectl delete namespace multica wipes everything.

The full reference — three login modes, the backend ExternalName workaround for the build-time-baked REMOTE_API_URL in the web image, resource limits, and TLS — lives in the repo's SELF_HOSTING.md.

Common issues

• Backend won't start: check container logs with docker compose -f docker-compose.selfhost.yml logs backend; usually it's a bad DATABASE_URL or JWT_SECRET in .env
• Verification code not received: no email backend is configured (neither Resend nor SMTP) → look for [DEV] Verification code in docker compose logs backend
• WebSocket won't connect: for public deployments you must set FRONTEND_ORIGIN to your real frontend domain; see Troubleshooting → WebSocket won't connect
• Usage / Runtime dashboard stays at zero: rollup_task_usage_hourly() isn't being scheduled — see Step 7 above and Troubleshooting → Usage dashboard shows zero
• migrate up fails with refusing to drop legacy daily rollups: upgrade-path guard from v0.3.4 → v0.3.5+. Run backfill_task_usage_hourly first — see Step 7 → Option C

Next steps

• Environment variables — full env reference
• Auth setup — Resend / OAuth / signup allowlist in detail
• GitHub integration — connect a GitHub App so PRs auto-link to issues and merging closes them
• Troubleshooting — start here when things go wrong
• Desktop app — optional Desktop setup via ~/.multica/desktop.json; the web frontend + CLI remains the quickest self-host path