Kinu gives AI agents a durable computer of their own.
It records outcomes, runs locally or fully in the cloud, and evaluates hard tasks
by exploring multiple approaches and 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
Illustrative interface demo, not measured benchmark results. Explore the current interactive examples at kinu.run.
A workspace holds a durable POSIX filesystem, a shell, execution environments, agent conversations, memory, and an event log. Close the laptop and a cloud workspace keeps going. A schedule or a webhook starts the next turn with nobody at the keyboard. An email does too once the mail domain is onboarded.
The agent writes tools for itself and keeps the ones that score well. Each task starts from what the last one taught it.
For a hard task it runs a search whose nodes are whole agents. A verifier runs in the workspace and reports a number. The number picks the winner.
Hosted. Sign in at kinu.run and create a workspace in the browser. Close the tab and the workspace keeps running.
From your terminal.
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 a full-screen terminal UI over the same workspace. kinu exec
runs one task, never prompts, and exits 0 only when the turn completed cleanly.
Cloud or your own machine. --mode cloud runs on Cloudflare Durable Objects.
--mode local runs on your machine over bun:sqlite. The agent is the same either
way. kinu export archives either one. kinu import restores it locally. Editors
attach over kinu acp.
QUICKSTART.md is the short path. docs/USER-GUIDE.md covers daily use.
kinu.run is one deployment of this repository. Yours runs the same Worker, containers and search code on your 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 required gate roster passes.
Preflight runs first, source gates run concurrently, and gate:hammer then
gate:infra each run alone at the end. You bring a Workers Paid account, a
zone, and OAuth applications for sign-in.
docs/DEPLOYMENT.md lists each prerequisite.
docs/SELF-HOSTING.md walks an empty account end to end.
| One real filesystem | A durable POSIX filesystem with a real shell, ~95 coreutils, and language runtimes installed on demand. The same component runs on Workers and on your machine. |
| 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. |
| Containers that stay | A Cloudflare container is spot capacity; the disk can come back blank between two calls. @kinu.run/devbox brings files, supervised processes and preview URLs back after a recycle. |
| Swarms | A search whose nodes are whole tool-calling agents. Seven presets, six axes, and a workspace verifier that reports the number that picks the winner. |
| 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. Four structural gates validate a mutation before it runs. |
| Evolution | Four timescales: step, turn, session, lifetime. kinu evolve searches over the scaffold itself. |
| Triggers | Schedules and webhooks reach a workspace with nobody at the keyboard. Email reaches it too, on a domain that has completed the one-time Email Routing setup. kinu.run has not completed it, so the inbox is code-complete and inert. |
| 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, a local Claude Code 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.
- Measure evolution's lift on the sealed bench and publish the number.
- Settle the default container storage strategy from the deployed three-way benchmark.
- 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/ |
An ephemeral Cloudflare container presented as a machine that stays: lifecycle, activity lease, supervised processes, ports, three storage strategies | Yes. A standalone SDK over @cloudflare/sandbox. Extend the class, override the hooks. Depends on no other package here |
core/ |
The turn pipeline, canonical VFS and execution router, swarm and MCTS engines, evolution, CraftStore, scaffold, the eight tools, 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 |
cf-backend/ |
Cloudflare Workers: orchestrator, exploration and subordinate facets, 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 |
packages/core knows nothing about where it runs. 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.
A third backend implements that pair and nothing else. Core owns the turn. The turn arrives from a person, a schedule or a finished background job. Core assembles it once, then runs a step loop where the agent re-reads live workspace state between 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 |
| Exploration | The six axes, the node contract, the publication seal, settle and merge-back |
| Extensibility | The four 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 |
| 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 |
| 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 # 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