---
title: "Configuration"
description: "An overview of the key environment variables: port, auth mode, metadata database, space topology, search."
---

# Configuration

Notarium is configured through **environment variables** — no secrets or paths are baked into the image. The defaults are built for zero-config: a fresh instance comes up without a single setting. This page is an overview of the key variables; the full list with exact values and defaults lives in the [Reference](/docs/reference/environment-variables/).

Configuration is set with `-e` flags on `docker run` or through an `.env` file (copied from `.env.example`). The Docker stack passes `.env` into the container as-is.

## Key variables

| Variable | Purpose | Default |
|---|---|---|
| `DATA_DIR` | The single data knob: the root everything else is derived from — metadata database, indexes, notes, artifacts. Unset → a working default is used. | `/data` (Docker); `~/.local/share/notarium` (host) |
| `PORT` | The port the backend listens on (`/api`, `/mcp`, and the web interface). | `3000` |
| `AUTH_MODE` | Authentication mode: `password` or `none`. | `password` |
| `META_DB_URL` | Metadata database: `sqlite:<path>` or `postgres://…`. Optional — set it only for an external Postgres; by default this is SQLite under `DATA_DIR`. | `sqlite:<DATA_DIR>/meta.db` |
| `SPACES_ROOT` | The root where each space is a folder; lets you create spaces from the interface. Optional — only if notes live outside `DATA_DIR`. | `<DATA_DIR>/spaces` |
| `VECTOR_SEARCH` | `on`/`off` — semantic (vector) search. | `off` in the published image (`on` in the code) |

Each topic is covered on its own page: [Authentication](/docs/self-hosting/authentication/) (`AUTH_MODE`), [Database](/docs/self-hosting/database/) (`META_DB_URL`), [Semantic search](/docs/self-hosting/search-setup/) (`VECTOR_SEARCH` and model parameters).

## Space topology

There are two ways to define spaces:

- **`SPACES_ROOT`** — zero-config: each space is a folder under the given root. Spaces are created on first run and with the "New space…" button in the interface. This is the Docker stack default.
- **`SPACES_CONFIG`** — an explicit, fixed topology (inline JSON or a path to a JSON file). A good fit when the set of spaces is defined by the operator and isn't created from the interface.

For the model of spaces and projects, see [Concepts](/docs/concepts/spaces-and-projects/).

## Agent authentication (OAuth)

Beyond personal tokens (PATs), Notarium can authorize MCP connectors over **OAuth** — so an agent (the Claude connector, for example) authenticates on its own, with no token to paste by hand. This needs no separate configuration: clients register dynamically. Behind a reverse proxy, set `PUBLIC_BASE_URL` (for example, `https://notes.example.com`) — a stable external address for the OAuth metadata; without it, the address is derived from the proxy's forwarded headers. Behind a proxy it's also worth setting `TRUST_PROXY`, so that the login and new-connector limits are counted against the client's real IP rather than the proxy's address — see [Production](/docs/self-hosting/production/). For more on connecting agents, see [Connect an agent](/docs/agents/connect/).

> [!tip] Full reference
> The search variables (`EMBED_MODEL`, `EMBED_DIMENSIONS`, `EMBED_CPU_MEM_ARENA`, and others), sync timings, and other fine-grained knobs are collected in the tables on the [Environment variables](/docs/reference/environment-variables/) page.

Next: set up [authentication](/docs/self-hosting/authentication/) and, if needed, [semantic search](/docs/self-hosting/search-setup/).