speakeasy-api · subomi · Aug 20, 2026
@@ -45,12 +45,18 @@ In the dashboard, open **Organization settings > API Keys** (see [API keys](/doc
   The [device agent](/docs/ai-control-plane/org-admin/device-agent) applies the
   same marketplace, plugin, and OTEL settings to Claude Code on its own and
   reapplies them every minute, so organizations running it can skip this
-  section. It writes the user-level settings file rather than the admin-owned
-  managed settings, and the telemetry block only lands once Claude Code has
-  cloned the marketplace on its next launch. These settings can also be
-  distributed via MDM, which gives more control over the rollout at the cost of
-  a more involved setup. Claude Cowork is not covered by either alternative, so
-  the [Claude Cowork](#claude-cowork) steps below always apply.
+  section for Claude Code on developer machines. It writes the user-level
+  settings file rather than the admin-owned managed settings, and the telemetry
+  block only lands once Claude Code has cloned the marketplace on its next
+  launch. These settings can also be distributed via MDM, which gives more
+  control over the rollout at the cost of a more involved setup.
+
+  Claude Code on the web does not use this laptop path. Instrument those
+  sessions with the device agent in a shared Anthropic-hosted environment; see
+  [Claude Code on the web](/docs/ai-control-plane/org-admin/device-agent#claude-code-on-the-web).
+
+  Claude Cowork is not covered by either alternative, so the
+  [Claude Cowork](#claude-cowork) steps below always apply.
 </Callout>
 
 In the Claude org settings, open the **Claude Code** tab (claude.ai/admin-settings/claude-code), scroll to **Managed settings**, and click **Manage**. Merge the following JSON into the dialog, replacing the marketplace values with the ones shown on the dashboard's **Distribute > Plugins** page and the API key placeholder with the key created above.

@@ -49,7 +49,9 @@ Choose how the team's AI coding assistants get instrumented. **Manual Setup** wa
 
 ![The Instrument agent platforms step with per-platform manual setup entries](/assets/docs/ai-control-plane/getting-started/setup-instrument-agents-manual.webp)
 
-The **Device Agent** (beta) is the centralized alternative. One on-device agent enforces the organization's required plugins and MCP configuration across every assistant and reports compliance back. For fleets, deploy it through MDM (Kandji, Jamf, Intune, or similar): identity and enrollment are set centrally with no per-user setup, and walkthroughs cover macOS, Windows, and Linux.
+The **Device Agent** (beta) is the centralized alternative. One agent enforces the organization's required plugins and MCP configuration across every assistant and reports compliance back. For fleets, deploy it through MDM (Kandji, Jamf, Intune, or similar): identity and enrollment are set centrally with no per-user setup, and walkthroughs cover macOS, Windows, and Linux.
+
+Claude Code on the web is not a laptop install. The same **Device Agent** option includes a **Remote sessions** walkthrough for Anthropic-hosted VMs: a shared environment with Custom network access, a generated setup script, and a SessionStart hook that starts the agent in each session. See [Claude Code on the web](/docs/ai-control-plane/org-admin/device-agent#claude-code-on-the-web).
 
 ![The Device Agent option with platform walkthroughs for macOS, Windows, and Linux](/assets/docs/ai-control-plane/getting-started/setup-instrument-agents-device-agent.webp)
 
@@ -61,7 +63,7 @@ Optionally connect admin and compliance APIs so the platform can import usage, s
 
 ### Confirm traffic
 
-The wizard listens for events from the instrumented agent platforms. Trigger any action in Claude Code, Cursor, Codex, or OpenCode on a managed machine, and the live activity feed shows tool-call events arriving, followed by confirmation that the organization is receiving hook events.
+The wizard listens for events from the instrumented agent platforms. Trigger any action in Claude Code, Cursor, Codex, or OpenCode on a managed machine, or in an instrumented Claude Code on the web session, and the live activity feed shows tool-call events arriving, followed by confirmation that the organization is receiving hook events.
 
 ![The Confirm traffic step with a live feed of arriving tool-call events](/assets/docs/ai-control-plane/getting-started/setup-confirm-traffic.webp)
 

@@ -7,6 +7,10 @@ import { Callout } from "@/mdx/components";
 
 The Anthropic Compliance integration connects Anthropic's Compliance API to import Claude chats from claude.ai web and desktop, alongside Claude usage and cost metrics. Chat activity feeds security review; usage and cost feed the platform's [Observe](/docs/ai-control-plane/observe) and [Costs](/docs/ai-control-plane/observe/costs) views.
 
+<Callout type="info">
+  This integration imports **claude.ai chat** activity, not Claude Code on the web. To track and policy-block Claude Code on the web sessions, use the device agent in an Anthropic-hosted environment; see [Claude Code on the web](/docs/ai-control-plane/org-admin/device-agent#claude-code-on-the-web).
+</Callout>
+
 ## Access requirements
 
 <Callout type="info">

@@ -1,12 +1,12 @@
 ---
 title: "Device agent"
-description: "Enforce required AI-tool plugins and MCP configuration on developer machines and report compliance back to the platform."
+description: "Enforce required AI-tool plugins and MCP configuration on developer machines and Anthropic-hosted Claude Code on the web environments, and report compliance back to the platform."
 ---
 
 import { Callout } from "@/mdx/components";
 import { BADGE_DEFINITIONS } from "@/lib/data/docs/badges";
 
-The device agent runs on-device, 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.
+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.
 
 <Callout type="info">{BADGE_DEFINITIONS.Beta}</Callout>
 
@@ -24,10 +24,59 @@ The agent also carries signals back the other way. When a policy blocks a call a
 
 ## Setup and enrollment
 
-Setup lives in the **Instrument agent platforms** step of the setup wizard (see [getting started](/docs/ai-control-plane/getting-started)), with walkthroughs for macOS, Windows, and Linux.
+Setup lives in the **Instrument agent platforms** step of the setup wizard (see [getting started](/docs/ai-control-plane/getting-started)), with walkthroughs for macOS, Windows, and Linux, plus a **Remote sessions** walkthrough for [Claude Code on the web](#claude-code-on-the-web).
 
 Enrollment tokens come from an API key with the **Agent** scope, created on the [API keys](/docs/ai-control-plane/org-admin/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's config — 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](https://code.claude.com/docs/en/self-hosted-environments).
+
+### Configure the shared environment
+
+Create a **shared** environment (Team or Enterprise) from [Cloud environments](https://claude.ai/admin-settings/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](/docs/ai-control-plane/reference/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:
+
+1. **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`.
+2. **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.
+3. **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 Anthropic's cached filesystem.
+
+<Callout type="warning">
+  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.
+</Callout>
+
+### 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](https://claude.ai/admin-settings/cloud-environments), set it as the organization default at [claude.ai/admin-settings/claude-code](https://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.
+
+```json
+{
+  "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.
@@ -1,20 +1,20 @@
 ---
 title: Device Agent
-description: "A lightweight endpoint agent that keeps org-mandated AI agent configuration in place on developer machines and reports device coverage back to the platform."
+description: "A lightweight endpoint agent that keeps org-mandated AI agent configuration in place on developer machines and Anthropic-hosted Claude Code on the web VMs, and reports coverage back to the platform."
 ---
 
 import { Callout } from "@/mdx/components";
 import DeviceAgentDiagram from "@/components/astro/docs/DeviceAgentDiagram";
 
-The device agent is a lightweight endpoint agent for developer machines. It installs, maintains, and reports on the organization's mandated AI agent configuration: which plugins and MCP servers Claude Code, Codex, Cursor, and OpenCode should have, kept in place even as tools update or users switch accounts. 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.
+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, and OpenCode 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](/docs/ai-control-plane/org-admin/device-agent#claude-code-on-the-web).
 
 <Callout type="info">
   The device agent is in beta. Capabilities described here reflect the current release; contact the team for rollout support.
 </Callout>
 
 ## 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 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.
+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.
 
@@ -36,6 +36,7 @@ The agent has a small, well-defined network surface. Policy polling doubles as t
 - **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](/docs/ai-control-plane/reference/device-agent/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](/docs/ai-control-plane/org-admin/device-agent#claude-code-on-the-web).
 
 ### Network allowlist
 
@@ -51,6 +52,10 @@ Every connection the agent makes is **outbound HTTPS on port 443**. It opens no
   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.
 </Callout>
 
+<Callout type="warning">
+  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](/docs/ai-control-plane/org-admin/device-agent#claude-code-on-the-web).
+</Callout>
+
 ## 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](/docs/ai-control-plane/reference/device-agent/mdm-installations)).
@@ -59,7 +64,7 @@ The agent keeps itself current so a fleet doesn't quietly drift onto old builds,
 
 | Mode | Behavior |
 | --- | --- |
-| `disabled` | **Default.** The agent never checks for updates; IT ships new versions on its own cadence via MDM. |
+| `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. |
 
@@ -73,10 +78,11 @@ The agent keeps itself current so a fleet doesn't quietly drift onto old builds,
 
 ## Enrollment
 
-Two enrollment paths cover evaluation and fleet rollout:
+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](/docs/ai-control-plane/org-admin/device-agent#claude-code-on-the-web).
 
 ## Device status in the dashboard