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.

To actually send verification emails:

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]

4. Restart: docker compose -f docker-compose.selfhost.yml restart backend

For more auth configuration (OAuth, signup allowlist), see Auth setup.

4. First login + create a workspace

Open http://localhost:3000:

• Enter your email
• Grab the verification code from the Resend email (or, if you haven't configured Resend, 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. Once installed, use the self-host variant of the setup command:

multica setup self-host --server-url http://<your-server-address>:8080 --app-url http://<your-server-address>:3000

If you're running everything on one local machine:

multica setup self-host

That defaults to http://localhost:8080 (backend) and http://localhost:3000 (frontend).

setup self-host takes you through browser login, stores the PAT locally, and starts the daemon automatically.

6. Create an agent + assign your first task

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

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: Resend isn't configured → 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

Next steps

• Environment variables — full env reference
• Auth setup — Resend / OAuth / signup allowlist in detail
• Troubleshooting — start here when things go wrong
• Desktop app — released Desktop builds connect to Multica Cloud only; using Desktop with self-host requires a custom build (see the callout in the desktop-app page)