> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kanaeru.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a machine

> Install the Agent Manager on your computer, or use a cloud machine, so Kana sessions have somewhere to run.

Kana sessions run on **agent machines**. An agent machine is any computer running the **Agent Manager**, a background service that starts coding agents, gives each task its own Git worktree, and reports back to Kanaeru. The `kana` CLI is installed alongside it.

Every machine belongs to one person. Teammates can still share a session: each person's turns run on their own machines. See [Sessions that move](/concepts/sessions).

<Note>
  In the closed beta, Kanaeru gives you a [cloud machine](#cloud-machines) and you don't install anything. Installing the Agent Manager on your own computer, as described below, is for accounts that have it turned on.
</Note>

## Supported platforms

| Platform | Installer target |
| - | - |
| macOS on Apple Silicon | **macOS Terminal** |
| Linux x64 (including WSL) | **Linux / WSL** |
| Windows x64 | **Windows PowerShell** (outside WSL) |
| Any Linux host with Docker | **Docker Engine (Linux)** |

On Linux and WSL, agents run inside a bubblewrap sandbox, so the installer needs `bubblewrap` at `/usr/bin/bwrap`. On native Windows there's no built-in sandbox, so agents only start if you declare the host isolated or turn the sandbox off. See [Sandboxing](/machines/sandboxing#where-the-sandbox-runs).

## Install

<Steps>
  <Step title="Open the machine page">
    In the chat box, open the runtime selector and choose **Connect**, or go straight to `/machine-connect`. The page is called **Connect an agent machine**, and it's also a step during onboarding.

    At the top, choose **New computer** to install on a computer for the first time, or **Already installed** to update and reconnect one you set up before. Then pick the installer target for that computer.
  </Step>

  <Step title="Choose runtimes">
    Tick the [runtimes](/machines/runtimes) to install, such as Claude Code and Codex. You can optionally paste provider API keys. They're only inserted into the generated command and are stored locally by the Agent Manager on that computer.
  </Step>

  <Step title="Run the command">
    Choose **Copy command** (or **Download installer**) and run it on the target computer.

    <Tabs>
      <Tab title="macOS / Linux">
        The command downloads `install.sh` and runs it with your connect URL, the workspace directory (`$HOME/kanaeru`), and your runtimes.
      </Tab>

      <Tab title="Windows">
        The command downloads `install.ps1` with `irm` and runs it with your connect URL, the workspace directory (`%USERPROFILE%\kanaeru`), and your runtimes.
      </Tab>

      <Tab title="Docker">
        The command loads the Agent Manager image and runs it as a container named `kanaeru-agent-manager` with host networking, persistent volumes for its state and for the Claude Code and Codex sign-ins, and your workspace directory (by default `~/kanaeru-workspaces`) mounted at `/workspace`.
      </Tab>
    </Tabs>

    Download links in the command are signed and expire after an hour, so copy a fresh command if one stops working. The computer doesn't need access to Kanaeru's source.
  </Step>

  <Step title="Wait for Machine ready">
    The machine page refreshes on its own. When the machine connects, it shows **Machine ready** with a check for each runtime: **Ready**, or **Needs setup** with what's missing.

    Each runtime also lists its **Kanaeru harness bundles**, the [session plugins](/machines/session-plugins) it runs with. **Machine access** shows whether the Kana CLI and Kanaeru's agent tools can reach your account from this machine. If the CLI isn't signed in, choose **Set up Kana CLI**.
  </Step>
</Steps>

On macOS and Linux, the installer puts `kanaeru-agent-manager`, `kanaeru-agent-manager-daemon`, and `kana` in `~/.local/bin`. On macOS it registers a launchd agent for your user, and logs are written to `~/.kanaeru/logs/agent-manager.stdout.log`. On Linux it doesn't register a background service yet, so start `kanaeru-agent-manager` yourself. On Windows, the installer adds `kanaeru-agent-manager.cmd` and `kana.cmd` to `%USERPROFILE%\.local\bin` and registers a scheduled task named `KanaeruAgentManager` that starts when you sign in.

## Sign in to runtimes

Each runtime needs credentials for its model provider. You can provide them in four ways:

* **API keys in the install command.** Paste them in the Providers section before copying the command.
* **Provider credentials panel.** On the machine page, save one or more named accounts per provider.
* **Sign in on the machine.** For **Sign in with ChatGPT** (Codex), AWS SSO (Claude Code on Bedrock), and **Sign in with Google** (Antigravity), the token is created and refreshed on the machine and never passes through Kanaeru.
* **Logins you already have.** The Agent Manager detects runtimes that are already installed and picks up their existing sign-ins, such as your `claude` login, your Codex sign-in, and your Copilot login. If a runtime already works on that computer, there's nothing more to do.

See [Runtimes](/machines/runtimes) for which providers each runtime accepts.

## Upgrade

From the machine page, choose **Upgrade agent manager**. Tick **Also update runtimes** to upgrade the coding agents too. Upgrades wait until the machine is idle before restarting. Turn on **Auto-update** to keep the machine current without asking.

To reinstall from scratch, choose **Reinstall agent manager & runtimes**. On a computer that's already installed, switch the page to **Already installed** to get an update-and-reconnect command.

## Cloud machines

Your invite may include a **cloud machine**, a managed machine that Kanaeru runs for you. It appears on the machine page as **Cloud machine** with its CPU and memory.

* It sleeps after a period of idleness (30 minutes by default) so it stops costing compute, and wakes in about a minute when you send it work. Choose **Wake** to start it early.
* If it gets into a bad state, **Recover machine** rebuilds it on the same workspace, so your files are kept.

Some invites provide only a cloud machine. In that case the install controls are turned off and the machine page shows that your machine is set up for you.

A cloud machine still needs your provider access before its runtimes can work. Select the machine, choose **Wake** if it's asleep, and add an account for each runtime in **Provider credentials**. Each runtime you've given access shows **Ready** under **Runtime checks**. Once at least one is ready, you can start working with Kana.

## Capacity

The Agent Manager decides how many agents a machine runs at once from its memory and CPU. That's typically 2 to 4 on a small machine, 8 on a 4-core machine with 8 GB, and up to 15 on larger ones. When every machine that could run a session stays busy for about a minute, the session doesn't start: Kana tells you every machine was busy, and you send a message again once one frees up. See [Sandboxing and capacity](/machines/sandboxing#capacity) to change the limit.


## Related topics

- [Settings and profile](/guides/settings.md)
- [Kana CLI](/cli/overview.md)
- [Kanaeru overview](/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.