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

# Installation

> Every way to install Crew — desktop app, one-line wheel, source build, Docker. Runs on macOS, Linux, and Windows.

Crew ships as a Python package that bundles the React dashboard. There are four ways to install it — pick whichever fits how you'll run it. All builds are driven by plain `pip` + `npm`/Vite + `pytest`. No proprietary tooling.

## Prerequisites

| Requirement | Needed for | Notes |
|-------------|------------|-------|
| Python 3.10+ | Backend runtime | 3.12 recommended |
| Node.js 18+ | Building the dashboard from source | Not needed for the prebuilt wheel, desktop app, or Docker image |
| kiro-cli | Talking to the LLM | Installed via the dashboard or Mac app on first launch |

Crew drives an LLM through `kiro-cli` over the [Agent Client Protocol](https://github.com/zed-industries/agent-client-protocol). It is the only provider (`agent.provider = acp`). The first desktop or dashboard launch can install Kiro CLI on the Gateway host and guide device-code sign-in before chat opens. `kirocrew doctor` reports whether the binary is found and logged in.

Semantic memory needs no setup. Embeddings run in-process and the Gateway downloads its embedding model (~610 MB) in the background on first start, verifies it, and stores it under `~/.kiro/crew/models`. Until the model lands, memory search falls back to keyword matching and picks up embeddings automatically without a restart. Set `KIROCREW_EMBED_MODEL_URL` to point at a mirror for airgapped installs.

## Choose an installer

    Desktop app
    One-line wheel
    From source
    Docker

[Download Crew](https://kiro.dev/downloads) for macOS (signed `.dmg`) or Linux (`.AppImage`). The app starts a bundled Gateway when no local Gateway is already running, and agent sessions and ACP processes then run on demand on the same machine. It can connect to a remote Gateway over an SSH tunnel instead. On Windows, run the Gateway from a native source install and open the dashboard in your browser.

You can also build the app yourself with `make desktop`.

The fastest path — installs a prebuilt, SHA-256-verified wheel from the release CDN.

```bash
# Stable channel (the default)
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh

# Or track a faster channel: insider or nightly
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --channel insider

# Pin an exact version
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --version 0.1.0
```

The installer resolves the channel feed, verifies the wheel's SHA-256 against the published manifest, installs through `pipx` when available or a managed venv at `~/.kiro/crew/venv`, and records the channel in `~/.kiro/crew/channel`. The channels are `stable`, `insider`, and `nightly`, and `KIROCREW_CHANNEL` sets the default.

You can also install one exact wheel directly with its published SHA-256:

```bash
pip install "https://download.crew.kiro.dev/cli/nightly/0.1.0.dev20260718/kirocrew-0.1.0.dev20260718-py3-none-any.whl#sha256=2109dd186da999a1f135b4d6da2b36110d6a943e0af229ec259c25f72b73e570"
```

For contributors or when you want the latest code. Requires Python 3.10+, Node.js 18+, and npm.

```bash
git clone https://github.com/kirodotdev/KiroCrew
cd Crew
make build
source .venv/bin/activate
```

`make build` runs two steps: builds the frontend (npm/Vite → `website/dist` → `src/kiro_crew/static/dist`) and installs the backend into a local `.venv`. Both `kirocrew` and `kirocrew-browse` are installed onto your `PATH`.

The gateway ships as a multi-arch image on GHCR — the recommended way to run Crew 24/7 on a server or NAS.

```bash
docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  ghcr.io/kirodotdev/kirocrew:stable
```

First run needs two one-time steps:

```bash
docker exec -it kirocrew kiro-cli login          # sign in the agent runtime
docker exec kirocrew kirocrew token --ttl 2h     # mint a dashboard login link
```

Open the printed link, substituting the host you reach the container on. Available tags: `stable`, `insider`, `nightly`, plus pinned versions like `0.1.0`. Version tags are immutable — pin one for reproducible deployments. See the Docker section of [Running 24/7](https://kiro.dev/docs/crew/running-24-7.md) for the full container security model.

## Windows

Crew supports Windows natively. Use CPython 3.12 + a venv + `pip install -e . tzdata`, and launch with `python -m kiro_crew gateway`.

```powershell
py -3.12 -m venv .venv
.venv\Scripts\activate
pip install -e . tzdata
python -m kiro_crew gateway
```

All POSIX-only process, signal, file-lock, and metrics calls are routed through `kiro_crew.platform_compat`. The OS-level sandbox (Linux namespaces / macOS Seatbelt) is not available on Windows; every other feature works. The interactive web-terminal and the SSO-login PTY degrade to a clear "not supported on Windows" response rather than crashing.

## Configure and verify

For the one-line wheel, source build, and Docker installs, set up and verify after installing:

```bash
kirocrew setup            # interactive wizard: data dir, agent, credentials
kirocrew doctor           # verify everything is wired up
kirocrew gateway          # start the server → http://localhost:5476
```

`kirocrew doctor` reports the status of the `kiro-cli` binary, its authentication, Ollama/embeddings, Slack tokens, config validity, and MCP servers.

**ℹ️ Info:** The desktop app handles this automatically — it starts a bundled Gateway on launch and guides kiro-cli installation and sign-in from the app itself. These steps are only needed for the CLI-based install paths.

## Data home

All persistent state lives under `~/.kiro/crew/` (override with `KIROCREW_HOME`):

```
~/.kiro/crew/
├── config.json          # user configuration
├── .env                 # Slack tokens, owner ID, other credentials
├── workspace/
│   ├── memory/          # preferences.md, projects.md, history/
│   ├── lessons.jsonl    # learned corrections
│   └── knowledge/       # ingested documents (FTS5 + vectors)
├── conversations/       # JSONL session logs
├── crons.json           # scheduled jobs
├── audit.log            # bash command audit trail
└── agents/              # generated kiro-cli agent configs
```

## Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `KIROCREW_HOME` | `~/.kiro/crew` | Data directory (config, credentials, databases) |
| `KIROCREW_PORT` | `5476` | Port the gateway binds to |
| `KIROCREW_EMBED_MODEL_URL` | (CDN) | Override the embedding-model download URL (for mirrors) |

Both `KIROCREW_HOME` and `KIROCREW_PORT` are validated at CLI entry, not stored as config keys. Pass `--port` on the CLI to override the env var per-invocation.

## Optional extras

Install with `pip install "kirocrew[<extra>]"`:

| Extra | Adds |
|-------|------|
| `voice` | `boto3`, `amazon-transcribe` for cloud speech-to-text |
| `aws` | `boto3` for AWS integrations |

Piper TTS is the default text-to-speech provider and runs locally — no extra install needed.