Your first run

You want an agent harness that keeps its state on your machine: no hosted service, no account, nothing leaving your laptop that you did not send. This tutorial takes you from nothing installed to a running server, a signed-in coding agent, and a completed chat turn.

By the end you will have keelson installed in its managed home, know how to read its health sweep, and have pushed one message through the whole loop: CLI to server to provider and back.

Prerequisites

Bun on your PATH, ~/.local/bin on your PATH, and a GitHub Copilot subscription. A fresh keelson defaults to Copilot, so this rail assumes it; if you would rather drive Claude, Codex, or Pi, the configuration guide covers enabling them, and the steps below are otherwise identical.

Install the harness

The installer provisions ~/.keelson, the managed home that holds the CLI, its SQLite store, your workflows, and the ribs you install later. It also drops a keelson launcher in ~/.local/bin.

curl -fsSL https://github.com/danielscholl/keelson/releases/latest/download/install.sh | sh

The last lines of the install tell you where everything landed:

keelson v0.11.0 installed to /Users/you/.keelson
launcher: /Users/you/.local/bin/keelson  (ensure /Users/you/.local/bin is on PATH)

Confirm the launcher resolves and the versions line up:

keelson version

name: @keelson/cli
version: 0.11.0
bunVersion: 1.3.13
schemaVersion: 0.3

Re-running the installer later upgrades in place and preserves your installed ribs, and keelson update does the same from the CLI once you are set up.

Read the health sweep

Before starting anything, run the health sweep. keelson doctor probes the toolchain, the server, the database, credential storage, your workflows, and installed ribs in one pass:

keelson doctor

It runs one check per category and prints each one’s status, detail, and (on a warn or fail) a hint. On a fresh install, before the first keelson start, the results read like this:

Category	Check	Status	What it tells you
toolchain	bun --version	ok	Bun is on your PATH (1.3.13).
server	GET /api/health	warn	No server is running yet. Hint: run keelson start.
db	schema_version	warn	No database yet; the first keelson start creates and migrates it.
auth	keyring round-trip	ok	The OS keychain reads and writes back (service=keelson).
auth	providers	ok	copilot is enabled and the default (source: defaults).
workflows	discovery	ok	Eight starter workflows under ~/.keelson/workflows.
workflows	parse	ok	Every workflow parses cleanly.

It closes with a tally: 5 ok, 2 warn, 0 fail across seven checks. (The terminal prints the same results as indented text; keelson doctor --json emits them as structured JSON for scripting.)

Both warnings are expected on a first run. The server check cannot reach a server because none is running yet, and db has no database because the first keelson start is what creates and migrates it. Each warning carries the hint naming its exact next move, and here both point at the same one: start the server. Meanwhile workflows already found the eight starter files a fresh install seeds, so the catalog is usable before you write anything. The tutorials that follow build on it.

Install a rib later and a ribs category joins the sweep, one check per rib reporting whether it wired up cleanly.

Two different version numbers

schemaVersion: 0.3 (from keelson version and /api/health) is the wire and protocol version a client checks on connect. schema_version: v4 (the db check, once keelson start has created the database) is the local SQLite migration version doctor verifies. They move independently, so the two numbers will not match.

Doctor is your reflex

Whenever keelson behaves unexpectedly, run keelson doctor first. Every check that fails or warns carries a hint with the next command to run.

Start the server

The server owns the store, the providers, and the browser UI, all on one port. Start it in a terminal you can leave open:

keelson start --foreground

[workflows] discovered 8 workflows
keelson server listening on http://127.0.0.1:7878/

A fresh keelson loads Copilot by default, so there is no provider to configure. You just need to sign in, which is the next step.

Open http://127.0.0.1:7878 in a browser. The server serves the full web UI from the same port as the API: a Chat surface, a Workflows surface, and a tab for each rib you install later.

Sign in to Copilot

The server is up, but Copilot still needs your credential. On the Chat surface, use its sign-in surface to authorize GitHub Copilot; keelson stores the credential in your OS keychain, never in a file. (Prefer the terminal? copilot auth login authorizes the same credential.) The providers reference documents the sign-in surface and where the credential lives.

Confirm the harness is healthy

Now run the sweep again from a second terminal:

keelson doctor

  -     category: server
    checks:
      -         name: GET /api/health
        status: ok
        detail: keelson, schema 0.3 @ http://127.0.0.1:7878
summary:
  ok: 7
  warn: 0
  fail: 0
  skip: 0
  total: 7

All seven checks pass. Both warns you saw earlier, the server and the database, resolved themselves the way their hints said they would: the one keelson start brought up the server and created the database in a single move.

Complete a first turn

Push one message through the loop:

keelson chat "In one sentence, what is keelson?"

Keelson is a local-only harness that wraps a coding agent with persistent state, deterministic YAML workflows, and a browser UI.

That is a real answer from Copilot. Your message traveled from the CLI over HTTP to the server, through the provider registry to Copilot, and streamed back. The turn also landed in the server’s SQLite store, so if you open the Chat surface in the browser you will find the same session there: one store behind every surface, which is the next tutorial.

A different provider

Copilot is the default, not the only option. Claude, Codex, and Pi each enable in ~/.keelson/config.json, and a gateway points keelson at any OpenAI-compatible endpoint. The configuration guide covers enabling each one and its sign-in; nothing else in this rail changes.

When the server is down

keelson chat and keelson workflow run do not require the server. When it is down they fall back to in-process execution and print to stdout, which is why the CLI works for quick checks even before keelson start. Server-backed features like the browser UI and the rib commands need the server up.

Common errors

Symptom	What’s happening
keelson: command not found after install	~/.local/bin is not on your PATH. Add export PATH="$HOME/.local/bin:$PATH" to your shell profile and reopen the shell. The installer’s last lines print the exact path to add.
keelson version reports a version you did not install	Another keelson is earlier on your PATH. Run which -a keelson; the copy in ~/.local/bin should be the one that resolves.
doctor warns on the server and db checks	Expected before your first keelson start: both resolve once the server boots and creates the database, so neither is an error on a fresh install.
keelson chat fails with a Copilot authentication error	Copilot is not signed in yet. Complete the sign-in step; keelson doctor re-checks credentials.

What you proved

1. The harness installs into one managed home, ~/.keelson, with a launcher on your PATH.

2. keelson doctor is the diagnostic reflex, and its hints name the next command when something is off.

3. One server on port 7878 carries the API, the WebSocket stream, and the browser UI.

4. With Copilot signed in, a chat turn flows CLI to server to provider and back, and lands in the store.

Your harness runs, with a real agent behind it and a handful of starter workflows already seeded. You pushed one turn through the CLI; next you actually talk to the agent, three ways, and watch one store back them all.

Continue to Talk to the agent.