Documentation

Get Started

Connect Client

Point your MCP-capable client at the local bridge and understand the local-first prep artifacts.

Connect your AI client after the workspace is prepared. This keeps the setup simple: login, init, connect, then open the client in the same workspace.

Connection flowLink to connection-flow

  1. Run bardo login from the workspace root.
  2. Approve the browser session.
  3. Run bardo init if the workspace has not been prepared yet.
  4. Run bardo connect --client codex or the matching client flag.
  5. Open the client from the same workspace.

Expected result: Bardo writes the client config file for that workspace, and the client can see the local Bardo connection the next time it starts.

why this is neededLink to why-this-is-needed

Bardo uses a local MCP endpoint so the client can work directly from your local workspace and .bardo/ prep layer. The browser approval is still necessary because Bardo needs hosted account approval, billing, entitlements, and bridge-session checks before the local bridge starts serving the client.

This is the split:

  • hosted side: sign-in, browser approval, billing, entitlements, token refresh, runtime status
  • local side: workspace discovery, rules bootstrap, campaign bootstrap, current state, committed canon, scene resolution

Client-specific guidesLink to client-specific-guides

Exact commandsLink to exact-commands

cd ~/projects/my-campaign
bardo login
bardo init
bardo connect --client codex

If the rulebook is inside the workspace but not at the root:

bardo init --rulebook ./rules/core-rulebook.md

bardo init writes its prep layer into .bardo/, including:

  • .bardo/rules/rulebook.md
  • .bardo/rules/normalized/index.json
  • .bardo/manifests/source-index.json
  • .bardo/entities/campaign-entities.json
  • .bardo/state/current-state.json
  • .bardo/simulation/tracking-profile.json
  • .bardo/manifests/readiness.json

What you approveLink to what-you-approve

The browser approval confirms account access for the bridge session. The hosted side handles approvals, billing, entitlements, status checks, and token refresh. It does not own your campaign truth.

Approval must happen in a signed-in browser session. A direct unauthenticated curl or script POST to /api/connect/bridge-session/approve should return 401 Unauthorized; that protects the bridge from being approved outside your account session.

Paid access is Pro. Legacy Clerk solo subscriptions are accepted as Pro-equivalent access while older billing records finish migrating.

Local MCP endpointLink to local-mcp-endpoint

After approval, your client talks to the local MCP endpoint exposed by the Bardo bridge. That endpoint exists so the client can use workspace files and .bardo/ artifacts without sending your campaign into a hosted gameplay service.

what stays localLink to what-stays-local

Workspace discovery, rules bootstrap, campaign bootstrap, and local play state stay on your machine. The generated .bardo/ artifacts are the prep layer your client should rely on before continuing play.

If .bardo/ goes missing, stop and re-run bardo init. Bardo is designed to fail closed instead of silently recreating canon during a turn.

If the table explicitly corrects a fact, record that correction through Bardo instead of leaving it buried in chat history.

Session hygieneLink to session-hygiene

Treat 429 responses from hosted routes as backpressure on approvals or status checks. Wait, retry, and avoid hammering the bridge.

Troubleshooting:

  • If the client does not see Bardo, restart the client after bardo connect.
  • If readiness is not ready, fix the missing campaign inputs before expecting richer play.
  • If the workspace lost .bardo/, rebuild it with bardo init before resuming play.
  • If bardo login says the bridge session expired or was not found, start a fresh login after confirming the hosted deployment is using durable bridge storage rather than /tmp.