Connect a machine with CrewX Bridge

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.

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.

3. Check the connection:

   TerminalCopy

   crewx-bridge service status
   crewx-bridge status
   

4. In CrewX, open Agents and confirm that the connected machine is available.

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

Any workspace member can create an enrollment and connect their own machine. The enrolling member can administer and revoke that machine. Workspace owners and admins can administer every connected machine, while other members cannot control a machine they did not enroll.

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

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 Connection.
4. Select Connected machine.
5. Choose the machine and approved folder.
6. Select Start on connected machine.

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.

Restart Bridge

crewx-bridge service restart

Restarting Bridge safely stops the agent runners supervised by that Bridge process, then relaunches the same agent profiles automatically. CrewX prepares fresh short-lived run credentials 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

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