Install

Koda is Docker-first. A single command brings up the full stack — web dashboard, control plane, Postgres, object storage, and the runtime services that supervise agent execution. The npm CLI handles staging, bootstrap, and diagnostics so you can move from zero to a dashboard setup page in minutes.

Prerequisites

Koda targets Linux and macOS hosts with Docker. Windows users should run through WSL 2.

• Docker and Docker Compose installed and running.
• Node.js 20 or later (required by the @openkodaai/koda CLI).
• Free ports 3000 (dashboard) and 8090 (control plane).

Install with the CLI

The fastest path is through npm. Two forms both produce the same result: you can install the CLI globally, or run it once through npx.

$npx @openkodaai/koda@latest install

Or install globally once and reuse the binary:

$npm install -g @openkodaai/koda
$koda install

What the installer does

koda install is idempotent and safe to re-run. On the first run it:

1. 1

   Verifies prerequisites

   Checks Docker, Docker Compose, and Node versions. Fails fast with a specific error if anything is missing.
2. 2

   Stages the release bundle

   Downloads and unpacks the pinned product release into an installation directory (defaults to ~/.koda; override with --dir).
3. 3

   Creates a minimal .env

   If one does not exist, writes defaults for Postgres, object storage, session secrets, and control-plane authentication.
4. 4

   Starts the compose stack

   Brings up web, app, postgres, seaweedfs (plus internal runtime services) through the release compose file.
5. 5

   Runs doctor checks

   Verifies bootstrap configuration, storage connectivity, secret hygiene, dashboard reachability, and control-plane reachability.
6. 6

   Prints the dashboard URL and setup code

   You'll see a localhost URL and a short-lived code used in the first-owner flow.

Services that start

After a successful install the compose stack exposes four public-facing surfaces plus internal runtime services:

Internal gRPC services for security, memory, artifact, retrieval, and runtime kernel are also started but aren't exposed outside the compose network.

First-run flow

Once the installer finishes it prints a dashboard URL. Open it in a browser on the same machine and complete setup in six steps:

1. 1

   Open /control-plane/setup

   The installer prints this URL. On loopback (127.0.0.1) the development default ALLOW_LOOPBACK_BOOTSTRAP=true lets you skip the setup code. On a remote host you'll be prompted for it.
2. 2

   Paste the setup code if prompted

   If you need a new one, run koda auth issue-code to print another short-lived code.
3. 3

   Create the owner account

   Email, password (minimum 12 characters across 3 of 4 character classes), and a username auto-derived from the email local-part (you can rename later in Settings).
4. 4

   Save the recovery codes

   Ten single-use codes will be shown once and never again. Copy them into a password manager or secret store — they're how you recover access without SMTP configured.
5. 5

   Sign in to open an operator session

   The dashboard opens an HTTP-only cookie session. From here the rest of setup happens in the UI — provider credentials, access policy, and optional first-agent wizards.
6. 6

   Optional: connect a provider and create a first agent

   The home dashboard surfaces a checklist for the three opt-in setup steps. None of them block normal operation — you can explore first and configure later.

Diagnostics

If something feels off after install, the doctor command walks through the same checks the installer ran:

$koda doctor

Add --json for machine-readable output, or point at a custom installation directory with --dir.

Lifecycle commands

A handful of commands cover day-to-day operation:

• koda up — start a stopped installation.
• koda down — stop the stack (state volumes persist).
• koda logs [service] — tail logs from one or all services.
• koda update — pull the latest release, restart, and auto-rollback if the doctor check fails.
• koda uninstall [--purge] — remove the installation; --purge also drops state volumes.
• koda version — print the currently installed release.

Where next

• Quickstart — walk through the full path from install to first agent.
• VPS deployment — hardening, reverse proxy, HTTPS, and production checklist.
• Troubleshooting — if doctor is red, start here.