# Vault Registry & Multi-Vault

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](https://nest.promptowl.ai/d/promptowl-documents/protocol/remote-nests/remote-governed-nests)). A `default` key names the alias used when nothing else selects one.

```yaml
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:

```bash
# 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](https://nest.promptowl.ai/d/promptowl-documents/protocol/remote-nests/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

- [Remote & Governed Nests](https://nest.promptowl.ai/d/promptowl-documents/protocol/remote-nests/remote-governed-nests) — remote transports and routing
- [Configuration](https://nest.promptowl.ai/d/promptowl-documents/protocol/configuration) — the full `config.yaml` reference
- [CLI Reference](https://nest.promptowl.ai/d/promptowl-documents/protocol/cli-reference) — the `ctx` command surface