Quickstart

This walkthrough takes you from a machine with Docker and Node installed to a Koda instance running your first agent. If something fails mid-way, each step lists what to check.

One-command install

Run the CLI. The installer handles the rest:

$npx @openkodaai/koda@latest install

Expected output, trimmed for clarity:

✓ Prerequisites verified (docker 24.x, node 20.x)
✓ Release bundle staged at ~/.koda
✓ .env created with safe defaults
✓ Compose stack started (web, app, postgres, seaweedfs)
✓ Doctor: all checks passed
Dashboard:  http://127.0.0.1:3000/control-plane/setup
Setup code: 7F-JQ2-P84

If doctor reports a failure, stop here and see Troubleshooting before proceeding — the dashboard won't be reliable until the bootstrap is clean.

First-owner setup

1. 1

   Open the dashboard setup URL

   Navigate to http://127.0.0.1:3000/control-plane/setup. On loopback the setup code is optional by default. If the browser prompts for it, paste the one printed by the installer.
2. 2

   Create an owner account

   Pick an email and a password with at least 12 characters spanning three of four character classes (upper, lower, digit, symbol). The form previews requirements as you type.
3. 3

   Save the recovery codes

   Ten single-use codes appear once and never again. Put them in a password manager or secret store. They are how you recover access if SMTP is not configured.
4. 4

   Sign in

   After registering, the dashboard opens an HTTP-only operator session cookie and lands you on the home view with a setup checklist.

Connect a provider

An agent can't do useful work without a model. The home dashboard exposes a Connect an AI provider step on the setup checklist. Open it and pick any supported provider — Anthropic, OpenAI, Google, or Ollama (for local/self-hosted models).

1. 1

   Open the provider wizard

   From the dashboard home, click Connect an AI provider on the checklist card. Each provider has its own short form (API key, optional base URL, optional project/org identifiers).
2. 2

   Paste credentials and verify

   Koda verifies the key before saving. Failed verification surfaces the provider's raw error so you can tell a revoked key from a network issue.
3. 3

   Pick a default model

   Once verified, set a default model for the provider. Agents can override this per role later, but a default is required so bot creation can complete.

Create the first agent

1. 1

   Open the agent wizard

   Click Create your first agent on the setup checklist, or go to Control plane → Agents → New.
2. 2

   Name the agent and pick a model

   Every agent has a human name (used in the dashboard and any messaging integration) and a model. The model defaults to your provider's default but can be overridden — for example, a cheaper model for triage and a larger one for final drafts.
3. 3

   Attach Skills and memory scope (optional for now)

   You can wire Skills and a memory scope here, or start with a plain system prompt and add those later. Both are described in detail in the Skills and Memory & knowledge sections.
4. 4

   Publish

   Publishing moves the agent from draft to runnable. Koda creates the runtime records, registers the OpenAPI endpoints, and surfaces the agent in the runtime catalogue.

Run your first task

There are two equivalent entry points:

• From the dashboard. Open the agent and start a new session from the chat view. The transcript is recorded as a runtime task with full inspection.
• From the runtime API. Use /api/runtime/tasks (see the Runtime API) with the operator session cookie or a runtime token.

The dashboard is the fastest feedback loop for the first run — you'll see the agent's tool calls, provider responses, memory writes, and the final output appear in real time.

Verify the install

Three checks that are worth running before you trust the stack:

• Doctor is clean. koda doctor returns no warnings or errors.
• Health surface responds. curl http://127.0.0.1:8090/health returns a JSON payload with all components marked healthy.
• First run succeeded end-to-end. A task is visible in the dashboard with a complete trace — no broken tool calls, no missing memory writes.

Keyboard shortcuts you'll use

• ⌘ K — open search anywhere in these docs.
• Esc — close any dialog or drawer.

Where next

• Architecture — the mental model behind everything you just did.
• Authoring a Skill — turn your best prompt patterns into first-class abilities.
• VPS deployment — move from localhost to a hardened, TLS-fronted install.