Configuration

archmax is configured through environment variables. Set them in your shell, .env file, or Docker Compose config.

Required Variables

Variable	Description	Example
BETTER_AUTH_SECRET	Session encryption secret (min 32 chars). Save this value and reuse it across restarts.	Generate with openssl rand -base64 32
UI_PASSWORD	Initial admin password	changeme

Caution

Save your BETTER_AUTH_SECRET somewhere safe. If you lose it or change it, all existing sessions and authentication data become invalid. You will need to re-authenticate after any change to this value.

Database

Variable	Default	Description
MONGODB_URI	(embedded)	MongoDB connection string. Optional in Docker: when omitted, the container starts an embedded MongoDB instance at /data/mongodb. Set this to use an external MongoDB (e.g. mongodb://localhost:27017/archmax).

Server

Variable	Default	Description
APP_BASE_URL	-	Public URL of this instance (e.g. https://archmax.example.com). Set this when running behind a reverse proxy. Automatically configures CORS allowed origins and auth callback URL.
PORT	3000	API server port
CORS_ORIGINS	(derived)	Comma-separated allowed origins. Defaults to APP_BASE_URL when set, otherwise http://localhost:5173. Override to allow additional origins.
AUTH_BASE_URL	(derived)	Public URL for auth callbacks. Defaults to APP_BASE_URL when set, otherwise http://localhost:PORT.

Tip

For most deployments behind a reverse proxy or on a cloud host, setting APP_BASE_URL is all you need. It derives both CORS_ORIGINS and AUTH_BASE_URL automatically. You only need to set those individually for advanced configurations (e.g. allowing multiple origins or using an internal auth URL).

Admin Credentials

Variable	Default	Description
UI_USERNAME	admin	Initial admin username (used to seed on first run)
UI_PASSWORD	-	Initial admin password

Log in at http://your-server:8080 with these credentials after deployment.

Security

Variable	Default	Description
ENCRYPTION_KEY	-	Encrypts database connection passwords and API keys at rest using AES-256-GCM. Generate with openssl rand -base64 32. Without this, credentials are stored in plaintext.

Caution

Save your ENCRYPTION_KEY and keep it consistent across restarts and upgrades. If you change or lose it, stored credentials become unreadable and you will need to re-enter all connection passwords and test agent API keys.

Data Directory

Variable	Default	Description
ARCHMAX_DATA_DIR	/data (Docker) or data (local)	Root data directory. All persistent data lives under this path: projects/ (semantic models), mongodb/ (embedded DB), .duckdb/ (extension cache).

Inside the Docker image, persistent application data lives under /data/:

Path	Contents	Persistent?
/data/projects/	Semantic model YAML files	Yes
/data/mongodb/	Embedded MongoDB data (when using embedded mode)	Yes
/data/.duckdb/	DuckDB extension cache	Yes
/tmp/redis/	Embedded Redis data	No (ephemeral)

A single bind mount (-v ~/.archmax:/data) maps the data directory to ~/.archmax on the host, including project files, the DuckDB extension cache, and embedded MongoDB data. When using an external MongoDB via MONGODB_URI, the mongodb/ directory is unused. See the Docker Reference for details.

MCP Server

Variable	Default	Description
MCP_RATE_LIMIT_MAX	120	Max requests per IP per 60-second window

AI Agent

Caution

AGENT_API_KEY is required for all AI-powered features: the Semantic Model Builder, Testing Playground, and automatic conversation title generation. Without it, these features will be unavailable and the chat interface will display a configuration warning.

Variable	Default	Description
AGENT_API_BASE_URL	https://openrouter.ai/api/v1	OpenAI-compatible API endpoint. Change this when using a provider other than OpenRouter.
AGENT_API_KEY	-	Required for agent features. API key for your chosen provider.
AGENT_MODEL	anthropic/claude-sonnet-4	Model identifier (must match your provider’s naming convention)
AGENT_TITLE_MODEL	-	Cheap/fast model for conversation title generation

Supported providers: OpenRouter (default), OpenAI, Azure OpenAI, Ollama, or any OpenAI-compatible endpoint. To get started quickly, create an account at openrouter.ai, generate an API key, and set AGENT_API_KEY to that value.

Worker Queue

Variable	Default	Description
REDIS_URL	(embedded)	Redis connection URL for BullMQ worker queue. Optional in Docker: when omitted, the container starts an embedded Redis instance. Without Redis (local dev), the agent runs in-process.
WORKER_CONCURRENCY	5	Number of concurrent agent jobs per worker

Testing

Variable	Default	Description
TEST_AGENT_MAX_ITERATIONS	100	Max tool call iterations for playground and batch test agents