Development Setup

This guide covers running kaged locally for development. The daemon and UI run with hot reload via devctl.sh.

Architecture

operator browser
    │
    ▼  http://127.0.0.1:13001
Vite dev server (proxy /api → daemon)
    │
    ▼  http://127.0.0.1:13000
kaged daemon (--watch, insecure mode)

Prerequisites

Bun runtime
A cloned kaged repository
At least one LLM provider API key

Step 1: Install dependencies

bun install

This installs all workspace packages.

Step 2: Start the dev stack

./devctl.sh start

This boots two processes in a tmux session named kaged:

Daemon — bun --watch run src/main.ts start --bind 127.0.0.1:13000 (with insecure auth)
UI — bunx vite --port 13001 --host (with KAGED_DAEMON_PORT=13000 proxy)

The daemon starts in insecure mode (no auth required). A magenta banner appears in the UI.

Step 3: Open the UI

Navigate to http://127.0.0.1:13001. No login required.

devctl commands

Command	What it does
`./devctl.sh start`	Boot daemon + UI in tmux
`./devctl.sh status`	Show process status
`./devctl.sh restart`	Restart both services
`./devctl.sh stop`	Stop the tmux session
`./devctl.sh attach`	Attach to tmux (Ctrl-B D to detach)
`./devctl.sh logs daemon`	Tail daemon logs
`./devctl.sh logs ui`	Tail UI/Vite logs

Default ports: daemon 13000, UI 13001. Override with --daemon-port N / --ui-port N.

Step 4: Configure an LLM provider

Create or edit ~/.config/kaged/config.toml and add a provider under [providers]:

[providers.claude]
driver = "anthropic"
api_key_env = "ANTHROPIC_API_KEY"

[aliases]
default = "claude:claude-sonnet-4-20250514"

Set the API key in your environment:

export ANTHROPIC_API_KEY=sk-ant-...

Restart the daemon to pick up config changes: ./devctl.sh restart.

Running tests

bun test                    # all packages
bun test:dsl                # one package
bun --filter '@kaged/daemon' test  # by package name

Type checking

bun run typecheck           # all packages (canonical command)
bun --filter '*' typecheck  # equivalent

Do NOT use tsc --noEmit at the repo root — it's a no-op by design (ADR-0025).

Formatting

bun format                  # Biome format + lint for the entire repo

Project structure

The repo dogfoods kaged itself. See .kaged/project.yaml for the kaged-on-kaged configuration. The project DSL files under docs/dsl/examples/ show the full range of YAML constructs.