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

Run in the background

Keep the local collector running at login using macOS launchd or a Linux user service.

On this page

beam start runs in your terminal and stops when that process exits. A background service runs the same userspace collector under your account and can restart after a crash. It does not add kernel capture or change which agent hooks are supported.

Install the service

Code
beam service install
beam service status
beam studio

The install command registers and starts the collector. Avoid leaving a separate beam start process on the same port. Use --port at installation when you need a different listener:

Code
beam service install --port 4400

Configure BEAM_COLLECTOR_URL=http://127.0.0.1:4400 for CLI commands that talk to that listener. A port change also changes Studio's browser origin and pairing state.

Platform behavior

PlatformService definitionLifecycle
macOS~/Library/LaunchAgents/ai.beam.collector.plistUser launch agent with RunAtLoad and KeepAlive
Linux~/.config/systemd/user/beam.serviceUser unit enabled and started with restart behavior
WindowsNot supported by beam serviceRun beam start directly

These are user services, not system-wide endpoint enforcement. Login/session behavior depends on the service manager configuration.

Set the data directory

Code
BEAM_DATA_DIR=/absolute/private/beam-data beam service install

The installer embeds the resolved data directory into the service definition because service managers do not inherit your interactive shell environment. Ensure the location is private and writable by the intended user. Inspect the generated definition when using additional custom settings; do not assume every shell variable persists after reboot.

Operate and inspect

Code
beam service stop
beam service start
beam service status
beam service logs

logs prints the log file paths or the command used to follow the service logs. Inspect stderr for hook wiring, configuration, and binding errors. If Studio cannot connect, verify the service status, collector URL, port, and data directory used to read the token.

Remove the service

beam service uninstall stops and removes the background service. It is not the same as removing agent hooks, deleting local history, or revoking workspace registration. Use Uninstall & offboarding for a complete device retirement workflow.

Keep exploring

Explore the docs