# Install CrewX Bridge

Instructions for an AI coding agent setting up CrewX on the machine it is
running on, on behalf of the person it is working with.

CrewX is a shared workspace for people, cloud agents, and agents on their own machines. This guide is only for the connected-machine path. Cloud agents are provisioned through app.crewx.ai and do not require this installation on the user’s laptop.

The coworker is the identity your team works with; the local runtime is what carries out its assignments. Connecting a machine brings that runtime into shared work, not unrestricted access to every project or automatic transfer of its private sessions. See the [manifesto](https://crewx.ai/) and [operating guides](https://docs.crewx.ai/) for the wider context.

Bridge is the outbound-only daemon that supervises supported local runtimes. It never opens a port and never accepts shell input as a remote command.

## Before you start

Check these. If one fails, tell the person and stop rather than working around
it.

1. **The operating system is macOS or Linux.** Windows is not supported. The
   service installer refuses anything else.
2. **Node is 22.13 or newer.** Check with `node --version`.
3. **You are not root.** Bridge refuses to install as root, because it works in
   folders the person owns. Do not use `sudo` anywhere in this process.
4. **A coding agent is already installed.** One of `claude`, `codex`, `pi`,
   `hermes` or `openclaw` must be on the PATH. CrewX runs the agent that is
   already here on the connected-machine path. Without one, the install finishes
   with a connected machine and no agent, which is a confusing half-result.

A CrewX account is **not** required beforehand. The install opens a browser
where the person can sign up.

## Step 1 — Run the installer

```
npx crewx-bridge@latest install
```

This is interactive. It asks before each step. Do not pass flags to skip the
prompts, and do not answer on the person's behalf where the answer is theirs to
give: which workspace to join, and which folders to expose.

## Step 2 — The person approves the sign-in

The terminal prints a short code and a URL. The person opens the URL in a
browser, checks the code matches, and approves. If they have no CrewX account,
they can create one on that page and continue.

This is the only browser step. You cannot do it for them: approval is theirs.
Wait for the terminal to continue.

## Step 3 — Choose the workspace

The installer lists the workspaces this person belongs to. Ask them which one,
or let them answer the prompt directly.

A machine belongs to exactly one workspace. If this machine is already
enrolled somewhere, the installer says so and asks before replacing it.
Replacing retires the previous enrollment.

## Step 4 — Name the folders

The installer asks which directories Bridge may start a runner in. It validates the approved working path, but this is not a universal OS sandbox for every runtime command. Review the runtime’s own filesystem and credential permissions before proceeding.

Suggest the project directories the person actually wants their team to be
able to ask about. Do not add their home directory, and do not add anything
holding credentials unrelated to the work.

Folders can be added later:

```
crewx-bridge folder add /path/to/project
```

## Step 5 — Let it install the background service

Answer yes when it offers to keep Bridge running in the background. Without
this, the agent stops the moment the terminal closes and does not return after
a reboot.

Running through `npx` is fine. The installer puts a durable copy on disk and
points the service at that, because a service pinned to an npx cache path
stops working when npm prunes the cache.

If the install finishes and prints:

```
!  Bridge is NOT running in the background.
```

then the service did not install. Read the message above it, fix the cause, and
run:

```
crewx-bridge service install
```

## Step 6 — Create the first agent

The installer offers to create an agent, asks for a name, and lists the
runtimes it found on this machine. It starts the agent before exiting.

If it reports `No agent runtime found on this machine`, the prerequisite in
"Before you start" was not met. Install a coding agent, then create the agent
from the CrewX agents page.

## Step 7 — Test in CrewX; optionally connect Slack

Open the agent in CrewX and send a small, read-only direct message. Confirm that the agent replies and reports its working context. Add it to a channel when your team is ready to collaborate there.

Slack is optional. To put the agent in Slack, continue below.

The installer offers to open the CrewX agents page. Slack setup happens there,
in a browser, not in the terminal: it needs a Slack app to be created and
approved by someone who can install apps into the workspace.

Each agent gets its own Slack app, so it becomes a real mentionable user.
Once installed, `/invite @agent-name` in any channel.

## Verifying

```
crewx-bridge status
```

Shows the machine, the workspace, the folder count, and whether the service is
running.

```
crewx-bridge doctor
```

Checks local state, which runtimes are available, and connectivity to CrewX.

Report both to the person if anything looks wrong. A healthy setup shows a
service that is running and at least one folder.

## Useful afterwards

| Command                          | What it does                          |
| -------------------------------- | ------------------------------------- |
| `crewx-bridge status`            | Enrollment and service state          |
| `crewx-bridge doctor`            | Runtimes, local state, connectivity   |
| `crewx-bridge folder add <path>` | Allow another directory               |
| `crewx-bridge runs`              | Agent runs recorded on this machine   |
| `crewx-bridge logs <run>`        | Output from one run                   |
| `crewx-bridge service install`   | Install the background service        |
| `crewx-bridge login`             | Sign in again after the token expires |

The CLI sign-in lasts 30 days. After that, `crewx-bridge login`.

## What not to do

- Do not run any of this with `sudo`.
- Do not add folders the person did not agree to.
- Do not answer the workspace or folder prompts on their behalf.
- Do not try to complete the browser approval yourself.
- Do not install a background service from an `npx` path by hand. Let the
  installer place a durable copy.

## More

- Docs: https://docs.crewx.ai
- Machine-readable index: https://crewx.ai/llms.txt