Windows setup

Install the Companion in PowerShell under your Windows account and pair it as a device in Cabane. Agents placed on it work as that 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 returning after Windows restarts.

To give agents less, use a harness sandbox, a dedicated WSL environment or Docker Desktop, described in Give agents their own environment.

Before you start

Install Node 22 or newer: the install line installs the Companion with npm. Have your Cabane workspace open, and the account or provider credentials you plan to use with Claude Code, Codex or OpenCode. Windows 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 npm · @cabane/companion and run it in PowerShell:

npm i -g @cabane/companion; cabane setup

Setup 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 PowerShell 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; PowerShell prints a fresh one when it does. The page the 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.

Interactive setup starts the Companion in the background. In the same PowerShell window, run cabane status. Needs sign-in is expected at this stage: pairing does not sign you in to Claude Code, Codex or OpenCode.

2Sign in

For Claude Code or Codex, run the lines setup printed in PowerShell, 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 a dedicated WSL environment, follow Sign in inside Ubuntu instead.

Claude Code: use its PowerShell installer:

irm https://claude.ai/install.ps1 | iex

Run claude --version. If PowerShell says claude isn't recognized, the installer's folder isn't on your PATH. Add it for new windows and for this one:

$bin = "$env:USERPROFILE\.local\bin"
$p = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$p;$bin", 'User')
$env:PATH += ";$bin"

Then sign in:

claude auth login

Complete the browser sign-in and return any code requested by PowerShell. If the browser does not open, open the printed URL yourself.

npm i -g @openai/codex
codex login

npm install -g opencode-ai

opencode auth login

opencode serve --port 4096

After signing in, run cabane status in the PowerShell window where you ran setup. 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

Interactive setup has already started the Companion in the background. Keep Windows awake and online. On native Windows, the Companion has no service, start-at-login or automatic update path.

After Windows restarts, open PowerShell and run:

cabane start
cabane status

If you use OpenCode, also run opencode serve --port 4096 in a separate PowerShell window and keep that window open.

To update the Companion, wait until no agent is working, then run in PowerShell:

cabane stop
cabane update
cabane start

Stop, pause or remove

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

cabane logout clears pairing credentials while keeping 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 computer a team shares. Agent access compares the levels.

• A harness sandbox. Follow Harness sandboxes to configure the restrictions you want. Codex supports native Windows sandboxing; Claude Code's sandbox needs WSL 2. If you keep WSL's default mounts, Windows files remain reachable.
• A dedicated WSL environment. Agents work in a new Ubuntu distribution that sees only one Windows folder. Follow the recipe below instead of steps 1 to 3.
• Docker Desktop. Use Linux containers and, from a WSL shell, follow the Docker environment recipe, including its pairing and sign-in steps.

Dedicated WSL environment

You need Windows with WSL 2 support and permission to install WSL. This recipe installs a new Ubuntu distribution dedicated to Cabane. If you already have an Ubuntu distribution with personal work in it, use Docker Desktop instead of changing that distribution.

Prepare the distribution

In PowerShell as administrator, install Ubuntu:

wsl --install -d Ubuntu

Restart Windows if requested, open Ubuntu, and create its Linux user account. In Windows File Explorer, create C:\cabane-work for the files you want agents to use.

In the Ubuntu shell, create a mount point for that folder and open WSL's configuration:

sudo mkdir -p /work
sudo nano /etc/wsl.conf

Merge these settings into /etc/wsl.conf. Keep unrelated settings and avoid duplicate sections:

[boot]
systemd=true

[automount]
enabled=false
mountFsTab=true

[interop]
enabled=false
appendWindowsPath=false

Save and exit. Still in Ubuntu, open the mount table:

sudo nano /etc/fstab

Add this line, then save and exit:

C:\cabane-work /work drvfs defaults 0 0

Save work in every WSL distribution before continuing: the next command stops all of them. In PowerShell, shut WSL down and reopen Ubuntu:

wsl --shutdown
wsl -d Ubuntu

In Ubuntu, confirm that /work contains the files from C:\cabane-work and that /mnt/c is not mounted. Edits in /work persist in your Windows folder. These settings limit default access; a process with Linux administrative permission can mount Windows drives again. See Microsoft's WSL configuration reference for the settings.

Pair the distribution

Open the workspace's Settings → Devices → Set up a new device in Cabane. Copy the line under In WSL · With the installer, not the npm line above it, and run it in the dedicated Ubuntu shell:

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

The installer supplies Node and the Companion under ~/.cabane and runs cabane setup, which prints a code; enter it in the dialog and choose Confirm. Follow any PATH instruction the installer prints. 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. Run cabane status in the Ubuntu shell; Needs sign-in is expected until you sign in.

Sign in inside Ubuntu

Install and sign in from the Ubuntu shell. Signing in on Windows does not sign you in inside Ubuntu. With WSL interop disabled, Ubuntu cannot open your Windows browser: open each printed sign-in URL yourself in your Windows 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 distribution running

Install the Companion's service in the Ubuntu shell:

cabane service install
cabane service status

The service enables automatic updates, which can restart the Companion during a turn. If cabane service install asks you to enable linger, run sudo loginctl enable-linger "$USER" in Ubuntu.

Keep an Ubuntu terminal open and Windows awake and online. Systemd services do not keep WSL running.

After Windows restarts, open Ubuntu from PowerShell:

wsl -d Ubuntu

In Ubuntu, check cabane service status and run cabane start if the Companion is stopped. If you use OpenCode, open a separate Ubuntu terminal and run opencode serve --port 4096 again. If you run the Companion without its service, use cabane update in Ubuntu when no agent is working.

To stop or disconnect, run the commands in Stop, pause or remove in the Ubuntu shell. There, cabane service uninstall also disables automatic startup.

Back to Quick start

Return to Quick start: check the device.