Skip to content
Kurahi

Kurahi

Kurahi is a resident agent runtime. One background service per identity runs under your operating system’s service manager; your terminal, the web UI, messaging channels and paired devices are clients of that service. State lives in one directory, the service binds to loopback unless you opt in to remote access, and everything a client does is written to a hash-chained audit log.

Start here

Section titled “Start here”

How it is put together

Section titled “How it is put together”
terminal (kurahi tui, kurahi attach)   web UI   paired devices   messaging channels
            │                        │           │                 │
            └────────────────────────┴───────────┴─────────────────┘
                                     │  authenticated clients
                                     ▼
                         ┌───────────────────────┐
                         │        gateway        │  one process per identity
                         │  sessions · agents    │  loopback by default
                         │  tool policy · audit  │  OS service (systemd / launchd /
                         │  secrets · integrity  │  Task Scheduler)
                         └───────────┬───────────┘
                                     │
                       model providers · local model servers

The gateway is the only long-running process. It owns the channel connections, the session store, the agent runtime and the control plane. Every other surface talks to it over an authenticated WebSocket or the HTTP API.

What the runtime guarantees

Section titled “What the runtime guarantees”
  • One state root. KOLO_HOME (~/.kolo on Linux and macOS, %LOCALAPPDATA%\KoLo on Windows) holds config, secrets, sessions, logs and the audit chain. Nothing is written elsewhere.
  • Loopback by default. Remote access requires an explicit bind policy and a token; see Remote access.
  • Every route authenticated. The only open endpoints are /health and /api/health, which answer with status, version and uptime; detail requires a credential.
  • Scoped pairing. Invitations carry a scope (observe < attach < admin < owner), are redeemed with a device key over a server nonce, and issue short-lived access tokens with rotating refresh; reuse of a retired refresh token revokes the family.
  • Audit and integrity. kurahi audit verify checks the chain; the boot integrity gate refuses to start when a registered file changed.
  • Described API. OpenAPI 3.1 at /doc; kurahi api <operation> calls anything the gateway can do; the generated client is @kodasoken/kurahi-client.

Surfaces

Section titled “Surfaces”
Surface How
Terminal kurahi tui, kurahi attach <session>, kurahi agent --message
Web UI served by the gateway at its HTTP port; kurahi dashboard opens it with your token
Messaging channel extensions (LINE, WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Matrix, Teams, Google Chat, Mattermost and more); see Channels
Devices iOS, Android and macOS companions pair as nodes
Automation Cron, Hooks, Webhooks

Command surface

Section titled “Command surface”

kurahi --help lists every command. The ones you will use first:

Command Purpose
kurahi init create the state directory, config and gateway token; run doctor
kurahi service install | status | logs run the gateway under the OS service manager
kurahi health, kurahi status, kurahi doctor one-line health, detailed status, checks and repairs
kurahi pair invite | list | revoke device and terminal pairing
kurahi attach, kurahi sessions live sessions
kurahi secrets set | list provider keys and other secrets
kurahi audit verify | tail the audit chain
kurahi update, kurahi uninstall lifecycle

Exit codes are the same everywhere: 0 ok, 1 error, 2 usage, 3 gateway unreachable, 4 authentication.

Licensing

Section titled “Licensing”

Kurahi is open core: MIT for the protocol, SDK, plugin API and CLI; Functional Source License for the gateway runtime and its subsystems; a proprietary licence for the identity engine and enterprise features. The map is in the repository’s LICENSING.md.