Device Agent

The device agent is a lightweight endpoint agent for developer machines and Anthropic-hosted Claude Code on the web VMs. It installs, maintains, and reports on the organization’s mandated AI agent configuration: which plugins and MCP servers Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and OpenClaw should have, kept in place even as tools update or users switch accounts. On laptops it runs as a small background daemon with a menu bar app on macOS, Windows, and Linux, and deploys through MDM or a self-serve installer. In Claude Code on the web it runs inside the session VM; see Claude Code on the web.

What it aims to achieve

The platform enforces policy at MCP tool-call time, but that enforcement only applies if the AI agent on the laptop, or in an Anthropic-hosted Claude Code on the web VM, actually routes through a sanctioned MCP server. The device agent is the device-side guarantee that it does. It closes the most common bypass path: configuration drift on developer laptops, including the case where a user switches their AI agent to a personal account and silently loses the org’s plugins, telemetry, and guardrails. Claude Code on the web sessions have the same gap until the agent is installed in a shared Anthropic-hosted environment.

The intended outcome reads like a policy statement: install these MCP servers and plugins into every engineer’s AI agents, keep them installed even when an engineer switches accounts, and show which devices are covered. Admins configure policy in the dashboard and watch per-device coverage; developers see a menu bar icon reflecting status and otherwise keep working.

Capabilities

• Plugin and MCP configuration sync - An org-wide policy of marketplaces and plugins is rendered into each agent’s native configuration across Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and OpenClaw. The agent tracks what it installed and never touches entries the user added themselves.
• Continuous reconciliation - The daemon re-fetches policy and re-applies it every 60 seconds, so mandated configuration survives tool updates, settings resets, and account switches instead of drifting until the next manual audit.
• Telemetry wiring - The agent configures Claude Code’s OpenTelemetry export to point at the platform’s telemetry ingest, seeding the session logs and token metrics behind Observe. Neither OpenCode nor OpenClaw has an OpenTelemetry exporter, so there is nothing to wire up there: their observability plugins report sessions, tool calls, tokens, and cost on their own. See distributing plugins to OpenCode and distributing plugins to OpenClaw.
• Managed identity for hooks - Hook plugins resolve the developer’s email and organization from the agent locally, with no network call and no access to the org credential, so telemetry is attributed to the right person.
• Offline resilience - The agent detects control-plane downtime, backs off, and drains the hooks’ buffered telemetry once connectivity recovers, so short outages don’t lose events.
• Managed auto-update - Updates ship through release channels with checksum verification and a per-version kill switch; macOS binaries are Developer ID-signed and notarized.

How it connects

The agent has a small, well-defined network surface. Policy polling doubles as the device heartbeat, and everything else flows through existing platform channels:

• Policy fetch and heartbeat. Every minute the daemon fetches the org’s plugin policy over HTTPS, authenticated with its enrollment key. Each poll also records the device check-in that powers coverage reporting.
• Session telemetry. The AI agents themselves emit telemetry to the platform’s OTEL ingest; the agent’s job is wiring that configuration up and keeping it in place.
• MDM. The MDM deploys the agent and its managed configuration to devices, and separately syncs device inventory into the platform so coverage can be measured fleet-wide. See MDM installations.
• Claude Code on the web. Same policy fetch over app.getgram.ai. The Anthropic-hosted VM has no MDM; identity is the org_token in /etc/speakeasy/managed.json. See Claude Code on the web.

Network allowlist

Every connection the agent makes is outbound HTTPS on port 443. It opens no inbound ports; the enrollment sign-in callback binds to loopback (127.0.0.1) only. On a locked-down network, allow these destinations:

Destination	Purpose
app.getgram.ai, the Speakeasy control plane	Plugin-policy fetch, device check-in and heartbeat, enrollment, and the OpenTelemetry ingest that Claude Code’s telemetry is pointed at.
storage.googleapis.com	Signed release manifests and agent update binaries (see Automatic updates).
The plugin marketplace hosts, which are the control-plane host by default plus any external Git host the policy references (for example, github.com)	Cloning and updating the plugin and marketplace repositories the policy assigns.

The marketplace hosts depend on the plugins the policy assigns, so review the assigned policy to enumerate them for a given environment. The agent refuses plaintext HTTP and non-public marketplace URLs.

Claude Code on the web Trusted network access does not include app.getgram.ai. Set the shared environment to Custom, check Also include default list of common package managers (keeps storage.googleapis.com and the usual registries reachable), and add app.getgram.ai on its own line. Setup is on Claude Code on the web.

Automatic updates

The agent keeps itself current so a fleet doesn’t quietly drift onto old builds, while leaving teams that prefer to drive versions through MDM in full control. Behavior is set by the auto_update field in the agent’s managed configuration, either managed.json or a macOS configuration profile (see MDM installations).

Update modes

Mode	Behavior
disabled	Default. The agent never checks for updates; IT ships new versions on its own cadence via MDM. Required in Anthropic-hosted cloud environments, where the VM lives minutes and the setup script pins a version.
notify	The agent checks and reports that an update is available but does not install it.
automatic	The agent checks, downloads, verifies, and installs without user interaction. Recommended.

How updates are delivered

• The agent checks at startup and every 24 hours, and on demand via speakeasy update --check.
• Each binary is verified by SHA-256 against a signed release manifest before it is installed. macOS binaries are Developer ID-signed and notarized.
• The new binary is swapped into place atomically. If an updated daemon fails to start, the agent automatically reverts to the previous version, so a failed update never leaves a device worse off than before.
• Self-update applies on macOS and Linux. Windows updates are delivered through MDM for now.
• speakeasy update --apply runs the same download-verify-swap on demand, for scripted or headless use.

Enrollment

Three enrollment paths cover evaluation, fleet rollout, and Claude Code on the web:

• Self-service - The developer opens the menu bar app and clicks “Enroll”, which opens the dashboard in a browser. After sign-in, the agent redeems a short-lived, single-use code (PKCE-bound, so the code is useless without the device that requested it) for a long-lived per-user key scoped to agent use only. Any org member can enroll their own device.
• MDM zero-touch - IT deploys a managed configuration file or macOS configuration profile carrying the org’s agent key and settings alongside the installer package. Devices come up enrolled with no user interaction.
• Claude Code on the web - The environment’s setup script, generated in the dashboard’s Remote sessions walkthrough, writes /etc/speakeasy/managed.json with a shared identity and an org token. There is no interactive enroll step in the VM. See Claude Code on the web.

Device status in the dashboard

Each policy poll updates the device’s standing, surfaced in two places:

• Employee Enrollment shows a per-member Device Agent column: Active when the agent synced in the last few minutes, Stale when it is enrolled but hasn’t been seen recently, and Not Enrolled when there is no agent activity.
• With an MDM inventory source connected, the dashboard joins the MDM’s device list against agent heartbeats to show fleet-wide coverage: which managed devices have an active agent, which are stale, and which have none. Setup lives on the Device Agent page under organization settings.