# Agent monitoring, end to end

> Roll AgentBeam out to every developer machine: coding agents hooked and captured, MCP servers inventoried, a workspace policy moved from observe to enforce, alerts routed, and a weekly review routine.

Source: https://docs.agentbeam.com/cookbooks/agent-monitoring

This recipe takes a workspace from one person trying Beam to every coding agent in the team watched and governed: Claude Code, Codex, Cursor, Gemini CLI, Copilot CLI and others. Work through it in order; each step ends with a check.

## What you'll have

- Every supported coding agent on every developer machine hooked, with its actions captured locally and sent to the workspace.
- MCP servers inventoried, with risky responses filtered before they reach an agent.
- A workspace policy that started in observe mode and now asks or blocks where it should.
- Risky skills held for approval before an agent loads them.
- Alerts for findings that matter, and a weekly review of what agents did.
- Past agent sessions imported, so the history starts before the rollout.

## Before you start

| You need | Who | Why |
| --- | --- | --- |
| An AgentBeam workspace | Anyone | Sign up at [app.agentbeam.com](https://app.agentbeam.com) |
| Owner or admin role | Steps 3, 5, 6 and 7 | Inviting members, policies and integrations |
| A terminal on each machine | Each developer, or IT through MDM | Installing the CLI and its hooks |

## Step 1: Set up your own machine first

```sh
npm i -g @agent-beam/beam
beam setup
```

`beam setup` finds the agents installed on the machine, adds Beam's hook to each one without replacing existing hooks, inventories MCP servers, connects the device to your workspace through a browser sign-in, downloads the policy and starts the background service. No Node.js? Use `curl -fsSL https://agentbeam.com/install.sh | bash` first.

**Check:**

```sh
beam whoami            # this device and workspace
beam agent list        # each agent and whether its hook is installed
beam service status    # the collector is running
```

Then run any harmless command in Claude Code or Codex (for example "list the files here"), and open `beam studio`: the action is there with its agent, tool and command.

## Step 2: Watch what agents do, locally and in the dashboard

- **Local Studio** (`beam studio`) shows this machine's activity, live, without leaving it.
- **Observability** and **Sessions** in the dashboard show every connected device's agents, sessions, tools, token use and findings.
- **Agents** lists each device's agents and versions; **MCP Scan** lists their MCP servers.

To bring in history from before Beam was installed:

```sh
beam agent extract claude-code          # preview what's in local transcripts
beam agent extract claude-code --save   # import it into the collector
beam agent extract codex --save
```

**Check:** your machine appears under **Agents**, and its session from step 1 is under **Sessions**.

## Step 3: Bring the team

Invite people from **Members** and give each the least role they need: members for developers, security manager or auditor for reviewers. Each person runs the two commands from step 1. To let their coding agent do it, have them run:

```sh
npx -y @agent-beam/beam add skill agentbeam-setup -g --all-agents
```

and ask their agent to "set up AgentBeam". For a managed fleet, push the CLI with your device management tool and have each person run `beam setup` once to sign in.

**Check:** **Agents** lists every developer machine, with a recent last-seen time.

## Step 4: Protect MCP servers and skills

- **MCP responses.** Run an MCP server through Beam's filter so secrets in its responses are redacted before the agent sees them: `beam mcp proxy <command> [args...]` in place of the server's command in your MCP configuration.
- **Risky skills are held automatically.** When an agent loads a skill (the Skill tool, or reading a `SKILL.md`), the hook scans it first. Prompt injection or a critical finding makes the agent ask you before loading it, or blocks it under an enforce policy. Review it with `beam skills scan <path>`; if you trust it, `beam skills trust <path>` pins that exact content.
- **Inventory.** `beam skills index` finds every skill on the machine and `beam skills sync` sends names and risk scores (never contents) to **Skills Scan**.

See the [skill testing cookbook](https://docs.agentbeam.com/cookbooks/skill-testing) for the full skill workflow.

## Step 5: Move the policy from observe to enforce

Policies live under **Policies** in the dashboard. Do this in three passes:

1. **Observe (week 1).** Add the [policy presets](https://docs.agentbeam.com/agent-cli/policy-presets) you want (recursive delete, destructive Git commands, credential file references, package publishing, cloud CLIs and so on) with the mode on **Observe**. Nothing is blocked; findings show what *would* have been.
2. **Advisory (week 2).** Switch to **Advisory**: matching actions ask the developer for approval in Claude Code and Codex. Watch **Risks** for actions people approve all the time and tune the rules.
3. **Enforce.** Switch to **Enforce** for the rules you're sure of. Use member overrides to make the policy stricter for specific people (contractors, production access); overrides can only tighten.

```sh
beam sync   # on a test machine: pull the new policy now instead of within 60 seconds
```

**Check:** in a test session, ask an agent to run a command your policy blocks (for example `rm -rf ./build` with the **Recursive delete** preset). Claude Code or Codex shows Beam's denial; the action is under **Risks**.

## Step 6: Route alerts

On [Integrations](https://docs.agentbeam.com/agent-cli/integrations), connect Slack, Microsoft Teams, PagerDuty, email or a signed webhook to your SIEM, then add alert workflows for agent findings at the severities you care about. **Device alerts** shows tamper alerts (an agent or process trying to change, stop or remove Beam) and deliberate uninstalls and logouts.

## Step 7: A weekly review

- **Risks:** work through new high and critical findings; mark each reviewed, or turn a recurring one into a policy rule.
- **Device alerts:** open tamper alerts, and any machine where Beam was uninstalled or logged out.
- **Agents and MCP Scan:** new agents or MCP servers nobody approved.
- **Audit log:** policy, member and integration changes, exportable as CSV.

## Coverage checklist

| Feature | Done when |
| --- | --- |
| CLI and hooks | `beam agent list` shows hooks on every agent each person uses |
| Background service | `beam service status` is running on every machine |
| Workspace connection | Every machine is under **Agents** |
| History | `beam agent extract ... --save` run once per machine |
| MCP filtering | Servers with access to secrets run through `beam mcp proxy` |
| Skill gate | Risky skills prompt before loading; trusted ones are pinned |
| Skill inventory | `beam skills sync` populates **Skills Scan** |
| Policy | Enforce for the rules you're sure of, advisory for the rest |
| Alerts | High and critical agent findings reach a channel |
| Review | Someone owns the weekly review |