Kinu gives AI agents a durable computer of their own.
It records lessons, runs locally or fully in the cloud, and tries multiple approaches
to hard tasks, letting executable checks choose the winner.
kinu.run
6 named searches · 8 built-in tools · 2 backends, one core · 4 execution environments
Quick start · User guide · Swarms · CLI reference
The planning walkthrough with sample data, recorded from the live interface. Try it at kinu.run.
I'm building Kinu as a general agent platform and software factory. Give a workspace a mission: research a question, build a live app, fix a codebase, or check something on a schedule. A cloud workspace keeps working while you are away, and you can return to its conversation, files and pending decisions.
You can use it for:
- Research. The
webtool searches and fetches pages with no keys. Aresearchswarm runs several angles on one question at once, and aresearcherrole can be hired for the long reads. - Live apps. Ask for a dashboard and the agent writes a slate: a small Worker
under
/home/user/slates/<id>/that opens in its own tab on a preview URL. A slate reads live data through bindings you declare: workspace files, a workspace read model, or an MCP connection narrowed to named tools. - Engineering. A real shell, git, package installs, a container for the heavy work, and a governed release lane with approvals. In Plan mode the agent reads and researches without changing project code, then submits a plan for you to review before a Build turn starts.
- Schedules and triggers. A cron timer, a one-shot timer, or a webhook wakes a cloud workspace with nobody at the keyboard.
- Work while you are away. Long commands and searches move to the background and wake the agent when they settle. Anything that needs your decision, a shell approval or a release approval, appears under "Needs you". Plans open for review in the same Work tab; settled work stays in its journal.
- Cloud or your own devices. A cloud workspace lives in a Durable Object on
Cloudflare and keeps running when your laptop is closed. A local workspace
runs on your machine over
bun:sqlite. It is the same agent either way. - Reach it from anywhere. The web app, the
kinuCLI, a full-screen terminal UI, and editors over the Agent Client Protocol can open a cloud workspace. Connect a machine of yours and every cloud workspace you grant can use it. - Bring your subscriptions. Connect your Cloudflare account for Workers AI. Connect your ChatGPT Codex subscription with a device code, or your OpenAI, Anthropic and OpenRouter keys, and cloud workspaces use them. On your machine a local workspace can also drive your Claude Code or opencode login.
The agent writes tools for itself and scores them with use. When you correct it, it records a provisional lesson. For a hard task it can run a swarm: a tree search whose nodes are whole agents, scored by a workspace verifier.
Sign in at kinu.run and create a workspace in the browser. Close the tab and the workspace keeps running. The home page lists your workspaces with what is active and what is waiting on you.
curl -fsSL 'https://kinu.run/install.sh' | bash
kinu setup # browser sign-in, provider keys
kinu create triage --mode cloud
kinu run triage "find the slowest query"kinu chat opens the terminal UI over the same workspace. kinu exec runs one
task, never prompts, and exits 0 only when the turn completed cleanly, so it
fits scripts and CI. kinu acp serves a workspace to Zed, JetBrains, neovim or
Marimo.
--mode cloud runs on Cloudflare. --mode local runs on your machine and needs
no account. kinu export archives either one and kinu import restores it
locally. QUICKSTART.md is the short path and
docs/USER-GUIDE.md covers daily use.
kinu connect # link this computer, with a consent prompt
kinu desktop status # is it attached?The daemon on your machine opens an outbound WebSocket to your Kinu account. You do not need to expose an inbound port for that tunnel. One connected device serves every workspace you grant. It works like this:
- A grant is per workspace and per machine. A workspace you have not granted is refused before anything reaches the device. Revoking a grant takes effect on the next call.
- Your machine mounts at
/pcin the workspace file plane, or/pc/<name>when you connect more than one. Mounts extend the view and never copy it. - The agent sees its own home plus the folders you named at connect time. The rest of your home is invisible by construction. On Linux the shell runs under bubblewrap, on macOS under sandbox-exec, and the file methods enforce the same view. Sandbox off is an explicit switch per device.
- Every shell command passes an approval gate before it runs. Housekeeping in the agent's own workspace or container runs without asking. The same recognized destructive command on your machine waits for you. Force-pushes and package publishing need approval on any executor. A standing approval is a rule you grant once, listed in Settings and revocable there. Known dangerous patterns, such as wiping the filesystem root, are refused.
The shell checks catch known command patterns. They are an accident guard, not protection against a hostile program. If the device cannot sandbox a command, it refuses execution unless you explicitly turn Sandbox off.
docs/EXECUTION-LAYER-SPEC.md has the whole model.
kinu.run is one deployment of this repository. Yours runs the same Worker, containers and search code on your own Cloudflare account.
bun install
bun run infra:provision # R2 buckets and Vectorize indexes
bun run deploy # the Worker, DO namespaces, container, routes, cron
bun run infra:provision # the secrets; wrangler needs the Worker to exist first
bun run gate:infra # every declared resource exists and is boundbun run deploy refuses to upload until its gate roster passes. You bring an
account on the Workers Paid plan, a zone with a wildcard DNS record for
previews, an AI Gateway, and OAuth applications for sign-in. Provisioning
prints that list every run. docs/DEPLOYMENT.md lists each
prerequisite and every secret. docs/SELF-HOSTING.md
walks an empty account end to end. I have not measured the monthly cost of a
fresh self-host as of 2026-09-13; model use, storage and containers affect it.
| One real filesystem | A durable POSIX filesystem with a shell, coreutils and git, over Nimbus's WASM OS. Choose an executor that supports the runtime your project needs. |
| Four executors | The workspace, a Linux container, your own machine over a consented tunnel, or the workspace a fork came from. The prompt tells the model what each one can do. |
| Container recovery | @kinu.run/devbox persists workspace files and records supervised processes and ports for restoration after a recycle. Storage uses an immutable base plus one cumulative delta and a read-only block layer. Preview addresses can change. Full live strategy admission remains refused; see the decision log. |
| Slates | Live apps the agent writes as small Workers, previewed on their own hostname, reading your data through declared bindings. |
| Plan mode | The agent reads and researches, then submits a Markdown plan. You annotate lines or approve, and only then does a Build turn start. |
| Swarms | A search whose nodes are whole tool-calling agents. Six named presets plus custom, six axes, and a workspace verifier that reports the number that picks the winner. The Swarms tab shows the tree as it grows. |
| Delegation | One agents tool: swarm, hire, msg, list, dismiss. A hire is durable or a single task, and runs as task, researcher, planner, auditor or designer. |
| Crafted tools | The agent writes tools, scores them with use, and finds them again over FTS5. |
| A mutable scaffold | The agent loop is code the agent can rewrite. Structural gates validate a mutation before it runs. |
| Evolution | Four timescales: step, turn, session, lifetime. An optional advisor reviews finished turns. kinu evolve searches over the scaffold itself. |
| Prompts as Markdown | Prompt prose lives under packages/core/src/prompts/. The builder selects sections and fills their slots; indexed sections can be evolved individually. |
| Triggers | Timers and webhooks wake cloud workspaces. Local timers need kinu daemon running. Email requires domain onboarding; the last recorded live check, 2026-08-20, found it incomplete on kinu.run (email setup). |
| Web search | The web tool works with no keys. A Tavily key adds ranked search. |
| Model choice | Your Cloudflare account through one sign-in, or your keys: OpenAI, Anthropic, OpenRouter, a Codex subscription, any OpenAI-compatible endpoint, and locally a Claude Code or opencode login. |
| A control plane | Operators get /control: users, workspaces, incidents, feedback, fleet metrics, an audit log. |
| Headless | Scoped tokens keep webhooks and consent interactive-only; kinu exec fits scripts and CI. |
docs/TOOLS.md covers the eight built-in tools. docs/EXPLORATION.md covers the axes, presets and records. docs/LIVE-UI.md covers slates.
- Measure evolution's lift on the sealed bench and publish the number.
- Close the container storage decision with a full live acceptance on deployed Containers (docs/DEVBOX-DECISIONS.md, O1).
- Seed the hosted runtime catalog so a fresh self-host gets Python without a manual step.
A Bun workspace. Platform-agnostic code lives in core/; the two backends are
adapters over it.
| Package | What it holds | On its own |
|---|---|---|
devbox/ |
Container lifecycle, activity leases, supervised processes, ports, and snapshot-chain storage with the block layer | Yes. A standalone SDK over @cloudflare/sandbox; it depends on no other package here |
core/ |
The turn pipeline, canonical VFS and execution router, swarm and MCTS engines, evolution, the advisor, CraftStore, scaffold, the eight tools, slates, the event log | Needs a backend to host it |
agent-utils/ |
MemoryStore and CraftStore over FTS5, shared VFS types, path addressing | Yes, as small libraries |
compaction/ |
The default context transformer: the better-compact ladder and its codec | Yes |
agent-core/ |
The vendored slate runtime, digest-pinned to its upstream | Private |
cf-backend/ |
Cloudflare Workers: the workspace Durable Object and its logical actors, KinuSandbox, UserDO, the React UI | This is the deployment |
cli/ |
The kinu commands |
Yes, this is the CLI |
cli-backend/ |
Local runtime over bun:sqlite, subprocess sandbox, child-process branches |
Behind the CLI |
pc-agent/ |
The device agent that lends your machine to a workspace | Yes |
test-utils/ |
Shared fakes and fixtures | In this repo's suites |
Kinu agents are platform agnostic and implemented in packages/core, and can
be extended to run on any backend. Two interfaces carry the platform.
AgentRuntime provides storage, memory, models and scheduling. BackendHost
provides what a turn loop needs from its host. I implement the pair twice: on
Cloudflare Durable Objects built on Think,
and on POSIX over bun:sqlite and real processes.
To add a backend, implement those interfaces and connect its available services. Keep the shared turn and tool logic in core. A turn arrives from a person, a schedule or a finished background job. Core assembles its context, then reads live workspace state between model steps.
Three extension points live inside that loop: an actor kind, a ModelProvider,
and the inference loop itself.
docs/EXTENSIBILITY.md works each one through with a real
example. docs/ARCHITECTURE.md has the object model, message
flow, events and ingress.
Start with Quick start, then the
User guide. CLI reference is generated from the
command registry, and Configuration documents every
~/.kinu/config.json field.
How it works, in depth
| Document | What is in it |
|---|---|
| Workspaces | The object model: a workspace is the container, agents are actors inside it |
| Architecture | System design, message flow, package structure, Think lifecycle |
| Product spec | The requested contract, current behaviour against it, and the product diagrams |
| Exploration | The six axes, the node contract, the publication seal, settle and merge-back |
| Extensibility | The three extension points, worked through with real examples |
| Evolution | The four timescales, CraftStore lifecycle, scaffold mutation |
| MCTS | UCT formula, branch isolation, convergence |
| Tools | The eight built-ins, the file plane, the agents surface, the codemode sandbox |
| Live UI | Slates: authoring, the one codemode operation, bindings and the resident preview |
| Execution layer | The four executors, mounts, device consent, what runs where |
| Context budget | Where bulk spills, the turn-cumulative clamp, the trip counters |
| Observability | Failure classification, the typed logger, what is wired and what is not |
| Storage | Data model, workspace files over the Nimbus VFS, MemoryStore FTS5, table schemas |
| Devbox decisions | Every container storage decision, with the measurement that settled it |
| Deployment | Local dev, Cloudflare deploy, AI Gateway setup, secrets |
| Self-hosting | An empty Cloudflare account to your own instance |
| Formal spec | Lean 4 models, assumptions, traceability, CI gates |
| Bench | The instrument for whether self-evolution helps: sealed split, paired stats |
| Testing | Conventions, what "all tests" runs, and the tier that calls a real model |
| Changelog | What changed in each version, and the release checklist |
bun install
bun run check # lint and type-check every package
bun test --cwd packages/core # also: cf-backend, cli, cli-backend, agent-utils, devboxContributions are welcome. AGENTS.md carries the rules this repository runs on, for people and for agents.
MIT