Connect a machine with CrewX Bridge

For the desktop setup, follow Getting started. CrewX desktop includes a background Bridge and starts it after you review the connection and working folder.

This guide covers the separate command-line Bridge installation for existing or advanced setups.

Before you begin

CrewX Bridge is the small background service that turns a Mac or Linux machine into a connected machine in CrewX. It lets authorized workspace members start an existing agent runtime in an approved project folder without opening another terminal on that machine.

Choose this path to bring your own installed and authenticated runtime. Cloud agents are provisioned by CrewX and do not require installing Bridge on your laptop.

You need macOS or Linux, Node.js 22.13 or later, and a supported runtime installed and signed in. Use the operating system account that owns your project files, not root.

Bridge accepts a limited set of structured commands. It does not accept arbitrary shell commands.

The desktop's bundled Bridge preserves saved agents, conversations and approved folders across reconnects. Keep the computer awake and use its connection controls to retry the existing profile when needed. Desktop and npm-managed Bridge installations have separate update paths.

Connect a machine

1. On the machine where the agent will run, start the installer:

   TerminalCopy

   npx crewx-bridge@latest install
   

2. Follow the prompts to sign in, select your workspace, approve a project folder, and install the background service. Choose an existing agent profile or create another when the workspace already has agents.

3. Check the connection:

   TerminalCopy

   crewx-bridge service status
   crewx-bridge status
   

4. Verify the saved agent profile you will use:

   TerminalCopy

   crewx-bridge agents list
   crewx-bridge verify --agent PROFILE_ID
   

   Replace PROFILE_ID with the profile ID from the list. This reads its saved provider and model and requires your CrewX management sign-in. Save profile changes before verifying again. To check a provider separately, use crewx-bridge verify codex or crewx-bridge verify claude.

   Verification defaults to configured_service_launch: it uses the background service's configured runtime settings, writes a random marker in a temporary folder, removes the file, and checks that a new worker remembers the marker in the same conversation. It uses your provider account's normal quota and removes its temporary workspace afterwards. Provider-owned conversation history remains in the provider's storage.

   If your account cannot use its configured default model, select a supported model with crewx-bridge verify codex --model <model-id> and use that model in the CrewX agent profile. CrewX sign-in and provider sign-in are independent; logging into CrewX does not refresh Claude or Codex credentials.

5. In CrewX, open Agents, select the connected machine and approved folder, and send the agent a small task. A current Bridge heartbeat proves the machine is connected. A successful provider verification proves that the selected runtime can respond. The first reply in CrewX confirms the complete connection.

If installation fails, use Troubleshoot an offline agent. For installation details intended for an agent to follow, see the agent-readable install guide.

Hermes continuation requires its restored conversation history. If verification reports missing history after restart, check the provider version and state directory, repair its local history, or start an explicitly new CrewX conversation. CrewX preserves the existing session binding and stops before sending a new prompt when the expected history is unavailable.

Workspace owners and admins can create an enrollment and connect a machine when connected computers are enabled. The enrolling member can administer and revoke that machine. Workspace owners and admins can administer every connected machine. Starting an agent also requires permission to administer that agent profile.

You can also begin from Agents → Connect machine. Run its one-time enrollment command on the target computer, approve a project folder there, install the service, and run the same provider verification. The web setup checklist follows the machine's actual progress. Folders must always be approved locally.

If setup stops partway through, run crewx-bridge install again. It reuses the existing machine enrollment and lets you finish missing setup steps. Use --replace only when you intend to retire the previous connection and enroll elsewhere. Stop the service and reconcile pending command outcomes first.

npx crewx-bridge@latest service stop
npx crewx-bridge@latest runs --all
npx crewx-bridge@latest outcomes list

Reconcile outstanding outcomes with the original workspace before install --replace. Replacement refuses active runners, an unhealthy service, or unreported command outcomes so you can recover the existing connection first.

If the installer used a private npm prefix, use the executable path it prints, or prefix these commands with npx crewx-bridge@latest when crewx-bridge is not on your PATH. The installer keeps a durable copy for the service even when you started through npx.

Run in a foreground terminal

For a foreground terminal connection, run setup with --no-service --no-agent, then run the Bridge daemon yourself:

npx crewx-bridge@latest install --no-service --no-agent
npx crewx-bridge@latest serve

Use --url https://your-server.example during install for a self-hosted server. Wait for the machine heartbeat to appear online, then start the agent from CrewX. Leave the foreground terminal open while agents work. Stop the background service first if it already owns the same enrollment. New web connections use Bridge; existing CLI join codes continue working, but the profile no longer offers reusable-token generation.

With Bridge 0.2.67 or newer, explicitly check the current terminal's provider environment before enrollment or for a foreground connection:

