> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Install

> Guided installer, manual Docker Compose, configuration, and MCP client setup.

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

<CodeGroup>
  ```bash Linux / macOS theme={"dark"}
  git clone https://github.com/perceo-ai/archivum.git
  cd archivum
  ./install.sh
  ```

  ```powershell Windows theme={"dark"}
  git clone https://github.com/perceo-ai/archivum.git
  cd archivum
  .\install.ps1
  ```
</CodeGroup>

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:

```bash theme={"dark"}
./install.sh --build
```

## Manual setup

```bash theme={"dark"}
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
```

Log in with `OWNER_USERNAME` from `.env` — `admin` by default — and the
`OWNER_PASSWORD` you configured.

## 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.                              |

<Warning>
  `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.
</Warning>

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

<Tip>
  Set `LLM_EXTRACTION_PROVIDER` and `EMBED_PROVIDER` to `ollama` to run
  everything against a local model. Nothing leaves the machine.
</Tip>

## Media ingest

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

```bash theme={"dark"}
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.

<AccordionGroup>
  <Accordion title="Claude Desktop (stdio)">
    ```json theme={"dark"}
    {
      "mcpServers": {
        "archivum": {
          "command": "docker",
          "args": ["exec", "-i", "archivum-mcp", "python", "-m", "archivum.mcp.server", "--stdio"],
          "env": { "MCP_API_KEY": "your-mcp-api-key" }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Editors and web clients (HTTP/SSE)">
    ```json theme={"dark"}
    {
      "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.
  </Accordion>
</AccordionGroup>

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

```bash theme={"dark"}
./uninstall.sh
```

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

<Warning>
  Dropping volumes permanently deletes your wiki content. There is no undo.
</Warning>