Mac setup

Install the Companion in macOS Terminal and pair your Mac as a device in Cabane. Agents placed on it work as your macOS account, with its files, tools and signed-in accounts, without asking before each action. This page takes you through pairing, signing in to a harness and keeping the Companion running.

To give agents less, use a harness sandbox or an isolated OrbStack machine, described in Give agents their own environment.

Before you start

Have your Cabane workspace open in a browser, and the account or provider credentials you plan to use with Claude Code, Codex or OpenCode. Your Mac must stay awake and online while agents work.

1Pair it

If you do not have a Cabane workspace yet, create it first. In Cabane, choose the gear at the bottom of the sidebar to open the workspace's Settings, then choose Devices → Set up a new device. The same dialog is available from Connect AI during workspace setup, and Your settings → Devices → Add a device pairs a device without adding it to a workspace.

Copy the line under With the installer and paste it into macOS Terminal:

curl -fsSL https://cabane.ai/install.sh | bash

The installer supplies Node and the Companion under ~/.cabane, then runs cabane setup, which prints a code and a link:

◇  Pair this device
│  Enter this code in Cabane, or press Return to open the page:
│
│    WXYZ-2345
│    https://app.cabane.ai/pair/enter-code
│
◒  Waiting for you to confirm in Cabane… (the code is good for 15 minutes)

In the dialog you opened in Cabane, type the code into Code from the terminal. Cabane shows which device asked: its name, platform and how long ago it asked. Choose Confirm. A few seconds later the terminal says the device is paired: it's paired to your account, and the workspace's dialog adds it to that workspace. A code works once and expires after 15 minutes; the terminal prints a fresh one when it does. Follow any PATH instruction the installer prints. The page the terminal's link opens, which Return opens too, also takes the code, but pairs the device to your account only; a device paired there is added to a workspace afterwards with Add a device in that workspace's Settings → Devices.

On a first interactive setup, if none of Claude Code, Codex or OpenCode is usable, setup asks “Cabane needs one of them. Which will you set up?” Choose the one you intend to use. Setup prints installation and sign-in lines for only that choice.

In the same terminal, check the Companion:

cabane status

Pairing does not sign you in to Claude Code, Codex or OpenCode. Needs sign-in is expected until you complete the next step.

2Sign in

For Claude Code or Codex, run the lines setup printed in macOS Terminal, or use the commands below. For OpenCode, open Details: OpenCode instead and follow its sign-in and server steps; setup's printed lines omit provider sign-in. In an OrbStack machine, follow Sign in inside the machine instead.

Claude Code: install its sign-in CLI and sign in:

curl -fsSL https://claude.ai/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
claude auth login

Complete the sign-in in your browser, and return any code requested by the terminal.

export PATH="$HOME/.cabane/node/bin:$PATH"
npm i -g @openai/codex
codex login

curl -fsSL https://opencode.ai/install | bash

opencode auth login

opencode serve --port 4096

Return to your original terminal window and run cabane status. Your chosen harness should show connected.

For other authentication options, see signing in without a browser and when to use a token.

3Keep it running and update

Install the Companion's service in macOS Terminal:

cabane service install
cabane service status

The service is a LaunchAgent: macOS asks you to allow it as a background item. It starts when you log in to macOS, rather than when the Mac first boots, and enables automatic updates, which can restart the Companion during a turn. Keep the Mac awake and online while agents work.

After a restart, log in and check cabane service status. Run cabane start if the Companion is stopped. If you use OpenCode, also open a separate terminal window and run opencode serve --port 4096 again.

If you run the Companion without its service, run cabane update when no agent is working.

Stop, pause or remove

In macOS Terminal, cabane stop stops the Companion and any running turns. Use cabane start to start it again. Stop a separate OpenCode server with Ctrl+C in its window.

cabane service uninstall disables automatic startup. cabane logout clears pairing credentials and keeps your configuration and the device record in Cabane. For deactivation, token rotation, removal or pairing a removed device again, see Devices.

Give agents their own environment

Recommended for agents reading untrusted input, such as public websites or inbound mail, and for a Mac a team shares. Agent access compares the levels.

• A harness sandbox. Install directly as above and follow Harness sandboxes to configure Claude Code or Codex.
• An isolated OrbStack machine. Agents work in an Ubuntu environment that sees only the Mac folder you share. Follow the recipe below instead of steps 1 to 3.
• A Docker container. With Docker Desktop, follow the Docker environment recipe in macOS Terminal, including its pairing and sign-in steps.

OrbStack isolated machine

You need Homebrew, and an existing folder to share. The commands below use ~/project; replace that path with yours.

Prepare the machine

In macOS Terminal, install OrbStack:

brew install orbstack

Open the OrbStack app and complete its initial setup. Return to macOS Terminal to create and enter the Ubuntu environment:

orb create --isolated --mount ~/project:/work ubuntu cabane
orb -m cabane

You are now in an Ubuntu shell. Your chosen Mac folder appears at /work. Changes there change the files on your Mac, and those files survive removal of the Ubuntu environment.

The --isolated option removes OrbStack's default /mnt/mac mount and SSH agent forwarding. OrbStack environments still share a Linux kernel, so this isolation has limits.

Pair the machine

Open the workspace's Settings → Devices → Set up a new device, as in step 1, and run the line under With the installer in the Ubuntu shell:

curl -fsSL https://cabane.ai/install.sh | bash

Setup prints a code; enter it in the dialog and choose Confirm. If setup asks “Cabane needs one of them. Which will you set up?”, choose the one you intend to use, then sign in as described below. Check the Companion with cabane status in the Ubuntu shell; Needs sign-in is expected until you sign in.

Sign in inside the machine

Install and sign in from the Ubuntu shell, even if you already use the same account on your Mac. The isolated Ubuntu environment cannot open your Mac's browser: open each printed sign-in URL yourself in your Mac's browser, complete sign-in, and return any code requested by the Ubuntu terminal.

Claude Code:

curl -fsSL https://claude.ai/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
claude auth login

export PATH="$HOME/.cabane/node/bin:$PATH"
npm i -g @openai/codex
codex login --device-auth

curl -fsSL https://opencode.ai/install | bash

opencode auth login

opencode serve --port 4096

Return to your original Ubuntu shell and run cabane status. Your chosen harness should show connected.

Keep the machine running

Install the Companion's service in the Ubuntu shell:

cabane service install
cabane service status

The service is a systemd user service and enables automatic updates, which can restart the Companion during a turn. If cabane service install asks you to enable linger, run this in Ubuntu so the service can continue after logout:

sudo loginctl enable-linger "$USER"

Keep the Mac awake, online and running OrbStack. After a restart, open OrbStack, then enter Ubuntu from macOS Terminal:

orb -m cabane

In Ubuntu, check cabane service status and run cabane start if the Companion is stopped. If you use OpenCode, also open a separate Ubuntu shell and run opencode serve --port 4096 again.

To stop or disconnect, run the commands in Stop, pause or remove in the Ubuntu shell.

Back to Quick start

Return to Quick start: check the device.