crewx-bridge verify codex --environment interactive
# Select a supported model when needed:
crewx-bridge verify codex --environment interactive --model gpt-5.5

This provider-only check needs no CrewX enrollment or installed service. It uses the terminal's filtered provider settings and normal provider quota. A pass verifies that environment, not the background service or its heartbeat. The default remains configured-service verification and never silently falls back to the terminal. To check a saved profile in this mode, use crewx-bridge verify --agent PROFILE_ID --environment interactive; profile selection still requires enrollment and your CrewX management sign-in.

When foreground setup creates or selects an agent, install --no-service --verify uses interactive verification. Run crewx-bridge serve afterwards, leave its terminal open, and confirm the agent replies in CrewX.

Sign in again or disconnect

Use crewx-bridge login --force to replace an expired or rejected CrewX management sign-in. For a self-hosted server, include --url https://your-server.example. Explicit server choices must match the enrollment you intend to manage.

crewx-bridge logout requests revocation of the management sign-in and removes it locally. If CrewX cannot confirm revocation, the CLI warns you; reconnect and revoke that sign-in before treating the remote token as retired. The enrolled machine and its running agents remain connected. To disconnect the computer from the workspace, use Agents → connected machines → Revoke machine. Revocation prevents new launches and disconnects that machine's active CrewX runs.

Approve another project folder

On the connected machine, approve each additional folder that CrewX may use:

crewx-bridge folder add /absolute/path/to/project
crewx-bridge folder list

Replace /absolute/path/to/project with the full path to your project. The folder should appear in the list before you start an agent there.

If you skipped service installation during setup, install the per-user background service:

crewx-bridge service install
crewx-bridge service start
crewx-bridge service status

Run the service as the operating system user who owns the project folders. Do not install it as root.

Folder approval limits where Bridge can start a runner; it is not an OS sandbox that confines every runtime action. Review permissions and safety, including the runtime’s own filesystem and credential access.

Start an agent

OpenClaw uses its native integration with a selected agent bound to the approved folder. The execution-folder checks require Bridge 0.2.66 or newer, which bundles CLI 0.2.42; direct terminal runners require CLI 0.2.42 or newer. Upgrade an existing background Bridge and verify its fresh heartbeat before starting or migrating an OpenClaw profile:

npx crewx-bridge@0.2.74 update --to 0.2.74 --repair
npx crewx-bridge@0.2.74 service status

Confirm the running service reports 0.2.66 or newer. Older clients can still appear online; updating the server does not update those local binaries. The web Start and Restart controls require a reported Bridge version of 0.2.66 or newer for native OpenClaw. Upgrade and wait for a fresh heartbeat if those controls show an older or unknown version.

Its ACP connection does not bind the Gateway workspace, so CrewX refuses that route. Existing OpenClaw ACP profiles need an explicit change to the native runtime and agent ID. crewx-bridge verify openclaw is unavailable; check provider authentication, the run log, and a test message in CrewX.

To change an existing ACP profile, stop its Bridge runs and disconnect its terminal sessions first. For a crashed or stale connection, use Deactivate to close its sessions. Wait for assignment leases to expire or cancel parked work, then select Validated native agent and the intended OpenClaw agent ID in profile settings and save. Saving revokes the profile's previous connection tokens. Reactivate if needed, then reconnect or start it again.

You can create a new profile on a connected machine or restart an existing offline profile:

1. Open Agents.
2. Open the agent profile.
3. Select Computer.
4. Select Connected machine.
5. Choose the machine and approved folder.
6. Select Start on connected machine.

For a new profile, Create and start agent saves the profile before requesting its launch. If launch is refused, the dialog keeps the explanation and offers Start saved profile. Resolve the issue, review the machine and folder, then use that action to start the same profile with its saved model and permissions. If creation or start cannot be confirmed, check Agents and the profile's Computer panel before trying again. CrewX does not automatically resend the request.

Starting or stopping a process requires permission to administer both the connected machine and the agent profile. CrewX also checks runtime availability, the local permission policy, approved folders, and agent capacity before it queues the start.

The Computer panel explains current readiness blockers beside Restart unavailable, Machine offline or Upgrade Bridge. If the server refuses a submitted restart, Restart not queued keeps its explanation visible. Resolve the reported issue, choose Restart agent explicitly, and wait for a fresh agent session. A new heartbeat does not resend a refused restart.

For terminal management, use a unique agent name or its profile ID:

crewx-bridge agents list
crewx-bridge agents start Atlas
crewx-bridge agents stop Atlas
crewx-bridge agents restart Atlas

Start requests are queued until the connected Bridge claims them. Restart waits for the old process to stop before its replacement may start. Stopping keeps the agent profile and its conversation history.

Restart Bridge

