Vault & Registry Configuration

Context Nest reads configuration from two places:

1. Per-vault config — .context/config.yaml inside each vault (vault name, layout, federation, source-server registry, telemetry).
2. Central registry — ~/.contextnest/config.yaml in the user's home directory. This is a machine-wide registry that names vaults and remotes so you can refer to them by alias from anywhere.

Central registry (~/.contextnest/config.yaml)

The central registry holds a vaults: map (alias → local vault), an optional remotes: map (alias → hosted / MCP nest connection), and a default alias. Entries are written by ctx vault add, so you rarely edit this file by hand.

# ~/.contextnest/config.yaml

version: 1
default: work                     # default alias when none is specified

# Local vaults: alias -> { path, description? }
vaults:
  work:
    path: ~/my-vault
    description: "Primary vault"
  scratch:
    path: ~/scratch-vault

# Remote nests: alias -> connection (written by `ctx vault add --url|--mcp-command`)
remotes:
  team:
    transport: http
    url: "https://nest.example.com/mcp"    # send the bearer token over TLS
    auth:
      bearer_env: TEAM_NEST_TOKEN          # env-var NAME; the token is never stored
  legal:
    transport: stdio
    command: "contextnest-remote"
    args:
      - legal

The registry directory defaults to ~/.contextnest and can be relocated with the CONTEXTNEST_CONFIG_DIR environment variable.

Vaults

vaults: maps a short alias to a local vault so commands can target it by name (for example --vault work) instead of a full path. Each entry is an object with a path and an optional description. Register one with ctx vault add <alias> <path>.

Remotes

remotes: maps an alias to a nest reached over MCP. Two transports are supported:

• http — a streamable-HTTP endpoint (url), with a bearer token read at call time from the env var named in auth.bearer_env. The token value itself is never written to the config; only the variable name is stored. If that variable is unset, the CLI errors with CONFIG_ERROR rather than calling out unauthenticated.
• stdio — a local MCP server spawned as command with args.

Register remotes with ctx vault add <alias> --url … --bearer-env … or ctx vault add <alias> --mcp-command … --mcp-arg …. See Remote & Governed Nests.

Resolution precedence

When a command needs to decide which vault to operate on, the engine's resolveVaultPath resolves in this order (first match wins):

1. --vault flag — an explicit registered alias on the command line.
2. CONTEXTNEST_VAULT env var — a registered vault alias from the environment.
3. CONTEXTNEST_VAULT_PATH env var — a direct vault path from the environment.
4. An explicit path argument — a path passed to the command.
5. The current-working-directory vault — the nearest vault found by walking up from cwd for a .context/config.yaml.
6. default: in the central registry — the default alias declared in ~/.contextnest/config.yaml.
7. Bare cwd — the working directory as a last resort.

Note the two environment variables are distinct: CONTEXTNEST_VAULT names a registered alias, while CONTEXTNEST_VAULT_PATH is a direct path. Also note the cwd/local vault is checked before the registry default — a vault you are standing in wins over the configured default.

Confirmed against the engine's resolveVaultPath; env-var names and this ordering are taken from that code.

Per-vault config (.context/config.yaml)

name: "My Project"
namespace: "my-project"
layout: structured          # structured or obsidian
federation: none            # none, federated, or scoped

# Server registry for source nodes
servers:
  jira:
    url: "https://mycompany.atlassian.net"
    transport: mcp
  github:
    url: "https://api.github.com"
    transport: mcp
  slack:
    url: "https://slack.com/api"
    transport: rest

# Telemetry (opt-in, metadata only, never vault content)
telemetry: false

Per-vault fields

Environment variables

CONTEXT.md

The CONTEXT.md file at the vault root is a free-form markdown file that serves as the vault-level system prompt. AI agents read it first before accessing individual documents.

Write it to describe:

• What the vault is for
• How the agent should interact with it
• Any conventions or rules specific to your team

Related

• Vault Registry & Multi-Vault — managing aliases with ctx vault
• Remote & Governed Nests — the remotes: map in practice
• CLI Reference — the ctx command surface
• Authentication & API Keys — cnst_ keys for push and remotes