AgentGridAgentGrid Docs
Troubleshooting

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, phone and device connections, the team lead's blind-by-default canvas access, permission prompts, and the usage data the app sends.

Team leads: canvas-blind by default

A harness pane with AgentGrid's orchestration tools becomes a team lead (internally, 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:

  1. Materializes the harness-specific MCP configuration that points the agent at the master MCP server.
  2. Mints a fresh control token and writes it into the MCP config as the AGENT_GRID_CONTROL_TOKEN environment variable.
  3. 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 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.

Permission prompts

Settings → Agents → Default permissions applies to new panes. In Default mode, Claude asks before edits and commands. Auto uses Claude’s own checks for routine tool calls and can still ask you for approval, including in the Coordinator.

Prompts offer Deny, Allow once and, when available, Allow for session for that exact request. Session grants last until the session is replaced, the pane closes or the app restarts. Always allow appears only when Claude supplies eligible rules; it saves those rules unchanged to the project’s .claude/settings.local.json. Empty or wildcard-only Bash rules are never offered.

GUI team leads normally start with the most permissive mode their coding agent supports; choose a per-pane access level to restrict one. See Agents and workers.

Headless servers filter inherited service variables before starting children; desktop environment inheritance is unchanged. This does not sandbox shell commands or prevent credential reads from disk. See Server setup.

The iPhone app and Remote Control

The iPhone app connects only when it's signed in to the same AgentGrid account as your computer. It reaches your computer through the AgentGrid relay rather than a port on your network. Phone controls use offered projects and their subdirectories; existing local-tab agents can also be targeted. Allowed agents retain shell access, and transcript subscriptions are not fully isolated. Computer/server tokens with a device kind cannot authenticate as phones; legacy kindless tokens remain compatible. Settings → Devices → Your devices lists every computer and phone signed in to your account, with online status or when each was last seen.

Remote Control (Claude), started with /rc in a Claude team lead or the Coordinator, is Claude's own feature. That session can be driven from claude.ai/code or the Claude mobile app by whoever is signed in to that Claude account. Type /rc off to end it. See Coordinator → Remote Control.

Paired devices

Pairing links from Settings → Devices → Advanced connect another computer directly, over Tailscale. Phones don't pair with a link: they sign in with your AgentGrid account. 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 under Settings → Devices → Advanced → Devices with access here; the hashed entry is dropped, that token stops authenticating, and a device that is still connected is disconnected at once. Removing a computer you connected to, on this desktop, also asks that computer to end this one's access and closes the open connection; if it can't be reached, revoke this desktop there as well. A computer paired to this one can remove only its own access here; it can't list this computer's devices, remove other devices or create pairing codes.

Computers that connect through the AgentGrid relay show a short fingerprint of their relay key, four groups of four characters, in Settings → Devices, in agentgrid status and in any key-change message, so you can compare the same key across them.

External MCP clients

Settings → MCP Server on a Mac connects other apps to AgentGrid through one URL, https://mcp.agentgrid.sh/mcp. See Remote MCP access.

On Windows and Linux, Settings → MCP Server keeps the local cards: only clients on this computer can connect, and Remote access (beta) tokens are the exception. Each local MCP client keeps one token. Copy config and Add to… / Re-add reuse it. Use Regenerate token to replace it, or Revoke token or Remove to cut access. Connected clients lists each connected agent; Revoke there cuts that one off. Replacing or revoking a token closes its existing sessions. If a client reports that its token was rejected, copy its current configuration again.

  • What a signed-in app can do. Any app you sign in can list, read and message your panes, and direct a Coordinator. The Coordinator acts with its full authority in AgentGrid, so it can do anything on that Mac that AgentGrid can. Sign in only apps you'd trust with that.
  • How long a sign-in lasts. The app gets an access token that lasts 10 minutes and a refresh token that lasts 14 days. No token is written into the app's config.
  • How to cut an app off. Select Revoke on Connected apps (in the account menu). The website cuts it off at once; the relay and your Macs refuse it within 10 minutes, once its last access token expires. Removing the entry from the app's config doesn't revoke its sign-in.
  • The relay can read requests. They travel over TLS through the AgentGrid relay to your Mac, and are not end-to-end encrypted, unlike the phone app.
  • When your Mac connects to the relay. An approved app or a reachable phone keeps the relay connection open while the background service runs; an old agr_ token also holds it open on the Mac that stores it. Other remote features can request a temporary connection. While it's connected, the relay sees your Mac's IP address and when it's online.
  • Which Macs an app reaches. On the free plan, an app connects only your oldest registered Mac to the relay. AgentGrid Pro reaches all of them.
  • Device codes. On a machine with no browser, an app signs in with a code you approve at agentgrid.sh/device. Check the code there matches the one on your device before you select Allow. The code expires in 10 minutes. Approve only a code you started yourself: approving someone else's code signs their app in to your account.

