---
title: "Installation and setup"
description: "Install open·kritt, configure one model-access option, and start the stack."
---

open·kritt runs locally with Docker Compose. The repository includes `./kritt`, an
interactive CLI that creates the environment file, guides model access setup, and starts
the stack. It does not need an npm install step.

## Prerequisites

- [Docker Desktop](https://www.docker.com/products/docker-desktop/), or Docker Engine with
  the Docker Compose plugin
- Git
- Node.js 20 or newer for the repository-local CLI

The manual Docker path does not use host Node.js. This is useful on distributions whose
default package repository still provides Node 16 or 18.

### Tested Linux matrix

The full source build, five long-running services (plus the one-shot runner-image helper),
and scan startup have been exercised on each of these Linux combinations:

| Distribution | x86_64 | ARM64 | Startup paths checked |
| --- | --- | --- | --- |
| Ubuntu 24.04 | Yes | Yes | `./kritt start`, manual Compose |
| Debian 12 | Yes | Yes | manual Compose, development overlay |
| Rocky Linux 9 | Yes | Yes | `./kritt start`, manual Compose with SELinux Enforcing |

Docker Desktop remains the normal macOS/Windows development path, but it was not part of
that Linux cloud matrix. Images are built for the host architecture; no amd64 emulation is
required on the tested ARM64 hosts.

### Install Node.js 20+

Check the version before running the CLI:

```bash
node --version
```

On Ubuntu 24.04 or Debian 12, the distribution default may be older than Node 20. One
repeatable option is the NodeSource 22.x repository:

```bash
sudo apt-get update
sudo apt-get install -y ca-certificates curl
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version
```

On Rocky Linux 9, select a current AppStream rather than installing its default stream:

```bash
sudo dnf module reset -y nodejs
sudo dnf module enable -y nodejs:20
sudo dnf install -y nodejs
node --version
```

If your distribution does not offer a suitable stream, use a Node version manager or skip
the CLI and follow [Manual Docker setup](#manual-docker-setup).

On Linux, verify Docker access before setup. Both commands must succeed as your regular
user:

```bash
docker info >/dev/null
docker compose version
```

If Docker requires `sudo`, configure [non-root Docker access](https://docs.docker.com/engine/install/linux-postinstall/)
or use [rootless Docker](https://docs.docker.com/engine/security/rootless/) before running
the open·kritt CLI.

<Warning>
  On Linux, run `./kritt` as your regular user, not with `sudo`. The guided Codex login and
  CLI import preserve the host user's ownership of `auth.json`. See
  [Linux ownership and permissions](/ai-provider-setup/codex#linux-ownership-and-permissions)
  if an older installation created the credential as `root`.
</Warning>

<Warning>
  Tool-enabled scan agents run as root inside disposable nested containers, with writable
  repository copies and direct internet access. The engine controls the Docker daemon to
  create those jobs. Use a dedicated Docker host or VM for untrusted targets; do not run
  open·kritt beside unrelated sensitive workloads.
</Warning>

## Install and launch

<Steps>
  <Step title="Clone the repository">
    ```bash
    git clone https://github.com/Kritt-ai/open-kritt && cd open-kritt
    ```
  </Step>
  <Step title="Open the CLI">
    ```bash
    ./kritt
    ```
    Use the Arrow keys to select **Setup**, press Enter, and follow the prompts. The CLI
    creates `.env` from `.env.example` when it does not exist.
  </Step>
  <Step title="Configure model access">
    Choose one model-access method. The recommended path is the guided Codex login; a
    provider API key works too. Follow the [AI provider setup guides](/ai-provider-setup/overview)
    for account, key, billing, and verification steps. A GitHub token is optional and only
    needed for private GitHub repositories.
  </Step>
  <Step title="Start open·kritt">
    Choose **Start** in the menu, or run:
    ```bash
    ./kritt start
    ```
    The command runs `docker compose up --build` and stays attached to the stack. Press
    Ctrl+C to stop it.
  </Step>
</Steps>

<Frame caption="The repository-local CLI opens directly into the interactive menu.">
  <img src="/images/cli.png" alt="open·kritt interactive CLI home screen" />
</Frame>

After startup, open [http://localhost:5173](http://localhost:5173). The backend health
endpoint is available at [http://localhost:3002/api/health](http://localhost:3002/api/health).

## Configure model access

You need **one** of the following options to create scans:

| Option | When to use it |
| --- | --- |
| [**Codex login**](/ai-provider-setup/codex) (recommended) | Use eligible ChatGPT/Codex subscription access through the guided device flow. |
| [`OPENAI_API_KEY`](/ai-provider-setup/codex) | Use an OpenAI Platform API key with the Codex harness. |
| [`CODEX_API_KEY`](/ai-provider-setup/codex) | Use the same kind of OpenAI Platform key as a direct Codex execution override. |
| [`ANTHROPIC_API_KEY`](/ai-provider-setup/claude-code) | Use Claude Code with Anthropic API billing. |
| [`OPENROUTER_API_KEY`](/ai-provider-setup/openrouter) | Route a compatible model through OpenRouter. |

`GITHUB_TOKEN` is separate from model access. Add it only when the scan needs to clone a
private GitHub repository or dependency.

The setup screen shows which options are present, lets you set, replace, unset, or learn
about them, and never prints credential values.

<Frame caption="Setup makes the recommended Codex login and optional provider credentials easy to inspect.">
  <img src="/images/cli-setup.png" alt="open·kritt CLI setup screen showing credential status" />
</Frame>

For detailed instructions, choose the [Codex](/ai-provider-setup/codex),
[Claude Code](/ai-provider-setup/claude-code), or
[OpenRouter](/ai-provider-setup/openrouter) guide. The guides explain where to obtain the
credential, how it is billed, which harness it enables, and how to verify it.

## CLI commands

| Command | Purpose |
| --- | --- |
| `./kritt` | Open the full-screen interactive menu. Arrow keys navigate, Enter selects, and Esc or Ctrl+C exits. |
| `./kritt setup` | Create `.env` when needed and configure model access or the optional GitHub token. |
| `./kritt start` | Check setup, then run `docker compose up --build`. Ctrl+C stops the attached stack. |
| `./kritt help` | Show command guidance. Use `./kritt help setup` or `./kritt help start` for a specific command. |

## Manual Docker setup

The CLI is the recommended path. To configure the stack manually with an API key instead:

```bash
cp .env.example .env
chmod 600 .env
# Set one provider credential in .env: OPENAI_API_KEY, CODEX_API_KEY,
# ANTHROPIC_API_KEY, or OPENROUTER_API_KEY.
mkdir -p .data/codex
chmod 700 .data/codex
docker compose up --build
```

## Optional demo data

Once the stack is running, load sample workflows, scans, and findings to explore the UI:

```bash
docker compose exec backend npm run seed
```

The demo seed is additive and idempotent. It preserves existing workflows, scans,
findings, post-scripts, and triage data, and skips demo records that already exist.

Next: review [AI provider setup](/ai-provider-setup/overview), then build
[your first workflow](/first-scan/workflow).