# Installing komrad

Get up and running with the komrad binary.

Komrad is one binary. The same binary runs the panel and the server.

The panel runs on your machine. It renders the view of komrad’s state in your terminal, and wraps around existing CLI tools like Claude or Codex.

The server runs your agents and records their activity in Postgres, so you can search chat history, spawn several agents at once, or have them communicate. The server, along with its database and agents, makes up an _engine_. Komrad’s engines can run on your laptop or on a remote machine, and one panel can connect to different engines.

## Quick start

Komrad runs its agents in tmux, so install tmux 3.3 or newer first. Then run the install script.

```sh
curl -fsSL https://github.com/harrisoncramer/komrad/releases/latest/download/install.sh | sh
```

Run [`komrad open`](https://komrad.dev/latest/cli/open.md) to open the panel.

To install the `tip` release, set `KOMRAD_VERSION=tip` on the `sh` side of the pipe. The `KOMRAD_VERSION` value also takes a release tag such as `v0.3.0`. You can use `KOMRAD_INSTALL_DIR` to pick a directory other than `~/.local/bin`.

```sh
curl -fsSL https://github.com/harrisoncramer/komrad/releases/download/tip/install.sh | KOMRAD_VERSION=tip sh
```

## Manual installation

The install script downloads the binary, checks it and runs setup. To do each step yourself, follow this section.

> Having trouble?
> 
> Run [`komrad doctor`](https://komrad.dev/latest/cli/doctor.md) to check for configuration or installation issues.

### Install the binary

```sh
mkdir -p ~/.local/bin
curl -fsSL -o ~/.local/bin/komrad https://github.com/harrisoncramer/komrad/releases/latest/download/komrad-darwin-arm64
chmod +x ~/.local/bin/komrad
```

Swap `darwin-arm64` for your platform: `darwin-amd64`, `linux-amd64` or `linux-arm64`.

This installs the newest stable release. Each release has a version number and a changelog on the [releases page](https://github.com/harrisoncramer/komrad/releases).

### Check the download

Every release carries a `checksums.txt` file. Compare the binary against it.

```sh
expected="$(curl -fsSL https://github.com/harrisoncramer/komrad/releases/latest/download/checksums.txt |
  awk '$2 == "komrad-darwin-arm64" {print $1}')"
echo "$expected  $HOME/.local/bin/komrad" | shasum -a 256 --check
```

The checksums come from the same place as the binary, so they catch a corrupted download, not a compromised release.

### Install tip instead

The `tip` release is rebuilt from main on every merge. It has the newest changes and doesn’t make a version promise.

```sh
mkdir -p ~/.local/bin
curl -fsSL -o ~/.local/bin/komrad https://github.com/harrisoncramer/komrad/releases/download/tip/komrad-darwin-arm64
chmod +x ~/.local/bin/komrad
```

### Build with more languages

Release binaries highlight a core set of languages and show a file in any other language as plain text. To highlight more, build komrad from source and add the grammars you need to the core set by their nvim-treesitter names. The [contributing guide](https://github.com/harrisoncramer/komrad/blob/main/CONTRIBUTING.md#building) covers the other `--grammars` options.

```sh
git clone https://github.com/harrisoncramer/komrad.git
cd komrad
mise install
mise run go:build --grammars core,ocaml
cp bin/komrad ~/.local/bin/komrad
```

### Run setup

Run [`komrad setup`](https://komrad.dev/latest/cli/setup.md) once the binary is on your PATH. It walks through the machine one step at a time. To set the machine up by hand instead, follow the rest of this section.

### Create your database

Every release binary carries an embedded Postgres, so you do not need to install or run it yourself. Komrad keeps its database there while [`database_url`](https://komrad.dev/latest/config.md#connection.database_url) is left empty. Run [`komrad setup`](https://komrad.dev/latest/cli/setup.md), and komrad creates the database and an engine named `default` under your state directory.

```sh
komrad setup --no-input
```

After a restart, [`komrad start`](https://komrad.dev/latest/cli/start.md) or [`komrad open`](https://komrad.dev/latest/cli/open.md) brings the embedded Postgres back up. While the server runs, it starts the embedded Postgres again whenever it exits.

The embedded Postgres needs only the C library. It runs on Linux with glibc 2.28 or newer, such as Debian 10, Ubuntu 20.04 or RHEL 8, and on macOS 12 or newer. It runs under any login except root. On any other machine, such as one running Alpine, keep the database in a Postgres you already run.

### Use a Postgres you already run

You can keep the database yourself instead, for example in Docker.

```sh
docker run --name komrad \
	-e POSTGRES_USER=komrad_owner \
	-e POSTGRES_PASSWORD=password123 \
	-e POSTGRES_DB=komrad \
	-p 5432:5432 \
	-v komrad_data:/var/lib/postgresql \
	-d postgres:18
```

Postgres takes a few seconds to start. Wait until `docker exec komrad pg_isready -h localhost` reports that it is accepting connections before moving on.

The database needs one admin-like user. The komrad engine uses this user to run migrations each time you update your binary. Run [`komrad setup`](https://komrad.dev/latest/cli/setup.md) with `--no-embedded-postgres` and paste this user’s URL, or pass it as `--owner-database-url`. To do the same by hand, provide the URL to the [`komrad migrate`](https://komrad.dev/latest/cli/migrate.md) command and create your first engine. The engine is named `default` here.

```sh
export KOMRAD_OWNER_DATABASE_URL=postgres://komrad_owner:password123@localhost:5432/komrad
komrad migrate
komrad engine ensure default
```

Several engines can share one database, so multiple developers can share a Postgres database, or one developer can spread their workload across machines.

### Write the config

Komrad’s configuration is stored in a TOML file. Setup writes this file for you when there is none. This section is for a Postgres you set up by hand, or a config file you already have.

The [`komrad engine ensure`](https://komrad.dev/latest/cli/engine/ensure.md) command prints an initial [`[connection]`](https://komrad.dev/latest/config.md#connection) block with a login for the engine. Run it, put the engine block in `~/.config/komrad/config.toml`, and add the owner URL from the previous step beside it.

```toml
[connection]
owner_database_url = "postgres://komrad_owner:password123@localhost:5432/komrad"
database_url = "postgres://komrad_engine_default:8f3a1c9e2b7d4e6f@localhost:5432/komrad"
```

Only [`komrad migrate`](https://komrad.dev/latest/cli/migrate.md), [`komrad engine ensure`](https://komrad.dev/latest/cli/engine/ensure.md), [`komrad engine grant`](https://komrad.dev/latest/cli/engine/grant.md) and [`komrad engine revoke`](https://komrad.dev/latest/cli/engine/revoke.md) use the [`owner_database_url`](https://komrad.dev/latest/config.md#connection.owner_database_url). The server itself connects with [`database_url`](https://komrad.dev/latest/config.md#connection.database_url).

To keep a whole URL out of the file, export `KOMRAD_DATABASE_URL`, `KOMRAD_OWNER_DATABASE_URL` or `KOMRAD_READONLY_DATABASE_URL` and leave the setting out. Each variable takes the place of its setting, as `KOMRAD_OWNER_DATABASE_URL` did for [`komrad migrate`](https://komrad.dev/latest/cli/migrate.md) above.

To keep only the passwords out, write each one as `${NAME}`. Komrad reads it from that environment variable when it reads the config:

```toml
[connection]
owner_database_url = "postgres://komrad_owner:${KOMRAD_OWNER_PASSWORD}@localhost:5432/komrad"
database_url = "postgres://komrad_engine_default:${KOMRAD_ENGINE_PASSWORD}@localhost:5432/komrad"
readonly_database_url = "postgres://komrad_engine_default_reader:${KOMRAD_ENGINE_PASSWORD}@localhost:5432/komrad"
```

A collector’s API key reads the same way, in a value under [`headers`](https://komrad.dev/latest/config.md#log.export.headers):

```toml
[log.export]
endpoint = "https://api.honeycomb.io"
headers = { "x-honeycomb-team" = "${HONEYCOMB_API_KEY}" }
```

Those four settings read `${NAME}`, and no others. Komrad refuses the config when one of them names a variable that isn’t set, or when any other setting holds a `${NAME}`.

### Open the panel

Komrad runs every agent in a tmux server of its own, so tmux must be installed. Using tmux yourself is optional.

Run [`komrad open`](https://komrad.dev/latest/cli/open.md) to open the panel. The first open starts the server in the background, and the embedded Postgres too if you use it.

![The komrad panel on first run, welcoming you and asking you to press space then w to set up your first workflow.](https://komrad.dev/media/komrad-open.png)

## Connecting a forge

Komrad can push or pull data from your forge, such as GitHub or GitLab, only after you connect it. Connect a forge once with the [`komrad forge connect`](https://komrad.dev/latest/cli/forge/connect.md) command.

### GitHub

On your laptop, the simplest way is to hand komrad the token the GitHub CLI already holds.

```sh
gh auth token | komrad forge connect github.com
```

Any personal access token works the same way, as long as it can read the pull requests of your repositories. For GitHub Enterprise, add `--kind github` and, if needed, `--api-url`.

To connect a GitHub App, set it up in [`[github_app]`](https://komrad.dev/latest/config.md#github_app) and connect it with `--method github-app`. Komrad makes a token from the App, which expires after an hour, and makes a new one whenever it needs to.

```sh
komrad forge connect github.com --method github-app
```

### GitLab

GitLab takes a personal access token with the `api` scope. GitLab workflows run on a local engine.

```sh
komrad forge connect gitlab.com --token-file ~/.config/gitlab-token
komrad forge connect gitlab.example.com --kind gitlab --token-file ~/.config/gitlab-token
```

GitLab has no App to make short-lived tokens from. On a machine other people can reach, connect with `--method rotating-token` so the token komrad holds does not live forever. Komrad swaps the token for a new one as soon as you connect, so the one you pasted stops working at once.

Use [`komrad forge disconnect`](https://komrad.dev/latest/cli/forge/disconnect.md) to revoke the current token with GitLab before you forget it.

```sh
komrad forge connect gitlab.com --method rotating-token --token-file ~/.config/gitlab-token
```

If a rotation is ever refused, the connection shows as refused in [`komrad forge list`](https://komrad.dev/latest/cli/forge/list.md). Connect it again with a fresh token.

### Self-Hosting

A self-hosted forge needs two more things.

Komrad cannot tell from a host’s name which forge it runs, so pass `--kind github` or `--kind gitlab`. If its API is somewhere other than `https://<host>/api/v3` for GitHub or `https://<host>/api/v4` for GitLab, pass `--api-url` as well.

Some hosts take SSH paths like `ssh.gitlab.example.com`. List each pair in [`ssh_hosts`](https://komrad.dev/latest/config.md#git.ssh_hosts) so a remote on the SSH name finds the connection for the web host. Public names such as `ssh.github.com` and `altssh.gitlab.com` are already known.

## Upgrading

Run the install script again or download the new binary over the old one, then stop the server and migrate. The install script skips setup when it replaces a binary.

```sh
komrad stop
komrad migrate
```

A running server keeps its old build until you stop it. Open the panel again and it starts the new build. The embedded Postgres keeps running through [`komrad stop`](https://komrad.dev/latest/cli/stop.md), so [`komrad migrate`](https://komrad.dev/latest/cli/migrate.md) can still reach it. The next [`komrad open`](https://komrad.dev/latest/cli/open.md) or [`komrad start`](https://komrad.dev/latest/cli/start.md) restarts the embedded Postgres on the programs the new build carries. Agents keep running throughout, because they live in tmux, not in the server.

## Running the panel inside tmux

The panel is a terminal application, so it runs inside tmux without a problem.

If your own tmux prefix is `ctrl+space`, give your tmux a different one, because the panel keeps its own keys behind it.
