# Connect a workspace

> Pair your machine through the browser or an enrollment code, then verify identity and policy synchronization.

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

Workspace connection gives the device an identity for sharing activity and receiving policy. It is separate from local Studio pairing and from operating-system MDM enrollment. Choose the intended workspace in the browser before authorizing the device.

## Connect through your browser

```sh
beam connect
```

Beam opens a dashboard sign-in flow and waits for authorization. Sign in, select or create the appropriate workspace, and complete the device connection. The CLI prints the connected device ID, organization ID, and API origin. If the device was already enrolled, the new connection replaces its local enrollment.

If the workspace's [plan](https://docs.agentbeam.com/agent-cli/subscription#plans) has no room for another device or person, the dashboard shows which limit was reached as you approve, and `beam connect` prints the same reason with a link to **Plans**. Nothing is connected and an existing enrollment is kept. `beam setup` says so and carries on with local protection. Reconnecting a machine that's already connected never counts against a limit.

The connection flow may install an entitled enterprise package. The public CLI's hook capture and the enterprise package's OS-level monitoring have different coverage; inspect the installation output rather than assuming every platform capability is active.

## Use an enrollment code

If your administrator provided a code, use:

```sh
beam enroll --code YOUR_ENROLLMENT_CODE
beam agent install-all
beam start
```

Treat enrollment codes as credentials. Do not commit them to scripts or share shell history containing them. The enrollment command also supports `--url` for an explicitly chosen API base.

## Verify your device

```sh
beam whoami
beam account
beam sync
```

`whoami` displays the local enrollment identity. `account` asks the workspace API for the signed-in user, workspace, and device status. `sync` fetches the latest policy into the data directory. Verify that these agree with the dashboard's **Agents** page.

The running collector synchronizes policy every 60 seconds for an enrolled device. Event forwarding batches up to 15 records, with a partial batch flushed after ten seconds of inactivity. Network failures can leave records only in local storage; forwarding does not guarantee eventual delivery.

## Connect a self-hosted dashboard

Set both remote destinations before pairing:

```sh
export BEAM_API_URL=https://beam.example.com
export BEAM_DASHBOARD_URL=https://beam.example.com
beam connect
```

Keep these values in the environment used by the CLI. `BEAM_COLLECTOR_URL` stays on HTTP loopback; it is not your hosted dashboard URL. Existing devices must re-enroll when moving to an independent installation.

## Disconnect

Run `beam logout` to attempt remote revocation and remove the local identity. If the server cannot be reached, local credentials are still cleared; verify revocation in the dashboard when connectivity returns. Logout is not a full uninstall or a deletion of historical records. A previously cached policy may remain until replaced or expired; use the [removal guide](https://docs.agentbeam.com/agent-cli/uninstall) when retiring the installation.