Apps still set up with the old local server appear under Local server (deprecated). Remove takes the entry out of the app's config and revokes its local token, closing its sessions. Old remote tokens (agr_) appear under Old tokens, where Revoke cuts one off.

GitHub comments

With Settings → GitHub → Post to GitHub as the AgentGrid bot, reviews and comments your agents post appear as the AgentGrid bot instead of your own GitHub account. In an agent shell that has no bot token and can't get one, AgentGrid's gh stops with a one-line error saying what failed instead of running as your own login; a shell that still has its launch token keeps using it if a renewal fails. The cost comment AgentGrid keeps on pull requests shows tokens and API-priced estimates. It names accounts only by harness and plan, never by your account name or email.

GitHub tokens AgentGrid supplies to agents are redacted from its logs, including when a command echoes one back. Secrets for MCP servers are never put on a harness's command line, where other programs could read them, or left in readable files. Claude agents are refused git commands that would throw away uncommitted work, such as git reset --hard or git clean -f, in a worktree with changes. Avoid sharing secrets in prompts or files.

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.

Desktop app usage data (PostHog and Sentry)

The desktop app sends usage data to PostHog (United States) from three places: the renderer (posthog-js), the main process (posthog-node), and the background daemon that keeps agents running (posthog-node, with $process set to daemon). Before you sign in, it is tied to a random installation identifier. After you sign in, it is linked to your account, including your email and account ID. Signing out switches to a new random installation identifier.

What is collected:

  • Device and app info (OS, architecture, app and runtime versions, language, screen size, time zone, browser properties) and approximate location derived from your IP address (for both the main process and the interface).
  • Session activity and active time.
  • Project names and each project's repository name (owner/repo from the git remote), plus repositories enabled for GitHub mentions.
  • Which subscription plan your Claude and Codex accounts are on (for example Pro, Max or Team), the highest one per computer, and Claude's rate-limit tier. For API-key logins, only that a key is in use.
  • Counts of panes, agents and harnesses, which harnesses, providers and models they use, enabled providers and model fallback order, and counts of extra harness accounts and custom roles.
  • Which features and settings you use or change, including theme and color settings. For API keys and other secrets, only whether one is set.
  • Agent task outcomes (success, whether it edited, ran or committed, duration) and cost when the harness reports it.
  • Counts of how often each AgentGrid tool was called by agents.
  • Voice call and dictation usage (including duration), and app update and crash events such as process type and exit reason (no crash dump).

Error reports go to PostHog, and packaged builds also send them to Sentry from the main process and the background daemon. PostHog error reports keep the error message and stack trace, with only your home-folder name removed, so they can occasionally include fragments of whatever the failing code was handling, such as a file path or command output. Sentry reports are heavily sanitized: error type, stack frames with file names kept only for AgentGrid's own code, technical event names and versions, with error message text withheld and the IP address redacted. Crash minidumps stay on your device.

Usage events never include: your code, prompts, file contents, agent transcripts, notes, terminal or browser-pane contents, or API keys and other secrets.

Turn Share usage data off under Settings -> Advanced -> Privacy to opt out at any time. Opting out stops both PostHog and Sentry reporting, including from the background daemon. While it's on, bug reports and other feedback that agents send to AgentGrid go without asking; with it off, AgentGrid asks you before each one. The setting is saved automatically.

If you set telemetryEnabled to false in settings.json by hand while AgentGrid is running, the background daemon stops right away and the app itself stops the next time you start it. If settings.json can't be read, AgentGrid treats it as opted out and leaves the file as it is. If AgentGrid can't save your choice, it keeps it for the rest of the session, stops sending from the app and the background daemon, and shows an error with Try again. The choice resets when you quit unless a later save succeeds.

Signing in lets AgentGrid measure active use per account and enforce account entitlements; it does not make pane contents part of telemetry.

Website analytics and advertising

The website measures every visit; there is no banner to opt in or out. Sign-in, downloads and every site feature work the same whether or not a measurement tag loads, so a content blocker does not break the site. The desktop app's telemetry choice is separate.

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

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.

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

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 (shown by Show Observability in Settings → Advanced) 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.

On this page

Ask AI

Ask a question about AgentGrid. Answers come from these docs, with links to the pages they use.

AI answers can be wrong. Check the linked pages.