Configuration & Environment Variables

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• scripts/install.py
• apps/backend/archivum/ingest/agent.py
• apps/backend/archivum/mcp/server.py
• archivum-prd-v1.0.md
• packages/archivum-cli/src/api.js

Archivum utilizes a centralized configuration system driven primarily by environment variables defined in a .env file. This system manages critical parameters for the self-hosted stack, including Large Language Model (LLM) provider settings, security credentials, database connection strings, and network visibility options.

The configuration architecture is designed for a "local-first" deployment model, where sensitive data like API keys and passwords remain within the user's infrastructure. It supports multiple LLM providers (Anthropic, OpenRouter, OpenAI-compatible, and Ollama) to allow for flexibility between cloud-based and fully local, air-gapped operations. Sources: README.md:195-200, archivum-prd-v1.0.md:580-585.

Configuration Management & Initialization

The project employs an interactive installation script (install.py) to guide users through the initial setup of environment variables. This script parses .env.example to create a local .env file, ensuring that critical secrets like JWT_SECRET and MCP_API_KEY are generated automatically if not provided.

Configuration Flow

The following diagram illustrates how configuration is established during the initial setup and consumed by the backend services.

The install.py script validates that the environment contains necessary configurations for selected providers before starting the Docker stack. Sources: scripts/install.py:90-110, scripts/install.py:165-175.

Core Environment Variables

Archivum distinguishes between required operational secrets and optional provider-specific settings.

Security and Access

Variable	Required	Default	Description
JWT_SECRET	Yes	—	Used to sign authentication tokens. Generated during install.
OWNER_PASSWORD	Yes	changeme	Password for the admin account on first boot.
OWNER_USERNAME	No	admin	Username for the owner account.
MCP_API_KEY	Yes	—	Bearer token required for MCP server access.
ARCHIVUM_HOST	No	localhost	Public hostname used for Caddy TLS provisioning.

Sources: README.md:158-166, scripts/install.py:34-45

LLM & Embedding Providers

Archivum allows for independent configuration of the extraction agent (which structures wiki pages) and the synthesis engine (which answers queries).

Variable	Provider Options	Default	Description
LLM_EXTRACTION_PROVIDER	anthropic, openrouter, openai_compat, ollama	anthropic	Provider for entity/relationship extraction.
LLM_SYNTHESIS_PROVIDER	anthropic, openrouter, openai_compat, ollama	anthropic	Provider for generating query answers.
LLM_MODEL	—	claude-haiku-4-5-20251001	Specific model for extraction.
LLM_SYNTHESIS_MODEL	—	claude-sonnet-4-6	Specific model for synthesis.
EMBED_PROVIDER	local, openai_compat, openrouter, ollama	local	Provider for vector embeddings.

Sources: README.md:170-180, scripts/install.py:46-55

Provider Specific Configuration

Different LLM providers require specific API keys and base URLs. The WikiAgent and MCP server dynamically select clients based on these configurations.

Client Selection Logic

Configuration Requirements by Provider

• Anthropic: Requires ANTHROPIC_API_KEY.
• OpenRouter: Requires OPENROUTER_API_KEY and defaults to https://openrouter.ai/api/v1.
• Ollama: Requires OLLAMA_BASE_URL (typically http://localhost:11434 or http://host.docker.internal:11434 for Docker).
• OpenAI Compatible: Requires OPENAI_COMPAT_API_KEY and OPENAI_COMPAT_BASE_URL.

Sources: README.md:181-190, scripts/install.py:56-65

Infrastructure and Storage Configuration

The system defines local directory paths and database URLs, which are usually passed as environment variables to the backend container via Docker Compose.

Variable	Role	File System Path (Container)
WIKI_DIR	Canonical Markdown storage	/data/wiki
RAW_DIR	Original source uploads	/data/raw
DB_PATH	SQLite metadata database	/data/archivum.db
KUZU_PATH	Embedded graph database	/data/kuzu
QDRANT_URL	Vector store endpoint	http://qdrant:6333

Sources: README.md:144-154, README.md:270-280

Implementation Details

Configuration Parsing (Python)

The backend uses a Settings class (typically leveraging Pydantic) to load and validate these variables. This is utilized in the WikiAgent for selecting the extraction pipeline:

# apps/backend/archivum/ingest/agent.py:102-108
class WikiAgent:
    def __init__(self, settings: Settings | None = None):
        self.settings = settings or get_settings()
        self._client = (
            anthropic.Anthropic(api_key=self.settings.anthropic_api_key)
            if self.settings.llm_extraction_provider == "anthropic"
            else None
        )

Authorization Header Handling

The archivum-cli and frontend utilize the MCP_API_KEY to authenticate requests to the backend REST API via the Authorization: Bearer <key> header. Sources: packages/archivum-cli/src/api.js:7-12, apps/backend/archivum/mcp/server.py:44-48.

Summary

The configuration system in Archivum centralizes environment-based control to ensure the platform can adapt to various local and cloud environments. By leveraging the .env file and an interactive setup script, the project maintains a balance between ease of deployment and granular control over data privacy and AI model selection. Sources: README.md:155, scripts/install.py:530-540.