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).

# 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:

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:

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).

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:

# 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 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 and, for the hosted-side reviewer experience, the platform Governance 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); the review-and-approval gate above is what a governed nest enforces in the current build.

Related

• Vault Registry & Multi-Vault — alias resolution and --vault
• Status Lifecycle — review states
• MCP Server — transport and MCP operations
• Authentication & API Keys — minting the cnst_ key a remote alias uses
• Hosted Nest — what a Community server adds over a local vault
• Governance — the steward-side review queue