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.
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 (AUTH_MODE), Database (META_DB_URL), Semantic search (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.
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. For more on connecting agents, see Connect an agent.
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 page.
Next: set up authentication and, if needed, semantic search.