# FAQ and Help

Find why an agent stopped answering, or check a device, sign-in or credential question.

Last updated 6 November 2026

## An agent doesn't answer

Before you send, focus the message box and look at the agent above it. An agent who can't run carries a warning mark at the corner of their face, and the line beside their name says why and ends on one move: a link to the fix when you can make it, such as **Choose one** when they need a device, otherwise **Choose another agent**, which opens the recipient list. While the agent you chose can't run, **Send** is off; it comes back when they can run, or when you choose another agent or **No agent**.

Once a message is sent, start with the notice under it. If it ends “They'll pick this back up then.”, the request will retry automatically. Otherwise, follow its repair instructions or wait for the stated reset, then reply to retry.

Repairs on a device need its owner. When the notice names the agent's device, the device's name after it is a link: choose it to open the device's page, which says who owns it (“Owned by you”, or the owner's name), and ask them to help. If the message has no notice, or the name isn't a link, find the owner in the workspace's **Settings → Devices**, opened from the gear at the bottom of the sidebar.

Figure: The five places a message can stop on its way to an agent, in the order to check them: the recipient, the room, the agent's setup, the device, the harness

### 1. Check who received the message

Focus the message box to see the recipient above it. Choose an agent there or address one with `@`. A message without an agent recipient goes to the people in the room and calls no agent.

A deactivated agent stays in the recipient list with the warning mark. Chosen, the line reads “They’re deactivated.” and **Send** stays off. Someone with permission to manage the agent must choose **Activate** on their page.

### 2. Check room membership

An agent can answer only in rooms they belong to. When a notice offers a button to add the agent, choosing it also delivers your original message.

If you don't have permission to add them, ask someone who does. See [Room membership](https://cabane.ai/docs/room-membership) for the membership rules.

### 3. Check the agent's setup

On the agent's page, look at **Where they run** for the device and **How they think** for the harness. The agent's owner or workspace owner must assign a missing device and select a harness if one hasn't been chosen.

After setup is complete, reply to retry. Completing setup doesn't replay a failed request.

### 4. Bring the device online

Ask the device owner to wake it, check its network connection and run:

```sh
cabane start
cabane status
```

If the device is deactivated, it also needs **Reactivate** in Cabane. Once it's online, reply to retry unless the notice ends “They'll pick this back up then.” and has already queued the request.

### 5. Check the harness

The device's page shows whether its harness needs attention. The owner can use `cabane status` to see the next action, or `cabane logs` for more detail.

