Deployment and troubleshooting

Deployment paths

The repository includes local launch, Docker, remote deployment, reverse-proxy, and operating-system setup guides. Choose the smallest topology that satisfies your provider and worker needs.

Local and Docker operation

Local launch keeps the Rust core, database, model gateway, and workers inspectable during development. Docker Compose profiles package standard, monitoring, and performance-oriented service combinations.

Remote hosts and proxies

Remote deployments expose the control plane through HTTPS while keeping port 18789 behind the host firewall. Repository Caddy and nginx examples preserve HTTP and WebSocket forwarding; remote clients send the configured `X-Carnelian-Key` header.

• Use HTTPS for production access
• Expose the reverse proxy rather than port 18789 directly
• Add the public origin to cors_origins or CARNELIAN_CORS_ORIGINS
• Prefer a VPN or Tailscale when public exposure is unnecessary

Triage order

• Run carnelian status and confirm the daemon responds
• Inspect carnelian logs -f before retrying work
• Verify PostgreSQL migrations and pgvector availability
• Confirm the selected worker runtime and model provider are healthy
• For MAGIC, authenticate the provider or allow the OS CSPRNG fallback

Operational safety

Keep capability and approval boundaries intact in enterprise forks. A deployment that bypasses policy is not equivalent to the documented Karnelian execution model.