Connecting projects

Once you have authenticated the CLI, forge connect brings your machine online. The connection is made per machine and per organization, not per project directory: one registered CLI device serves every project in the organizations you linked during login. You do not run forge connect from inside a repository — the CLI manages its own clones under ~/.forgeai/ and finds your project's code through the Git repository URL configured on the cloud project.

Being connected is what makes the cockpit useful: creating a BMAD workflow requires at least one CLI device registered in the organization, and every workflow step and board task is executed by agents running on a connected CLI.

Starting the connection

forge connect

By default this spawns a background daemon and returns immediately, printing the daemon PID and the per-organization connection status. If a daemon is already running, forge connect reports its PID and per-organization status, and re-establishes connections for linked organizations the daemon is no longer tracking (for example organizations linked after the daemon started, or connections the server closed). An organization you disconnected with forge disconnect stays disconnected until you run forge reconnect.

Flag	Effect
--org <slug>	Connect to one organization only
--server <url>	Override the cloud server URL for this run
--attach	Run in the foreground (blocks the terminal; Ctrl-C to stop)
--stop	Shut down the background daemon

On startup the daemon:

1. Warns if no credentials are stored for the configured agent engine (agents will fail to authenticate. Run: forge auth setup-claude — or setup-codex / setup-opencode; see Authenticating the CLI).
2. Initializes the Docker-backed agent runtime (see Installing the CLI for the Docker requirement).
3. Opens a Socket.io WebSocket connection to every linked organization.
4. Runs an MCP self-probe to verify it can receive agent dispatches.

Daemon state lives under ~/.forgeai/:

File	Purpose
daemon.pid	PID of the running daemon
daemon.sock	Unix socket used for IPC between forge commands and the daemon
daemon.log	Daemon stdout/stderr

What the live connection does

While connected, the WebSocket connection to each organization is the channel through which:

• The cloud dispatches workflow steps and board tasks to your machine, where agents run in local Docker containers.
• Agent output streams back live to the task board and the workflow wizard.
• The cloud requests git operations (creating workflow and task branches, merges for releases).
• The cloud pushes configuration changes — for example, changing a device's agent slots in the cockpit applies to the running CLI immediately and is persisted locally.

If the WebSocket drops, events the CLI produces are journaled locally as NDJSON under ~/.forgeai/events/ and re-synced to the cloud over REST when the connection returns. See the CLI command reference for the forge journal commands that inspect this journal.

Heartbeats

Every 30 seconds the connected CLI sends a heartbeat carrying its device ID, name, agent slots, active agent counts, and MCP health. The cloud stores the heartbeat in Redis with a 60-second TTL — this is what drives the live Connected/Disconnected status in the cockpit.

Two failure modes are handled automatically:

• MCP unhealthy — if the MCP self-probe fails, the CLI prints MCP unhealthy — this CLI will not receive dispatches and re-probes every 60 seconds until healthy. The dispatcher skips devices reporting unhealthy MCP.
• Authentication failures — after 3 consecutive Socket.io authentication failures the CLI exits and asks you to run forge auth login again.

Disconnecting and reconnecting

forge disconnect
forge reconnect

forge disconnect closes the WebSocket connections while keeping the device registered in the cloud. With a running daemon it disconnects via IPC and the daemon stays alive; without one, it notifies the cloud over REST for each linked organization. Use --org <slug> to disconnect from a single organization.

forge reconnect re-establishes dropped connections through the daemon. It only works when a daemon is running — otherwise it errors with No daemon running. Run 'forge connect' first.

When a CLI disconnects, the cloud releases its work: tasks that were ACTIVE on that device return to WAITING and are re-dispatched to other available CLIs in the organization. Tasks waiting on a human (Awaiting Input or Corrections Requested) keep their state.

Managing linked organizations

forge org list
forge org unlink <slug>

forge org list shows every linked organization with the default marked and a per-organization status: connected, disconnected, not registered, or unreachable.

forge org unlink <slug> asks for confirmation, warns when you are unlinking your last organization, then disconnects and deletes this device's registration in that organization. To link organizations again, run forge auth login and select them on the approval page.

Managing CLI devices

forge cli list
forge cli unlink <cliId>

forge cli list lists all registered CLI devices in your default organization — name, device ID, owner, agent slots, and last-seen time — with your own device flagged (current).

forge cli unlink <cliId> unregisters a device after confirmation, and warns if you target the device you are running from.

The number of CLI devices an organization can register depends on its plan; if registration is rejected with a plan-limit error, the CLI suggests upgrading or unlinking an existing device. See Plans & billing.

Team setup

Each teammate connects their own machine: they repeat the installation, forge auth login, and agent-credential setup steps locally (forge auth setup-claude by default — see Authenticating the CLI). AI credentials are stored per machine, so every teammate uses their own subscription or API key — agents dispatched to a device always run on that device owner's tokens, with that device's configured agent engine (teammates can each pick a different one). Keep the plan limit in mind: the Free plan allows only 1 registered CLI device per organization, so a second teammate cannot register a device until the organization upgrades or the existing device is unlinked. See Plans & billing.

How the cockpit shows the connection

The cockpit surfaces CLI connections in two places:

• Settings → CLI Devices (/orgs/<slug>/settings/cli-devices) — a table every member can view, with columns Name, Owner, Status, Agent Type, Models, Agent Slots, Occupation, Cooldown, and Last Seen. The Models column shows the models the device declares per engine; the device's owner (or an admin) can edit the list, and org admins can lock it — a locked list is owned by the cockpit, the CLI can no longer change it, and the device is only dispatched on engines present in the locked list. Status (Connected, Reconnecting, Disconnected) comes from the Redis heartbeats; disconnected rows tell the owner to run forge connect. The device's owner or an org admin can change settings, force-disconnect the device, or unlink it entirely (which also unassigns its tasks).
• The status bar — at the bottom of every organization page (including the project task board), a live summary of connected CLIs and agent slot usage, or No CLI connected, which can be clicked to list the devices.

If your device shows as Disconnected in the cockpit while forge connect says it is running, see Troubleshooting & FAQ.