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.

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_pane only return content from panes the master has called associate_pane on.
list_canvas_panes reveals 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_TOKEN environment 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.

Product telemetry (PostHog)

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.

Website analytics and advertising

Use Privacy choices at the bottom of any website page to accept or reject optional measurement, or choose categories separately. Both categories stay off until you choose. The choice is saved in this browser for six months. Sign-in, downloads and essential site features work without optional measurement.

Analytics allows website visit, usage and performance measurement through PostHog, Vercel and Google Analytics when configured.
Advertising measurement allows campaign attribution and configured Google Ads, X and Reddit tags to measure sign-ups and installer download clicks. A download click does not prove that the app was installed or used. Google ad personalization remains off.

Turning a category off stops new optional measurement and reloads the page to remove tags already loaded. It also clears the associated first-party measurement storage that the site can access. This does not erase measurements previously sent to a provider or campaign attribution already attached to your account. The desktop app's telemetry choice is separate.

Google measurement excludes private account and administration pages. Its page URLs retain only supported campaign parameters and ad click identifiers; credentials, email parameters and URL fragments are excluded. No enhanced-conversion email or phone data is sent by this integration.

Consented Google signup events include a random identifier that we store against your account separately for analytics and advertising. It helps track retries and reduce duplicate conversions. The event does not send your email or internal account ID to Google.

Campaign attribution on agentgrid.sh

With advertising measurement enabled, the marketing site records where a visit came from so we can tell which campaigns produce real accounts. A visit is recorded when it carries any of the following, and nothing else is stored:

The utm_source, utm_medium, utm_campaign, utm_content, utm_term and utm_id values on the link you clicked. These can identify the campaign, ad variant and keyword supplied by the advertiser.
The ad-network click identifier and its type when one is present (twclid, gclid, gbraid, wbraid, fbclid, li_fat_id).
The site you arrived from, as origin plus path only. This is recorded for any external site, including an organic link from a forum, a search result or someone's blog, not only for tagged campaign links. Query strings are stripped before storage, and the site sends a Referrer-Policy: strict-origin header so a link you follow never carries a token in its referrer.
The page you landed on, and the time of the visit.

Whether you were already signed in at the time is not kept. It is read once, as the visit is attached to your account, to decide which of the records below that visit can become: a visit made while signed in can only ever be your most recent one, never the visit that brought you here or the one you signed up on.

Three visits are kept: the first one that brought you here, the last one before you signed up, and the most recent one. They are attached the first time you sign in after a recorded visit, which for an email signup is after you follow the verification link. For a week after the record is first created, an earlier visit found on another device can still correct the first one, and the pre-signup visit is likewise replaced if a later one is found that still predates your account. That week-long limit does not apply to the most recent visit: it is replaced every time you arrive again from a tagged campaign link, for as long as the account exists, so a later visit's ad-network click identifier is recorded against your account too. The most recent visit is stored and nothing reads it yet; it appears in no report and on no page today, and is kept so a returning visit can be credited later. Once you are signed in, arriving from an untagged external site records nothing at all.

Before you sign in this lives only in your browser's local storage. Signing in attaches it to your account and clears it from the browser once the server has accepted it; if that request fails in a way worth retrying it stays in your browser until a later attempt succeeds, and any later visit starts the cycle again. It contains no page content, no form input, and no cookies from other sites.

There is no self-serve account deletion yet. Closing an account today marks it inactive rather than erasing it, so the attribution row is retained, including the ad-network click identifier. The row is wired to be removed automatically whenever the account record itself is erased. To have your attribution record removed before then, email michael@agentgrid.sh.

Observability export (OpenTelemetry → Langfuse)

Separate from product telemetry, Settings → Observability can export harness OpenTelemetry traces to a configured Langfuse destination. That path is off by default. Prompt and tool parameter capture is on by default once export is enabled. Secrets (Langfuse secret key) are encrypted at rest; export credentials are injected only into known agent harness processes, not plain shell panes.

This does not turn on when product telemetry is on, and vice versa. Full setup and privacy notes: Observability with Langfuse.

When Observability is off, inherited telemetry configured independently by you is preserved. AgentGrid does not add its exporter credentials. Managed local Langfuse binds published ports to loopback and stores generated service secrets in owner-readable files under app user data; these files are plaintext, like the bootstrap credentials.

Observability with Langfuse — opt-in OTEL export, local Langfuse, and what gets instrumented.
Roles — the writePathPrefixes contract 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.

Master orchestrator: canvas-blind by default