# Remote & Governed Nests

A 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 you run against a local vault work against a remote one, selected with `--vault`. A remote nest can also be **governed**: instead of accepting direct publishes, it routes writes through a review-and-approval workflow.

## Registering a remote

Remotes are registered with the same `ctx vault add` command used for local vaults — you pass a connection flag instead of a path. Two transports are supported: **streamable HTTP** (`--url`) and **stdio** (`--mcp-command`).

```bash
# HTTP remote — the bearer token is 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 — served by a local MCP command
ctx vault add legal-nest \
  --mcp-command contextnest-remote \
  --mcp-arg legal
```

`--mcp-arg` is repeatable; each occurrence adds one argument to the spawned command. (Note that `--vault` is a global flag, so pass remote-side vault selection as a plain `--mcp-arg` value rather than as `--mcp-command`'s own `--vault`.)

This writes a `remotes:` entry into `~/.contextnest/config.yaml`:

```yaml
remotes:
  team-nest:
    transport: http
    url: https://nest.example.com/mcp
    auth:
      bearer_env: TEAM_NEST_TOKEN     # env var name; the token itself is never stored
  legal-nest:
    transport: stdio
    command: contextnest-remote
    args:
      - legal
default: team-nest
```

Two things to know about auth:

- **The token lives in an environment variable, never in the config.** The registry stores only the *name* of the env var (`bearer_env`). At call time the CLI reads that variable; if it is unset you get `CONFIG_ERROR: Remote auth env var … is not set`.
- **Use an HTTPS endpoint.** The bearer token is sent to the `--url` endpoint, so it should be reached over TLS.

`ctx vault list` shows remotes alongside local vaults (marked `[remote:http]` / `[remote:stdio]`), and `ctx vault which` reports which nest a command would resolve to.

### Hosted nests on a ContextNest Community server

A Community server (including the hosted one) exposes two MCP endpoint shapes, and both register with `--url`:

| Endpoint | Registers |
|---|---|
| `https://<server>/nests/<nest-id>/mcp` | One nest. Use the alias as-is: `--vault <alias>`. |
| `https://<server>/mcp` | The whole server: every nest the key can see. Pick a nest per command with `--vault <alias>/<nest>`. |

```bash
export CONTEXTNEST_API_KEY=cnst_...   # from the nest's Connect dialog
ctx vault add promptowl --url https://nest.promptowl.ai/mcp --bearer-env CONTEXTNEST_API_KEY
ctx vault list                         # lists promptowl/<nest> for each nest behind the alias
ctx --vault promptowl/my-nest search "pricing"
```

`<nest>` is the nest's name slugged to lowercase (with the first eight characters of its id appended when two visible nests slug the same), or the nest id. An unknown name fails with the list of available labels. The nest list is cached for five minutes; a nest created or shared since then is picked up on the next miss. Adding a `/<nest>` suffix to a per-nest alias, or to a local vault, is an error.

`ctx read`, `add`, `update`, `delete`, `move`, `publish`, `history`, `list`, `search`, `query`, and `verify` all work against a remote alias. `ctx pull <alias>/<nest> --recipe <id>` copies a recipe from a remote nest into a local vault; `ctx push` sends a local vault to a hosted nest (see [CLI Reference](https://nest.promptowl.ai/d/promptowl-documents/protocol/cli-reference)).

## Routing to a remote

Once registered, select a remote with the global `--vault` flag from any directory. ContextNest routes the operation to that remote over MCP:

```bash
# Query a remote nest
ctx --vault team-nest query "pricing decisions"

# Inspect resolution
ctx --vault team-nest vault which
```

The command surface is the same whether the vault is local or remote — the transport is transparent. An unreachable endpoint surfaces as `REMOTE_UNREACHABLE`. See [Vault Registry & Multi-Vault](https://nest.promptowl.ai/d/promptowl-documents/protocol/vault-registry/vault-registry-multi-vault) for how aliases resolve.

## Governed nests

A **governed** nest does not accept direct publishes — writes are proposed and must be approved before they become published documents:

1. A client submits a proposed change for review (`context_submit_review`). The change enters the `pending_review` state rather than publishing straight to `published`.
2. A steward reviews and either approves it — moving it toward `published` — or rejects it. Approval is a steward action on the hosting platform (the Community server / hosted nest), not a local `ctx` verb.

This maps onto the document status lifecycle: `draft → pending_review → approved → published` (with `rejected` as the terminal reject state). See [Status Lifecycle](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/status-lifecycle) and, for the hosted-side reviewer experience, the platform [Governance](https://nest.promptowl.ai/d/promptowl-documents/platform/governance/governance-stewardship) page.

### Roadmap

Deeper server-enforced integrity for governed remotes — where the server, not the client, is the sole authority on whether a document's hash chain and checkpoint are valid, so a compromised client cannot smuggle unverified content into the nest — is a planned hardening of this model. Today, integrity verification runs client-side via `ctx verify` (see [Integrity Verification](https://nest.promptowl.ai/d/promptowl-documents/protocol/versioning/integrity-verification)); the review-and-approval gate above is what a governed nest enforces in the current build.

## Related

- [Vault Registry & Multi-Vault](https://nest.promptowl.ai/d/promptowl-documents/protocol/vault-registry/vault-registry-multi-vault) — alias resolution and `--vault`
- [Status Lifecycle](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/status-lifecycle) — review states
- [MCP Server](https://nest.promptowl.ai/d/promptowl-documents/protocol/mcp-server) — transport and MCP operations
- [Authentication & API Keys](https://nest.promptowl.ai/d/promptowl-documents/protocol/authentication-api-keys) — minting the `cnst_` key a remote alias uses
- [Hosted Nest](https://nest.promptowl.ai/d/promptowl-documents/platform/hosted-nest/hosted-nest) — what a Community server adds over a local vault
- [Governance](https://nest.promptowl.ai/d/promptowl-documents/platform/governance/governance-stewardship) — the steward-side review queue