# Run in the background

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

Source: https://docs.agentbeam.com/agent-cli/service

`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

```sh
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:

```sh
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

| Platform | Service definition                               | Lifecycle                                           |
| -------- | ------------------------------------------------ | --------------------------------------------------- |
| macOS    | `~/Library/LaunchAgents/ai.beam.collector.plist` | User launch agent with RunAtLoad and KeepAlive      |
| Linux    | `~/.config/systemd/user/beam.service`            | User unit enabled and started with restart behavior |
| Windows  | Not supported by `beam service`                  | Run `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

```sh
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

```sh
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](https://docs.agentbeam.com/agent-cli/uninstall) for a complete device retirement workflow.