Security and privacy
Where Agent Grid stores credentials and tokens, what telemetry it sends, and which boundaries are enforced vs advisory.
This page covers the security and privacy surface of Agent Grid — credentials, mobile bearer tokens, the master orchestrator's blind-by-default canvas access, and the telemetry the app emits.
Master orchestrator: canvas-blind by default
A Claude pane becomes a "master" the first time it calls an MCP tool that spawns or associates panes. Until that point — and for every pane the master hasn't explicitly opted into — the master is canvas-blind:
- Read tools like
read_paneonly return content from panes the master has calledassociate_paneon. list_canvas_panesreveals pane ids and types but not their contents.
This means a master can't read another agent's transcript or a note's contents just because both panes exist on the same canvas. The master has to opt in to each pane it wants to read.
Per-master control token
Every master pane gets its own per-pane control token. When the master boots, Agent Grid:
- Materializes an MCP config on disk that points the Claude CLI at the master MCP server.
- Mints a fresh control token and writes it into the MCP config as the
AGENT_GRID_CONTROL_TOKENenvironment variable. - Hands the config path to
claude --mcp-config.
The MCP stdio child uses that token to authenticate against the localhost HTTP control server. The token is scoped to a single master and isn't reused across panes.
writePathPrefixes is advisory
writePathPrefixes on a role (for example browser_qa is contracted to write only under .agent-grid/qa-specs/) is advisory. The SDK does not block out-of-bounds writes. The orchestrator can audit a worker's writes after the fact, but nothing in the runtime enforces the boundary.
If you need a stronger boundary, pair a writePathPrefixes-constrained role with a reviewing role (qa, validator, or security) that catches misuse before it ships. See Roles.
Mobile bearer tokens
The mobile companion app pairs against the desktop over a local HTTP/WebSocket bridge. Pairing mints a long-lived bearer token used for every subsequent request from that device:
- Tokens are prefixed
agm_so they're easy to recognize. - Tokens are sha-256 hashed at rest. The desktop stores the hash, not the raw token; the raw token only lives on the paired device.
- The device store on the desktop is written with file mode
0o600(owner read/write only).
To revoke a paired device, remove it from the device list in Agent Grid's settings; the hashed entry is dropped and that token stops authenticating.
CLI authentication
Authentication for claude, codex, and agy is delegated to each CLI — Agent Grid doesn't read or store the underlying API keys. Sign in via the CLIs themselves (claude login, codex login, agy login or equivalent) before spawning panes that depend on them. Tokens persist in the CLI's own config directory in your home folder.
Telemetry
Agent Grid sends product telemetry to PostHog from both the renderer (posthog-js) and the main process (posthog-node). Telemetry covers anonymized usage events used to improve the product; it does not include the contents of your agent transcripts, notes, terminals, or browser panes.
If you need an explicit opt-out path or want to inspect what's emitted, ask the maintainers — the policy surface is still being documented for the GA launch.
Related
- Roles — the
writePathPrefixescontract and where it sits in the role model. - Logs and diagnostics — where local state lives if you want to inspect it.
- Updates — how the auto-updater works and where releases ship from.