Security and privacy
Where AgentGrid stores credentials and tokens, what telemetry it sends, and which boundaries are enforced vs advisory.
This page covers the security and privacy surface of AgentGrid — 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 harness pane with master MCP becomes a "master" the first time it calls a 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, AgentGrid:
- Materializes the harness-specific MCP configuration that points the agent at the master MCP server.
- Mints a fresh control token and writes it into the MCP config as the
AGENT_GRID_CONTROL_TOKENenvironment variable. - Launches the harness with that scoped configuration.
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 AgentGrid's settings; the hashed entry is dropped and that token stops authenticating.
CLI authentication
Authentication is delegated to each underlying harness. AgentGrid can run the harness's install and login flow inside the app, but provider credentials remain in that harness's own configuration rather than being copied into every pane. See Coding harness setup.
Telemetry
AgentGrid sends product telemetry to PostHog from both the renderer (posthog-js) and the main process (posthog-node). Telemetry covers anonymous usage and error events used to improve the product; it does not include code, prompts, file contents, agent transcripts, notes, terminals, or browser-pane contents.
Turn Share anonymous usage & error data off under Settings -> Privacy to opt out at any time. The setting is saved automatically.
Account identity and subscription status are separate from transcript content. Signing in associates product-level events with the account so AgentGrid can measure active use and enforce account entitlements; it does not make pane contents part of telemetry.
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.