crewx-bridge service restart

Restarting Bridge first checks that its agents have finished active work. A busy or disconnected Bridge refuses the restart before stopping any process. Once idle, CrewX briefly holds new assignments, stops the supervised runners, and relaunches eligible profiles after the service returns. CrewX prepares fresh credentials restricted to each replacement run on the server, waits for the old local processes to stop, and only then lets the replacement Bridge start them. Agent credentials are never stored in Bridge's local journal.

Use a cold restart when you intentionally want every supervised agent to stay offline:

crewx-bridge service restart --no-resume-runs

Cold restarts require the same idle check. If an automatic relaunch is already prepared, complete it or wait for its five-minute preparation to expire before choosing a cold restart.

Bridge 0.2.70 or newer checks readiness before an update changes any packages. It updates the existing installation, including a private runtime installed when the global npm directory was unwritable. Use the absolute executable printed by setup to update that installation. --yes confirms the update and does not force an interruption.

If installation fails, inspect the package and service state before retrying; npm may have partially changed files even though the old processes remain running. The temporary assignment hold expires five minutes after the last successful preparation. A retry reuses an unexpired prepared replacement. Finish active work or restore a disconnected machine, then run the update again. Parked assistance checkpoints are retained.

The same automatic recovery applies to crewx-bridge update, so updating Bridge no longer requires reopening every agent profile in the dashboard.

Inspect local runs

crewx-bridge runs
crewx-bridge runs --all

The first command shows active local runs. The second includes stopped, failed, and lost history.

Use the Bridge log when you need more detail:

tail -f "$HOME/Library/Logs/CrewX Bridge/bridge.log" \
  "$HOME/Library/Logs/CrewX Bridge/bridge.error.log"

On Linux, inspect the user service with:

journalctl --user -u crewx-bridge.service -f

Conversation responsiveness

Bridge 0.2.73 bundles CLI 0.2.47. Codex and Claude ACP conversations show when the runtime is connecting, when the session is ready, when it is composing a response, and safe tool activity. Chat stays compact for simple replies; tool work adds an activity trail. These stages reflect runtime events, not a simulated timer. Codex and Claude assistant text appears as a live draft as it arrives, then becomes a normal reply after successful completion. Tool calls clear the preceding draft narration. Cancellation and failure remove the draft without posting an unfinished answer. Private reasoning and raw tool data stay private.

ACP adapters launched through npx prefer a compatible cached package to avoid rechecking the registry on every message. A cache miss still downloads the adapter. Explicit npm_config_prefer_offline or npm_config_prefer_online environment preferences override this default. Bridge updates continue to use the regular update workflow.

A Codex model-metadata warning followed by the known ChatGPT unsupported-model rejection now fails the request with an actionable profile-setting message instead of posting the rejection as a successful reply. Plain JSON answers and quoted error examples are unaffected. Check the agent's model override if the runtime cannot use a model selected in your local Codex settings.

Provider generation and restoring a conversation can still take time. The live stages distinguish startup from response composition; they do not promise a fixed response time. Update an existing machine and restart its idle agent to use the new runtime without resetting the conversation.

Codex and Claude pre-tool narration is omitted from the completed reply. New tool calls clear preceding narration; late completion updates for an already observed call retain the final answer. The runtime's persisted conversation history remains intact.

Dashboard refreshes use a bounded coalescing window: frequent activity no longer pushes the next refresh farther into the future. Pending changes are retained while a refresh is running, and the request-rate limit still applies. Hidden tabs reconcile when visible again.

ACP follow-ups send context updates rather than repeating unchanged operating instructions and workspace items. New or edited messages, documents, tasks and memories remain available; changed permissions and instructions are sent in full. The update checkpoint is bound to the exact provider conversation and last successful turn. A missing, stale or invalid checkpoint falls back to a full snapshot without resetting history. First turns and large truncated snapshots retain the full prompt. This reduces repeated prompt processing; it does not erase the provider's existing context or eliminate provider startup time.

Live reply drafts

With Bridge 0.2.73 / CLI 0.2.47 and a server that advertises live-draft support, Codex and Claude ACP replies show a compact agent row with an updating status before the run finishes. Assistant text streams directly below Writing a reply…; tool details are available under View activity. Draft text updates in small batches; the dashboard refresh limit still applies. A successful run replaces the draft with its completed, formatted reply. Drafts are tentative: tool work can clear earlier narration, and an interrupted run may leave no completed answer. No partial draft is sent to other agents as conversation history. Draft bodies are excluded from the runtime event audit payload and cleared from message delivery metadata when the assignment finishes. Previews are limited to 32 KB; longer replies continue and appear in full when finished. Updating the Bridge preserves the existing conversation. Older servers and runtimes retain completion-only replies.