Kohala Devkit

Build and run Kohala agents entirely on your own machine — no account, no billing, no waitlist. When you want your agent hosted, kohala deploy pushes the exact same agent to the platform.

npm install -g @kohala/devkit

kohala init my-agent
kohala run my-agent --local
kohala trace my-agent

That's the whole loop. Python 3 is the only other thing you need (to run skill scripts).

What you get

• kohala CLI — init, validate, run --local, trace, memory serve, login, deploy, doctor.
• Local agent emulator — executes your agent's charter with the platform's exact enforcement order: per-day admission, tool allowlist, per-run token caps, and validators with a bounded repair loop. Tokens are counted for cap enforcement and shown in the trace, but nothing is ever billed locally.
• Open MCP memory server — kohala memory serve exposes agent memory over the Model Context Protocol with the platform's tool names (s3.put, s3.get, s3.list, s3.delete). File backend by default; Postgres with --backend postgres.
• Python script SDK — scaffolded into every agent (skills/_tools.py, stdlib-only). Scripts talk to the runtime over a loopback RPC boundary, so the same script runs unchanged locally and hosted.
• Deploy client — kohala deploy maps your kohala.json onto the platform's REST API. Idempotent on agent name, additive only (never deletes anything remotely), with --dry-run to see exactly what would be sent.

The compatibility contract

kohala.json is a 1:1 mapping onto platform fields:

{
  "name": "my-agent",
  "charter": "Collect one interesting fact per shift.",
  "toolAllowlist": ["s3.put", "s3.get", "s3.list", "notify.send"],
  "runtimeMode": "wrap",
  "skills": { "main": "main.py" },
  "caps": { "perRunTokens": 20000, "perDayTokens": 100000 },
  "validators": [
    { "type": "shape", "minBytes": 10 },
    { "type": "freshness", "asset": "my-agent/latest", "maxAgeHours": 24 }
  ]
}

• runtimeMode: "wrap" executes your script directly and validates its output (stdout). Use llm.complete from the script SDK to call an LLM mid-script (needs ANTHROPIC_API_KEY or GEMINI_API_KEY).
• runtimeMode: "llm" runs a real Anthropic tool-use loop — requires ANTHROPIC_API_KEY. GEMINI_API_KEY works for llm.complete in wrap mode but not for this loop. The devkit never mocks completions.

Docs

• Quickstart
• Manifest reference
• How the emulator works
• Memory & the MCP server
• Deploying to kohala.ai

Examples

• examples/weather-logger — wrap mode, external HTTP + memory + freshness validator.
• examples/rss-digest — wrap mode with llm.complete summarization (needs an LLM key).
• examples/llm-notes — runtimeMode: "llm", a real tool-use loop (needs ANTHROPIC_API_KEY).

Requirements

• Node.js ≥ 20
• Python 3 (to run skill scripts)
• Optional: ANTHROPIC_API_KEY or GEMINI_API_KEY for LLM features
• Optional: pg + a Postgres URL for the Postgres memory backend
• Optional: a Kohala account — only for kohala deploy

Contributing

See CONTRIBUTING.md. Bug reports and PRs welcome.

License

MIT

LLM model overrides (local emulator)

kohala run in LLM mode picks its model from environment variables:

| Variable | Effect | | --- | --- | | KOHALA_LLM_MODEL | Provider-agnostic override — takes precedence over the two below. | | ANTHROPIC_MODEL | Anthropic model id (e.g. claude-3-5-haiku-latest). | | GEMINI_MODEL | Gemini model id (e.g. gemini-2.0-flash). |

Unset, the emulator uses its built-in defaults.

Memory server scoping

kohala memory serve is always scoped to ONE agent. Either run it from inside an agent directory (one containing kohala.json) or pass --agent <name>:

kohala memory serve --agent my-agent --backend file