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/Reference
Reference

Local collector API

Integrate with the authenticated loopback HTTP API for ingest, scans, review state, and redacted export.

On this page

The collector listens on HTTP loopback, normally http://127.0.0.1:4319. API routes require Authorization: Bearer TOKEN. Studio's HTML shell is public on that origin, but its data requests are authenticated. This API is different from the remote workspace API.

Pair an API client

Start the collector and obtain its pairing token using beam token in a private terminal. Supply it through your client's secret handling. A token is generated for the data directory and reused across collector restarts.

Code
curl --fail --silent --show-error \
  -H "Authorization: Bearer $BEAM_TOKEN" \
  http://127.0.0.1:4319/health

Do not expose the listener publicly or point BEAM_COLLECTOR_URL at a remote dashboard. Browser callers must also satisfy the configured origin policy.

Endpoint reference

Method and pathRequest or response
GET /healthCollector version and retention information
GET /stateRetained events, scans, reviews, and rule catalog
GET /agentsAgent config/artifact existence and hook status; no file contents
POST /ingestA normalized JSON object, array, or NDJSON stream
POST /v1/logsOTLP/HTTP JSON; protobuf is not supported
POST /scan{ "name", "kind", "content" }, with kind skill or mcp
POST /review{ "id": "EVENT_ID", "reviewed": true }
POST /rules/reloadReload local custom rules; returns path, loaded count, and errors
GET /exportRedacted event NDJSON

Submit a scan

Code
curl --fail --silent --show-error \
  -H "Authorization: Bearer $BEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"example.md","kind":"skill","content":"Read the project README before editing."}' \
  http://127.0.0.1:4319/scan

This persists through the collector and may forward to an enrolled workspace. Use beam scan without --save for an offline, non-persisted file review.

Respect request bounds

Ingestion is limited to 2 MB and 2,000 records per request, with a 100 KB per-record limit. The scan route has a 500 KB body/content boundary. Split large imports into meaningful batches and inspect accepted, duplicate, and skipped counts instead of assuming every source line was retained.

Retention keeps the latest 10,000 events and 500 scan reports. /state and /export represent bounded history. A review toggle records an assessment marker rather than approval or enforcement.

Diagnose authentication and delivery

For rejected tokens, check the data directory and any BEAM_TOKEN override. For refused connections, confirm port and service status. For browser-origin errors, explicitly configure only the required local origins. A successfully stored record may still fail remote forwarding; local ingestion and workspace delivery are separate outcomes.

Keep exploring

Explore the docs