mirror of https://github.com/multica-ai/multica.git synced 2026-08-03 11:10:23 +02:00

Files

Lambda 7a66de9f23 fix(selfhost): deliver MULTICA_LLM_* to the backend and log the layer state

Chat auto-titling and chat follow-up suggestions are gated on the server-side
LLM layer, which reads MULTICA_LLM_API_KEY / MULTICA_LLM_BASE_URL through
os.Getenv. The self-host compose file enumerates backend environment
explicitly and has no env_file, and those three vars were not in the list — so
setting them in .env did nothing, the container never saw them, and the layer
was off on every compose deployment regardless of configuration. .env.example
documents them, which made it look configurable.

That was survivable while quick actions were generated by the daemon's own
provider pass, which needed no server key. MUL-5573 moved generation server-
side and removed the daemon path, so on those deployments the feature stopped
appearing entirely rather than degrading.

Adds the passthrough, and one startup line reporting whether the layer is
enabled. Every consumer degrades silently by design, so without that line an
unset key is indistinguishable from a broken feature — which is exactly how
this surfaced. Helm already supports it through the operator-managed Secret;
values.yaml now says so instead of leaving it undocumented.

Co-authored-by: multica-agent <github@multica.ai>

2026-07-31 16:35:01 +08:00

3.8 KiB

Raw Permalink Blame History

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/multica-ai/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:

Frontend at http://localhost:3000
Backend at http://localhost:8080
multica CLI installed and configured for localhost

Alternative: Manual Setup

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

The multica setup self-host command will:

Configure CLI to connect to localhost:8080 / localhost:3000
Open a browser for login — use the emailed code, or the generated code printed in backend logs when Resend is unset
Discover workspaces automatically
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:

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.
Run make selfhost
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.

Optional: server-side LLM features

Chat auto-titling and chat follow-up suggestions ("quick actions") are produced by a small server-side model call, separate from the agent runtimes. They are off until the backend has an upstream configured:

# In .env — either the key or the base URL is enough to enable the layer.
MULTICA_LLM_API_KEY=sk-...
MULTICA_LLM_BASE_URL=          # optional: any OpenAI-compatible gateway
MULTICA_LLM_DEFAULT_MODEL=     # optional: defaults to a small built-in model

Both features degrade silently when this is unset — titles stay as the first message and no follow-up suggestions appear — so confirm the state from the backend's startup log rather than from the UI:

docker compose -f docker-compose.selfhost.yml logs backend | grep "llm layer"
# "llm layer enabled"  -> configured
# "llm layer disabled" -> unset; the two features above will not appear

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

3.8 KiB Raw Permalink Blame History