Skip to Content
Get Started

Get Started

This guide walks you through running auxilia locally with Docker Compose.

Prerequisites

  • Docker  and Docker Compose
  • At least one LLM API key (Anthropic, OpenAI, Google, or DeepSeek)

1. Clone the repository

git clone https://github.com/keurcien/auxilia.git
cd auxilia

2. Configure environment

Copy the example environment file:

cp .env.example .env

The minimum configuration you need is a database URL, a JWT secret, an MCP encryption salt, and at least one LLM API key:

# Database
DATABASE_URL=postgresql+psycopg://auxilia:auxilia@localhost:5432/auxilia

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# At least one LLM provider
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...
DEEPSEEK_API_KEY=...

# Auth
JWT_SECRET_KEY=change-me-in-production
COOKIE_SECURE=false
FRONTEND_URL=http://localhost:3000

# MCP API-key encryption
SALT=changeme

# Backend URL — used by the Next.js proxy (server-side only)
BACKEND_URL=http://localhost:8000

Optional:

# Google OAuth sign-in
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=http://localhost:8000/auth/google/callback
AUTH_GOOGLE_EXCLUSIVE=false    # set to true to disable password signup

# Code-execution sandbox (see /docs/sandbox)
OPEN_SANDBOX_DOMAIN=localhost:8083
OPEN_SANDBOX_API_KEY=your-key
OPEN_SANDBOX_USE_SERVER_PROXY=true
OPEN_SANDBOX_VOLUME_MOUNTS=    # e.g. "~/.config/gcloud:/root/.config/gcloud:ro"
OPEN_SANDBOX_DEFAULT_IMAGE=    # e.g. keurcien/opensandbox-sandbox-image:latest

# Langfuse observability (see /docs/integrations/langfuse)
LANGFUSE_PUBLIC_KEY=pk-...
LANGFUSE_SECRET_KEY=sk-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

# Slack integration (see /docs/integrations/slack)
SLACK_SIGNING_SECRET=
SLACK_BOT_TOKEN=xoxb-...

# Tuning & debugging
LOG_LEVEL=INFO                 # set to DEBUG for verbose logs (MCP traces, etc.)
RECURSION_LIMIT=100            # max LangGraph steps per agent invocation

3. Start the stack

The fastest way to get everything running with hot reload:

make dev

This starts PostgreSQL, Redis, the FastAPI backend (with Alembic migrations) and the Next.js frontend in parallel.

Equivalent individual commands:

make dev-stack       # docker compose -f docker-compose.dev.yml up (postgres, redis)
make dev-backend     # alembic upgrade head + uvicorn with reload
make dev-frontend    # next dev

For production (Docker Compose):

make build           # or: docker compose build
make up              # docker compose up -d

4. Create the first admin account

Open http://localhost:3000 . The first account you create becomes the workspace admin. After that, new accounts require an invite from an admin.

5. Add an MCP server

Navigate to MCP Servers in the sidebar and either:

  • Click Install on one of the official servers (Notion, Linear, GitHub, HubSpot, BigQuery, …), or
  • Click Add MCP Server to register any remote MCP server by URL.

See MCP Servers for the full registration flow and auth options.

6. Create an agent

  1. Go to Agents → Create Agent
  2. Set a name, emoji, and color
  3. Write a system prompt (instructions)
  4. Bind one or more MCP servers
  5. Open a chat and send a message

Next steps

  • Agents — full configuration, permissions, subagents
  • Tool Settings — approval rules per tool
  • Sandbox — enable code execution for an agent
  • Deployment — move from local to production
IntroductionOverview