Deployment

Local install

Developer machines and evaluation environments.

The local install is the fastest way to evaluate Koda or work on it. It brings up the same compose topology a production install uses — dashboard, control plane, runtime services, Postgres, and object storage — on your laptop.

Same topology as production

The local quickstart and the single-node VPS path use the exact same compose file and services. Only environment variables change. What you test locally is what ships.

Prerequisites

Docker and Docker Compose installed and running.
Node.js 20 or later (required by the npm CLI).
Free ports 3000 (dashboard) and 8090 (control plane) on the host.
~2 GB of RAM available for the compose stack.

Install

The CLI is the recommended path. Two equivalent forms:

bash

$npx @openkodaai/koda@latest install

bash

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

From source (contributors)

If you cloned the repo, the wrapper script is equivalent:

bash

$git clone https://github.com/OpenKodaAI/koda.git /opt/koda
$cd /opt/koda
$./scripts/install.sh

The wrapper automates Docker and Node installation only on apt-based Linux hosts with sudo. On macOS or other environments, install those prerequisites yourself and use the npm CLI.

What the installer starts

Five services come up via compose. Four are public-facing, one is a one-shot bootstrap helper.

Service	Port	Purpose
web	3000	Next.js operator dashboard
app	8090	Control plane + runtime HTTP API
postgres	5432 (compose-internal)	Durable state (+ pgvector)
seaweedfs	8333 (compose-internal)	S3-compatible object storage
seaweedfs-init	—	Creates the default bucket on first boot

Five internal gRPC services (runtime-kernel:50061, retrieval:50062, memory:50063, artifact:50064, security:50065) also come up on the backend network but never leave the compose boundary.

Defaults that matter locally

The installer writes a minimal .env. On a development host two defaults deserve attention:

ALLOW_LOOPBACK_BOOTSTRAP=true — lets you finish first-owner setup at 127.0.0.1 without a setup code. Always false in production.
CONTROL_PLANE_AUTH_MODE=token — defaults to token mode. The escape hatches development and open exist for local debugging only and are refused at boot when KODA_ENV=production.
CONTROL_PLANE_API_TOKEN — left blank by default. Only set it when you need machine-to-machine CLI access.

First-boot flow

The installer prints a URL when it's done. Complete setup there:

Open http://127.0.0.1:3000/control-plane/setup.
On loopback, the setup code is optional; the form lets you proceed directly. On a remote host, paste the code from the installer output.
Create the owner account: email, password (12+ chars, 3 of 4 character classes), auto-derived username.
Save the ten recovery codes — shown once, never again.
Sign in. From there, the setup checklist offers optional steps (connect a provider, create an agent, connect Telegram). None block normal operation.

Manual startup (without the installer)

If you want tighter control — or you're already inside a cloned repo:

bash

$cp .env.example .env
$docker compose up -d --build
$python3 scripts/doctor.py --env-file .env --base-url http://127.0.0.1:8090 --dashboard-url http://127.0.0.1:3000

Doctor diagnostics

koda doctor runs the same checks the installer runs after startup. Use it any time the stack feels off.

bash

$koda doctor --json

The doctor validates bootstrap configuration, storage connectivity, secret hygiene, dashboard reachability, and control-plane reachability. --json gives machine-readable output for CI.

When doctor disagrees with the dashboard

The dashboard reflects runtime state, the doctor reflects bootstrap state. If doctor is clean but the dashboard shows degraded status, the issue is usually a provider credential, not the install.

Lifecycle

koda up / koda down — start and stop the stack. State volumes persist.
koda logs [service...] — tail logs. No service name tails everything.
koda update — pull the latest release, restart, run doctor, auto-rollback on failure.
koda uninstall --purge — remove the install and drop state volumes.

Next steps

VPS deployment — hardened, TLS-fronted, production-ready.
Troubleshooting — the right page if doctor is red.