Install - Perceo

Archivum runs in Docker on your own machine or server.

Requirements

Docker Engine 24+ with Docker Compose v2
Node.js 20+
An Anthropic API key, an OpenRouter key, an OpenAI-compatible endpoint, or a local Ollama setup

Guided install

git clone https://github.com/perceo-ai/archivum.git
cd archivum
./install.sh

git clone https://github.com/perceo-ai/archivum.git
cd archivum
.\install.ps1

The installer writes .env, generates any missing secrets, and starts the Docker Compose stack. By default it pulls published images through docker-compose.images.yml. To build from source instead:

./install.sh --build

Manual setup

cp .env.example .env
# Fill in OWNER_PASSWORD, JWT_SECRET, MCP_API_KEY, and your LLM provider key.
docker compose -f docker-compose.yml -f docker-compose.images.yml up -d --no-build

Endpoints

URL	Purpose
`http://localhost`	Web app through Caddy
`http://localhost:8473`	Direct frontend container port
`http://localhost/api/*`	REST API through Caddy
`http://localhost:8001/sse`	MCP HTTP/SSE endpoint

Configuration

The values that matter most in .env:

Variable	Required	Notes
`OWNER_USERNAME`	No	Login username. Defaults to `admin`.
`OWNER_PASSWORD`	Yes	First-boot owner password. Hashed on startup.
`JWT_SECRET`	Yes	Generate with `openssl rand -hex 32`.
`MCP_API_KEY`	Yes	Bearer token for MCP clients. Generate with `openssl rand -hex 24`.
`LLM_EXTRACTION_PROVIDER`	No	`anthropic`, `openrouter`, `openai_compat`, or `ollama`.
`LLM_SYNTHESIS_PROVIDER`	No	Same options as extraction.
`ANTHROPIC_API_KEY`	Provider-specific	Required when using Anthropic.
`OPENROUTER_API_KEY`	Provider-specific	Required when using OpenRouter.
`OPENAI_COMPAT_API_KEY`	Provider-specific	Required for OpenAI-compatible providers.
`EMBED_PROVIDER`	No	`local`, `openai_compat`, `openrouter`, or `ollama`. Defaults to local fastembed.
`ARCHIVUM_HOST`	No	Public hostname for Caddy TLS. Leave unset for local use.
`PUBLIC_WIKI_ENABLED`	No	Set `true` to expose read-only `/public` wiki pages.

OWNER_PASSWORD, JWT_SECRET, and MCP_API_KEY are what stand between your wiki and anyone who can reach the port. Set real values before exposing Archivum beyond localhost.

.env.example in the repo is the full reference.

Set LLM_EXTRACTION_PROVIDER and EMBED_PROVIDER to ollama to run everything against a local model. Nothing leaves the machine.

Media ingest

Published images omit Whisper, Torch, and ffmpeg to keep installs smaller. For local audio and video transcription:

cd apps/backend
uv sync --extra audio
# Install ffmpeg with your OS package manager for video files.

MCP client setup

Archivum exposes both stdio and HTTP/SSE MCP transports.

Claude Desktop (stdio)

{
  "mcpServers": {
    "archivum": {
      "command": "docker",
      "args": ["exec", "-i", "archivum-mcp", "python", "-m", "archivum.mcp.server", "--stdio"],
      "env": { "MCP_API_KEY": "your-mcp-api-key" }
    }
  }
}

Editors and web clients (HTTP/SSE)

{
  "mcpServers": {
    "archivum": {
      "url": "http://localhost:8001/sse",
      "headers": { "Authorization": "Bearer your-mcp-api-key" }
    }
  }
}

Works for Cursor, Windsurf, VS Code, and anything else that speaks MCP over SSE.

Core tools exposed to clients:

Tool	Purpose
`ingest_source`	Ingest a file path or URL into the wiki
`search_wiki`	Semantic search over wiki pages
`list_pages` / `get_page`	Read wiki pages

Uninstall

./uninstall.sh

Removes the containers and network but keeps your data. The repo documents flags for also dropping volumes, images, and local files.

Dropping volumes permanently deletes your wiki content. There is no undo.

​Requirements

​Guided install

​Manual setup

​Endpoints

​Configuration

​Media ingest

​MCP client setup

​Uninstall

Requirements

Guided install

Manual setup

Endpoints

Configuration

Media ingest

MCP client setup

Uninstall