Deployment

auxilia can be deployed on anything that runs Docker containers. The stack consists of three services (plus an optional sandbox runtime):

Backend (FastAPI) — Python 3.12+
Web (Next.js) — Node.js 20+
Database — PostgreSQL 17 + Redis 7
Sandbox (optional) — OpenSandbox for code execution

The repository ships with:


backend/Dockerfile       # FastAPI backend
web/Dockerfile           # Next.js frontend
docker-compose.yml       # production compose file
docker-compose.dev.yml   # postgres + redis for local dev

Minimum environment

Variable	Required	Notes
`DATABASE_URL`	yes	`postgresql+psycopg://...` connection string
`REDIS_HOST` / `REDIS_PORT`	yes	Reachable from the backend (OAuth tokens are stored here)
`JWT_SECRET_KEY`	yes	32+ random characters
`SALT`	yes	Salt for AES-GCM encryption of stored MCP API keys
`FRONTEND_URL`	yes	Public URL of the web app (used as OAuth redirect base)
`BACKEND_URL`	yes (web)	Internal URL the Next.js proxy uses to reach the backend
`COOKIE_SECURE`	recommended	`true` in production (requires HTTPS)
One LLM key	yes	`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, or `DEEPSEEK_API_KEY`

Optional:

Google OAuth: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI, AUTH_GOOGLE_EXCLUSIVE
Langfuse: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL
Slack: SLACK_SIGNING_SECRET, SLACK_BOT_TOKEN
Sandbox: OPEN_SANDBOX_DOMAIN, OPEN_SANDBOX_API_KEY, OPEN_SANDBOX_USE_SERVER_PROXY

See the Get Started guide and .env.example for the full list.

Migrations

Alembic migrations run automatically at backend startup (alembic upgrade head is invoked by the entrypoint). No extra step is needed on deploy — just restart the backend when pulling a new image.

Reverse proxy / HTTPS

The web container listens on port 3000 and proxies /api/backend/* to the backend on port 8000. Put a TLS-terminating reverse proxy in front (Cloud Run, Nginx, Caddy, Cloudflare, …) and set COOKIE_SECURE=true, FRONTEND_URL=https://your-domain.

Deployment guides

Google Cloud Run — deploy on serverless containers with Cloud SQL and Memorystore