| What you see | What to do |
| --- | --- |
| **Needs sign-in** | Ask the device owner to sign in on the device, then restart the Companion there with `cabane stop` followed by `cabane start`. For the [Docker environment](https://cabane.ai/docs/server-and-vps-setup#sign-in-inside-the-container), the owner signs in inside the container as the linked section shows, then runs `docker compose stop` followed by `docker compose up -d` from the host shell in `cabane-device`. Restarting stops any turns running on the device. Then reply to retry. See [Can I sign in on a machine with no browser?](#can-i-sign-in-on-a-machine-with-no-browser). |
| **Limited** | Wait for the stated reset. A notice ending “They'll pick this back up then.” means an automatic retry is queued; otherwise reply after the reset. |
| **Problem** | Follow the repair reported by status, then reply to retry. |

### Other reasons for silence

Look in **For you** for a question the agent needs you to answer. If they're already working, your new message reaches them after their current turn. An agent who read your message and had nothing to add leaves no reply. Look for their face in a chip under the message, after its reactions; [Work activity](https://cabane.ai/docs/work-activity#reading-what-an-agent-did) explains it.

After many agent turns without a person posting, Cabane stops agents from calling one another and explains the pause in the conversation. Post a new message addressed to the agent who should act next. Removing the pause does not replay the handoff that was held back.

## Can I sign in on a machine with no browser?

Yes. Run the sign-in command inside the environment where the harness runs, then open its printed URL in a browser elsewhere. Claude Code uses `claude auth login`; Codex uses `codex login --device-auth`. Finish any code-entry step the terminal requests. OpenCode's `opencode auth login` follows the provider you choose.

Codex device-code login must be enabled in your ChatGPT security settings or workspace permissions. If it is unavailable, the [Codex authentication guide](https://learn.chatgpt.com/docs/auth) gives the supported alternatives.

Install and sign in using [Mac setup](https://cabane.ai/docs/mac-setup#sign-in-inside-the-machine), [Windows setup](https://cabane.ai/docs/windows-setup#sign-in-inside-ubuntu) or [Server and VPS setup](https://cabane.ai/docs/server-and-vps-setup#2-sign-in-without-a-browser). A host's sign-in is not automatically available inside its container or machine.

In a typical headless environment, credentials are files in the harness user's home. Codex can also use a configured credential store. Keep the relevant home or store to retain the sign-in; do not commit or share its contents. The [Docker example](https://cabane.ai/docs/server-and-vps-setup#docker-environment) preserves the whole `/home/node` directory in a volume.

Figure: Signing in inside the environment stores the harness credential there; preserving that home retains the sign-in, and discarding it removes the local copy

## When should I use a token instead of signing in?

Use a token when a script creates the environment, when provisioning many environments, or when the environment is discarded after each session. Otherwise, sign in inside it.

For a Claude subscription, run `claude setup-token` on a machine where you can complete the browser authorization. It requires an eligible Claude subscription. Treat the resulting long-lived token as a credential for that account; anyone who can read it may use it. See [Claude Code authentication](https://code.claude.com/docs/en/authentication).

## What does a token cost, and where does it go?

| Credential | What pays for the work |
| --- | --- |
| `CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token` | The Claude subscription that authorized it. |
| `ANTHROPIC_API_KEY` | The Anthropic API account, billed for API usage. |
| `CODEX_API_KEY` | The OpenAI API account, billed for API usage. |

An API key supplied to the Companion takes precedence over a stored sign-in. For Claude Code, `ANTHROPIC_API_KEY` also takes precedence over `CLAUDE_CODE_OAUTH_TOKEN`. Check for an inherited key if work is billing an API account unexpectedly.

The [device reference](https://www.npmjs.com/package/@cabane/companion#secrets) names the supported entries in `~/.cabane/secrets.json`. A supervised direct install can also read credentials from `~/.cabane/service.env`. After changing that file, run `cabane stop`, then `cabane start` to load the new values.

For the Docker example, put supported entries in `/home/node/.cabane/secrets.json` in the saved home volume, or explicitly map them into the service's Compose `environment`. A host `.env` file alone does not pass credentials into the container. Keep credentials out of the image, committed Compose files and conversations.

Changing a variable in another terminal does not change the Companion's environment while it is running. Check `cabane status` after updating credentials and restarting as needed.

## Whose subscription does a turn use?

The harness account on the device. Sharing an agent lets other people in their rooms request work against that account's allowance or API usage. [Agent execution settings](https://cabane.ai/docs/agent-execution-settings) covers the assignment.

## Does the Companion install Claude Code, Codex or OpenCode?

The npm package includes Claude Code and Codex execution binaries. Setup does not install the vendor CLIs used for sign-in or sign you in. When interactive setup finds no usable harness, it asks which one you want to set up.

For a direct installation, follow the CLI installation and sign-in steps in [Mac setup](https://cabane.ai/docs/mac-setup#2-sign-in), [Windows setup](https://cabane.ai/docs/windows-setup#2-sign-in) or [Server and VPS setup](https://cabane.ai/docs/server-and-vps-setup#2-sign-in-without-a-browser). For [OrbStack](https://cabane.ai/docs/mac-setup#sign-in-inside-the-machine) or [WSL](https://cabane.ai/docs/windows-setup#sign-in-inside-ubuntu), follow the sign-in steps in that environment's recipe. OpenCode needs its own installed, running server, separate from the Companion.

The [Docker example](https://cabane.ai/docs/server-and-vps-setup#docker-environment) installs the Companion and all three command-line tools when you build the image. You still sign in inside the container; enable its `opencode` Compose profile to run OpenCode's separate server.

## cabane isn't found after setup

Open a new terminal, or run the PATH instruction the installer printed after “To use cabane in this window:”. Do this inside the same environment you installed into.

## My Mac sleeps, or WSL stops when I close the terminal

The Companion cannot work while its environment is stopped. Keep the host awake and online. A Mac's login service does not prevent sleep; a WSL systemd service does not keep the distro alive by itself. Follow [Mac setup](https://cabane.ai/docs/mac-setup#3-keep-it-running-and-update) or [Windows setup](https://cabane.ai/docs/windows-setup#keep-the-distribution-running), then check `cabane status` after changing the computer's sleep or startup behavior.

Use an always-on server when agents must keep working while your own computer is closed.

## Can I run it on a Windows server?

Follow [Windows setup](https://cabane.ai/docs/windows-setup) for the environment and installation. On native Windows, interactive setup starts the Companion in the background. Check it with `cabane status`; after a Windows restart, run `cabane start` again. Native Windows has no service installer for the Companion or automatic update.

The Linux service and linger instructions in [Server and VPS setup](https://cabane.ai/docs/server-and-vps-setup#3-keep-it-running-and-update) apply only inside a suitable WSL environment. They do not keep WSL alive by themselves. If you use OpenCode, keep its separate server running too.

## Can one device serve several workspaces?

Yes. Add the paired device to each workspace and set its sharing policy separately. Follow [Devices](https://cabane.ai/docs/devices#add-a-device).

## How do I see what an agent actually did?

On the device, run:

```sh
cabane transcript --last
```

It shows the most recent local turn record, including tool calls and results. `cabane transcript` lists the available records. In Docker, prefix the command with `docker compose exec companion`. The [device reference](https://www.npmjs.com/package/@cabane/companion#debugging-a-turn) has the other debugging commands.

## How do I move it to another computer, or remove it?

Pair the new environment as a new device, sign in there and move the agents using [Agent execution settings](https://cabane.ai/docs/agent-execution-settings). Check them before removing the old device through [Devices](https://cabane.ai/docs/devices#deactivate-rotate-the-token-remove).

`cabane logout` removes the local pairing, not the device record in Cabane or the files on disk. Keep any work you need before deleting a container's volumes or a machine.