Skip to content

SELF_HOSTING_AI.md

Latest commit

 

History

History
88 lines (64 loc) · 2.85 KB

SELF_HOSTING_AI.md

File metadata and controls

88 lines (64 loc) · 2.85 KB
Raw

Self-Hosting Setup (for AI Agents)

This document is designed for AI agents to execute. Follow these steps exactly to deploy a local Multica instance and connect to it.

Prerequisites

  • Docker and Docker Compose installed
  • Homebrew installed (for CLI)
  • At least one AI agent CLI on PATH: claude or codex

Install

# Install CLI + provision self-host server
curl -fsSL https://raw.githubusercontent.com/hduhelp/multica/main/scripts/install.sh | bash -s -- --with-server

# Configure CLI for localhost, authenticate, and start daemon
multica setup self-host

Wait for the server output ✓ Multica server is running and CLI is ready! before running multica setup self-host.

Expected result:

Alternative: Manual Setup

git clone https://github.com/hduhelp/multica.git
cd multica
make selfhost
brew install hduhelp/tap/multica
multica setup self-host

The multica setup self-host command will:

  1. Configure CLI to connect to localhost:8080 / localhost:3000
  2. Open a browser for login — use the emailed code, or the generated code printed in backend logs when Resend is unset
  3. Discover workspaces automatically
  4. Start the daemon in the background

Verification

multica daemon status

Should show running with detected agents.

Stopping

# Stop the daemon
multica daemon stop

# Stop all Docker services
cd multica
make selfhost-stop

Custom Ports

If the default ports (8080/3000) are in use:

  1. Edit .env and change PORT and FRONTEND_PORT. These are host ports; the containers keep listening on 8080/3000 internally, so no rebuild is needed.
  2. Run make selfhost
  3. Run multica setup self-host --port <PORT> --frontend-port <FRONTEND_PORT>

Edit the file rather than relying on environment variables: make includes .env, so a value in the file outranks the same variable from your shell (PORT=9100 make selfhost is ignored when .env sets PORT). A command-line assignment does take effect (make selfhost PORT=9100), and Docker Compose invoked directly is the reverse again — there the environment outranks .env.

BACKEND_PORT is an optional alias that overrides PORT for the backend; API_PORT and SERVER_PORT follow in that order. Whichever route you use, the startup output is read back from Docker Compose, so the address it prints is the one the stack is actually published on.

Troubleshooting

  • Backend not ready: docker compose -f docker-compose.selfhost.yml logs backend
  • Frontend not ready: docker compose -f docker-compose.selfhost.yml logs frontend
  • Daemon issues: multica daemon logs
  • Health checks: curl http://localhost:8080/health for liveness, curl http://localhost:8080/readyz for dependency-aware readiness