Installation

Docker Compose (Recommended)

The fastest way to run archmax is with Docker Compose. This starts archmax with dedicated MongoDB and Redis services, which is the recommended setup for production use:

git clone https://github.com/archmaxai/archmax.git
cd archmax
cp .env.example .env

Edit .env and set the required values:

BETTER_AUTH_SECRET=$(openssl rand -base64 32)
UI_USERNAME=admin
UI_PASSWORD=your-secure-password
AGENT_API_KEY=your-api-key

Caution

Save your BETTER_AUTH_SECRET somewhere safe (e.g. a password manager or secrets vault). If you lose this value or change it later, all existing sessions and authentication data become invalid. You will need this exact value when upgrading or restarting the container.

Note

AGENT_API_KEY is required for the AI-powered Semantic Model Builder, Testing Playground, and automatic title generation. The default provider is OpenRouter. You can also use OpenAI, Azure OpenAI, Ollama, or any OpenAI-compatible endpoint by changing AGENT_API_BASE_URL. Without this key, agent features will be unavailable.

Then start the stack:

docker compose up -d

Open http://localhost:8080 and log in with the username and password you configured (UI_USERNAME / UI_PASSWORD). The default username is admin.

Note

If you’re deploying behind a reverse proxy or on a cloud host with a custom domain, add APP_BASE_URL=https://your-domain.com to your .env file. Without it, authentication will fail with an “invalid origin” error. See the Configuration reference for details.

Tip

The Compose stack runs MongoDB and Redis as separate containers alongside archmax. Two Docker volumes persist data across restarts:

Volume	Container Path	Contents
archmax-data	/data	Semantic model YAML files, DuckDB extension cache
mongo-data	/data/db (mongo container)	MongoDB database files

These volumes are created automatically. Without them, all project and database data would be lost when containers are removed. See the Docker Reference for details.

Standalone Docker

Run archmax as a single container with no external dependencies. MongoDB and Redis are embedded in the image and start automatically:

docker run -d \
  --name archmax \
  -p 8080:8080 \
  -e BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
  -e UI_USERNAME=admin \
  -e UI_PASSWORD=changeme \
  -e AGENT_API_KEY=your-api-key \
  -v ~/.archmax:/data \
  ghcr.io/archmaxai/archmax:latest

Open http://localhost:8080 and log in with username admin and the password you set.

Caution

Save your BETTER_AUTH_SECRET value before running this command. The subshell $(openssl rand ...) generates a random secret that is not displayed. Either generate it beforehand and paste the value, or retrieve it after starting with docker inspect archmax --format '{{range .Config.Env}}{{println .}}{{end}}' | grep BETTER_AUTH_SECRET.

Note

MongoDB and Redis are both embedded in the image and start automatically when MONGODB_URI / REDIS_URL are not provided. To use external instances instead, pass MONGODB_URI and/or REDIS_URL. The bind mount at /data maps the container’s data directory so project files, embedded MongoDB data, and the DuckDB extension cache (.duckdb/) persist under ~/.archmax on the host.

When to use which mode?

• Docker Compose is recommended for production and long-term use. It separates MongoDB and Redis into their own containers, making backups, monitoring, and upgrades easier. You can also swap in a managed MongoDB service (Atlas, DocumentDB).
• Standalone Docker is ideal for quick evaluation, demos, or simple single-user setups. Everything runs in one container with zero external dependencies.

Local Development

For contributing or local development, see the Development Setup guide.

Next Steps

• See the full Configuration reference for all environment variables
• Read the Docker Reference for volumes, entrypoint behavior, and troubleshooting
• Check the Self-Hosting Guide for backup, upgrade, and production tips