Agentbeamdocs

Start here

MDM / Getting startedDevice managementOne place to understand your Apple and Windows fleet, deliver configuration, and request device actions.MDM / Getting startedSet up your workspaceRequest MDM access, check platform readiness, and get your first managed device into inventory.Agent CLI / Getting startedAgent CLI overviewUnderstand agent activity locally, scan the files your assistants use, and connect shared workspace controls when needed.Agent CLI / Getting startedCLI quickstartInstall Beam, capture a first event, and open your local activity dashboard.Agent CLI / Getting startedConnect a workspacePair your machine through the browser or an enrollment code, then verify identity and policy synchronization.
↑ ↓ to navigate · Enter to openEsc to close
Website Open dashboard
Agent CLI/Operate & troubleshoot
Operate & troubleshoot

CLI troubleshooting

Diagnose installation, local capture, pairing, forwarding, and policy behavior one stage at a time.

On this page

Start by separating the local CLI, collector, assistant hook, and remote workspace. Each can be healthy while another is disconnected. Avoid deleting the Beam data directory to solve a pairing or service problem; it contains retained events, credentials, and policy state.

beam is not found

Verify Node meets the package requirement and @agent-beam/beam is installed. Confirm the npm global binary directory is on PATH. A desktop assistant or MCP host may use a different environment from the terminal; configure a reviewed absolute executable path where necessary.

Collector is unreachable or the port is busy

Check beam service status if using a background service. Do not run a second foreground collector on the same port. Confirm BEAM_PORT and BEAM_COLLECTOR_URL refer to the same local listener and that the URL uses HTTP at 127.0.0.1 or localhost.

Use beam service logs to locate diagnostics. With a custom data directory, make sure client commands read the token belonging to that collector.

Studio loads but shows no data

The HTML shell does not require authentication, but the data API does. Reopen with beam studio to pair against the intended collector. Use Disconnect to clear stale browser pairing. Different ports have separate local storage.

Then verify a real harmless tool action from a supported assistant. beam agent list reports adapter support, not proof that the assistant actually invoked its hook. Check the native config and process PATH.

Local activity is missing from the dashboard

Run beam whoami and beam account to confirm the workspace and device status. An unconnected collector stays local. An enrolled collector batches forwarding and flushes partial batches after inactivity, so quiet activity can appear later.

Forwarding is best-effort, without a durable retry queue. Network or server failures can leave history only on the machine. Preserve a local redacted export rather than assuming reconnect automatically replays every missed record.

A policy did not block

Run beam sync and confirm the expected workspace policy version. Check mode, matching baseline fields, cached expiry, and whether the assistant uses the supported PreToolUse deny contract. Only Claude Code and Codex denial output is wired in the public CLI.

Structured dashboard rules are not consumed by the current public evaluator. Other agents receive diagnostic notes for deny decisions. Missing, unreadable, or expired policy allows the action. Agent policy is not a substitute for an OS sandbox or complete endpoint enforcement.

Scan or MCP tool fails

Use valid JSON with --mcp; respect the 2 MB file and 500,000-character text bounds. Saved scans also face the collector request-size limit. For MCP, verify BEAM_BIN, absolute file paths, and the subprocess's 15-second/5 MiB limits.

When contacting support, include versions, platform, command name, redacted error, collector port, and whether local or remote behavior failed. Keep tokens, enrollment codes, raw prompts, and private files out of diagnostics.

Keep exploring

Explore the docs