# Windows setup

Install the Companion in PowerShell and keep it running, or give agents a dedicated Ubuntu environment in WSL.

Last updated 5 November 2026

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](#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.

## 1. Pair it

If you do not have a Cabane workspace yet, [create it first](https://cabane.ai/docs/quick-start#2-create-the-workspace). 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**:

```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.

## 2. Sign 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](#sign-in-inside-ubuntu) instead.

**Claude Code:** use its [PowerShell installer](https://code.claude.com/docs/en/setup):

```powershell
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:

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

Then sign in:

```powershell
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.

> **Details: Codex instead**
>
> Run in **PowerShell**:
>
> ```powershell
> npm i -g @openai/codex
> codex login
> ```
>
> Complete the sign-in in your browser.

> **Details: OpenCode instead**
>
> Use its [npm installation for Windows](https://opencode.ai/docs/#install) in **PowerShell**:
>
> ```powershell
> npm install -g opencode-ai
> ```
>
> Open a **separate PowerShell window** and sign in there:
>
> ```powershell
> opencode auth login
> ```
>
> Choose your provider and follow its credential instructions. Setup's printed lines don't include this sign-in. Then start the server in that separate window:
>
> ```powershell
> opencode serve --port 4096
> ```
>
> Keep that window open while using OpenCode. The Companion does not supervise this server; use the [Docker recipe](https://cabane.ai/docs/server-and-vps-setup#docker-environment) for supervised, unattended OpenCode.

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](https://cabane.ai/docs/faq-and-help#can-i-sign-in-on-a-machine-with-no-browser) and [when to use a token](https://cabane.ai/docs/faq-and-help#when-should-i-use-a-token-instead-of-signing-in).

## 3. Keep 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:

```powershell
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**:

```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](https://cabane.ai/docs/devices#deactivate-rotate-the-token-remove).

## 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](https://cabane.ai/docs/agent-access) compares the levels.

- **A harness sandbox.** Follow [Harness sandboxes](https://cabane.ai/docs/harness-sandboxes) to configure the restrictions you want. Codex supports [native Windows sandboxing](https://learn.chatgpt.com/docs/windows/windows-sandbox); 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](https://cabane.ai/docs/server-and-vps-setup#docker-environment), including its pairing and sign-in steps.

## Dedicated WSL environment

Figure: Agents run in a dedicated WSL Ubuntu environment, with one Windows work folder mounted at /work

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:

```powershell
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:

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

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

```ini
[boot]
systemd=true

[automount]
enabled=false
mountFsTab=true

[interop]
enabled=false
appendWindowsPath=false
```

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

```sh
sudo nano /etc/fstab
```

Add this line, then save and exit:

```text
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:

```powershell
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](https://learn.microsoft.com/en-us/windows/wsl/wsl-config) 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**:

```sh
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:**

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

> **Details: Codex instead**
>
> Use the Node installation supplied by the Companion:
>
> ```sh
> export PATH="$HOME/.cabane/node/bin:$PATH"
> npm i -g @openai/codex
> codex login --device-auth
> ```
>
> Use `--device-auth` inside Ubuntu even if setup prints plain `codex login`. Follow the printed URL's code instructions. Device authentication must be enabled for your ChatGPT account or workspace.

> **Details: OpenCode instead**
>
> Install OpenCode in the **Ubuntu shell**:
>
> ```sh
> curl -fsSL https://opencode.ai/install | bash
> ```
>
> Open a separate **PowerShell window** and run `wsl -d Ubuntu` to get a new Ubuntu shell with the updated PATH. In that **new Ubuntu shell**, run:
>
> ```sh
> opencode auth login
> ```
>
> Choose your provider and follow its credential instructions. Then run the server in this separate Ubuntu terminal:
>
> ```sh
> opencode serve --port 4096
> ```
>
> Keep this terminal open while using OpenCode. The Companion does not supervise this server.

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**:

```sh
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](https://learn.microsoft.com/en-us/windows/wsl/systemd/).

After Windows restarts, open Ubuntu from **PowerShell**:

```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](#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](https://cabane.ai/docs/quick-start#5-check-the-device).