PromptOwl + ContextNest Docs
Contents

Vault Registry & Multi-Vault

Updated Open in ChatGPTOpen in Claude

ContextNest keeps a central vault registry so you can work with many nests from any directory. The registry maps a short alias to a nest — a local path or a remote connection — and the global --vault <alias> flag selects which one a command targets. This turns a machine with a dozen vaults — personal brain, team nests, client nests — into a single addressable set.

The registry file

The registry lives at ~/.contextnest/config.yaml. Local vaults go in a vaults: map (alias → { path, description? }); remotes go in a remotes: map (see Remote & Governed Nests). A default key names the alias used when nothing else selects one.

version: 1
default: brain

vaults:
  brain:
    path: ~/my-vault
  docs:
    path: ~/docs-nest

remotes:
  team-nest:
    transport: http
    url: https://nest.example.com/mcp
    auth:
      bearer_env: TEAM_NEST_TOKEN

You normally don't hand-edit this file — ctx vault add writes it for you.

Managing vaults

The ctx vault command group manages the registry.

Command Purpose
ctx vault add <alias> <path> Register a local vault under an alias.
ctx vault list List all registered vaults and remotes.
ctx vault remove <alias> Unregister an alias.
ctx vault prune Unregister local aliases whose vault folder no longer exists (remotes are left alone).
ctx vault default <alias> Set the default vault.
ctx vault which Show which nest the current context resolves to, and why.

Add --description "<text>" to label an alias, or --set-default to make it the default as you register it.

Remotes are registered with the same command, using a connection flag instead of a path:

# HTTP remote (bearer token read from an env var, stored only by reference)
ctx vault add team-nest --url https://nest.example.com/mcp --bearer-env TEAM_NEST_TOKEN

# stdio remote (spawns a local MCP command; --mcp-arg is repeatable)
ctx vault add legal-nest --mcp-command contextnest-remote --mcp-arg legal

For a ContextNest Community server, --url takes either a per-nest endpoint (https://<server>/nests/<id>/mcp) or the server-level endpoint (https://<server>/mcp). A server-level alias reaches every nest its key can see: ctx vault list lists each one as <alias>/<nest>, and --vault <alias>/<nest> targets it.

See Remote & Governed Nests for transports, auth, and routing.

Resolution precedence

When a command needs to know which nest to act on, ContextNest resolves it in this order, highest priority first (first match wins):

Priority Source
1 --vault <alias> flag (or --vault <alias>/<nest> for a server-level remote)
2 CONTEXTNEST_VAULT env var (a registered alias)
3 CONTEXTNEST_VAULT_PATH env var (a direct path)
4 An explicit path argument on the command
5 The vault found by walking up from the current working directory
6 The default alias in config.yaml
7 Bare cwd, as a last resort

Note that the current-directory vault (5) is checked before the registry default (6) — a vault you are standing in wins over the configured default. A stale CONTEXTNEST_VAULT or CONTEXTNEST_VAULT_PATH is ignored with a warning rather than blocking the command; a bad --vault alias is an error. Use ctx vault which to see the outcome for your current context.

Related pages

  • CLI ReferenceThe Context Nest CLI (ctx) is a structured, versioned knowledge base your AI agents can query. It provides commands for setting up vaults, creating and…
  • Remote & Governed NestsA nest does not have to live on your local disk. ContextNest can register remote nests and route reads and writes to them over MCP — the same ctx commands…
  • Vault & Registry ConfigurationContext Nest reads configuration from two places: The central registry holds a vaults: map (alias → local vault), an optional remotes: map (alias → hosted…
  • Install the ctx CLIThe package installs with a flattened dependency tree — its runtime dependencies are bundled/flattened so a global install pulls a self-contained CLI…
  • Authentication & API KeysContextNest Community distinguishes two kinds of key, and it is worth keeping them straight:

Referenced by