FAQ and Help
Find why an agent stopped answering, or check a device, sign-in or credential question.
On this page
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.
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 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:
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, 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?. |
| 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 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 gives the supported alternatives.
Install and sign in using Mac setup, Windows setup or Server and VPS setup. 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 preserves the whole /home/node directory in a volume.
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.
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 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 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, Windows setup or Server and VPS setup. For OrbStack or WSL, follow the sign-in steps in that environment's recipe. OpenCode needs its own installed, running server, separate from the Companion.
The Docker example 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 or Windows setup, 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 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 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.
How do I see what an agent actually did?
On the device, run:
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 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. Check them before removing the old device through Devices.
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.