Device agent

The device agent runs on developer machines and in Anthropic-hosted Claude Code on the web environments. It enforces the organization’s required AI-tool plugins and MCP configuration across every coding assistant, and reports compliance back to the platform. Open the Device Agent page from Organization settings > Secure > Device Agent in the dashboard.

Access requirements

Viewing this page requires the org:read scope, so both Admins and Members can see it. Administrative actions, including creating the API keys used for enrollment, require the org:admin scope, which only the Admin role holds by default.

What the device agent does

Instead of relying on each developer to configure every coding assistant by hand, the agent applies the organization’s required plugins and MCP configuration centrally on each machine. Plugin assignments determine what the agent delivers to a given device, so assignment changes in plugins flow through to enrolled machines. Each enrolled device reports its compliance state back to the platform.

The agent also carries signals back the other way. When a policy blocks a call against an unapproved MCP server, the agent raises a desktop notification on that machine and offers to file the access request, so the request reaches an admin without the developer leaving the machine or hunting for the link in the AI tool output. See shadow MCP for how those requests are reviewed.

Setup and enrollment

Setup lives in the Instrument agent platforms step of the setup wizard (see getting started), with walkthroughs for macOS, Windows, and Linux, plus a Remote sessions walkthrough for Claude Code on the web.

Enrollment tokens come from an API key with the Agent scope, created on the API keys page.

Claude Code on the web

Claude Code on the web runs each session in an Anthropic-hosted VM, not on the developer’s laptop. The device agent runs inside that VM, pulls org policy from the control plane, and writes Claude configuration, following the same policy-sync loop as any other machine. Do not paste observability hook JSON into Claude settings; the agent writes those hooks itself.

In the dashboard this flow is called Remote sessions: pick the Remote sessions tile, next to macOS, Windows, and Linux, on the Device Agent page or in the setup wizard. It opens a three-step walkthrough that the sections below mirror.

This walkthrough covers Anthropic-hosted environments only, not Anthropic self-hosted environments.

Configure the shared environment

Create a shared environment (Team or Enterprise) from Cloud environments in Claude admin settings. Personal environments do not reach the rest of the org.

Trusted network access does not include the Speakeasy control plane. Set Network access to Custom, check Also include default list of common package managers (keeps the agent release bucket and the usual registries reachable), and add app.getgram.ai on its own line. Without that host the agent cannot fetch policy or send hook events. The full destination list is in the device agent network allowlist.

Install and configure the agent

A headless shared VM cannot enroll through a browser sign-in, so remote sessions use managed enrollment: in the walkthrough, enter a shared session identity email and generate an org_token. Every session in the environment receives that identity’s policy and attribution, so use a dedicated org member or service account (for example claude-code-web@example.com), not a personal address. The dashboard embeds the email, the token, and a pinned, checksum-verified agent version into a single bash Setup script. Copy it from the dashboard rather than writing it by hand.

Paste the script into the environment’s Setup script field. It runs once as root before Anthropic snapshots the environment’s filesystem, and does exactly three things:

• Installs the daemon. Downloads the pinned linux_amd64 speakeasyd binary from the release bucket, verifies its SHA-256 checksum, and installs it to /usr/local/bin/speakeasyd.
• Writes managed enrollment. Creates /etc/speakeasy/managed.json with the identity email, the org_token, auto_update: "disabled", and hide_ui: true, readable by root only. Everything in the VM runs as root, so no root helper or per-user enrollment is involved.
• Registers a SessionStart hook. Writes /root/.claude/settings.json with an async SessionStart hook (matching startup|resume) that starts the daemon under flock, so a startup/resume double-fire can never start it twice.

Anthropic snapshots files, not processes, so nothing the setup script starts survives into a session. The SessionStart hook revives the daemon at every session start and resume; from there the agent’s normal policy sync installs plugins, writes tool configuration, and keeps enforcement reconciled. There is no cloud-specific sync logic.

The script pins the agent version and disables auto-update because the VM lives minutes: auto-update is wasted work, and a bad build is fixed by regenerating and re-pasting the script, which rebuilds the cached filesystem Anthropic snapshots.

Anyone who can use the environment can read the setup script and /etc/speakeasy/managed.json, including the org_token. Rotating the token in the dashboard splices a new token into the script. Save the updated script in the shared environment, or subsequent sessions stop syncing policy.

Make it the organization default

Anthropic has no switch that locks members to one environment.

• Web, Desktop, and mobile. After creating the shared environment at Cloud environments, set it as the organization default at claude.ai/admin-settings/claude-code. That preselects it when a member has not chosen another environment.
• CLI (claude --cloud). Merge the following into Managed Settings, replacing env_… with the shared environment’s ID, copied from Claude after the environment exists. The managed value overrides a user’s /remote-env default.

{
  "remote": {
    "defaultEnvironmentId": "env_…"
  }
}

The first session in a fresh VM may briefly show pending: Claude must clone the org’s observability plugin marketplace before the agent can enforce its managed hooks. Server-managed enabledPlugins triggers that clone, and the agent reconciles again once the bundle appears.

Fleet deployment through MDM

For fleets, deploy the agent through an MDM such as Kandji, Jamf, or Intune. Binaries install alongside a managed.json file, so identity and enrollment are set centrally with no per-user setup.