Configuration

archmax semantics 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	Admin password. Reapplied to the admin account on every API startup.	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://semantics.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	Admin username (used to seed on first run)
UI_PASSWORD	-	Admin password. Reapplied to the admin account on every API startup.

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

Caution

UI_PASSWORD is the source of truth for the admin password. On every API startup the value is verified against the stored credential and, if it differs, the credential is replaced with the current UI_PASSWORD. To rotate the admin password, change UI_PASSWORD and restart the API. Any password change made through the admin UI will be overwritten on the next restart unless UI_PASSWORD is updated to match.

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
SEMANTICS_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).
ARCHMAX_DATA_DIR	-	Deprecated. Pre-rename alias for SEMANTICS_DATA_DIR. Still honoured (with a startup warning) so existing deployments keep working; SEMANTICS_DATA_DIR wins when both are set.

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