koyu¶
Honest roadmap note: every domain described here will change substantially in the coming months. Data loading today is deliberately dumb — download the dataset, then train. Streaming, GOP-aware video access, and smarter caching come later. What will not change casually are the contracts: the episode format, the dataset layout, the policy contract, and the API. Code churns behind frozen seams.
Why this exists¶
Robot learning has always been mostly muck: drivers, recording pipelines, format conversions, experiment bookkeeping, eval scaffolding. The interesting work — policies, data, evaluations — sits on top of a swamp that every lab rebuilds and nobody enjoys.
Coding agents change the economics of the muck. An agent can write the glue, adapt the loader, wire the new sensor, and stand up the eval — if the system it operates on is legible to it. koyu is a robot-learning platform designed end-to-end for that: every interface is small enough to fit in a context window, every seam is a file or a documented API, and all local code is open source and meant to be modified. You focus on research and evaluations; your agent handles the infrastructure.
That is also the honest comparison to the alternatives. ROS and LeRobot are excellent at what they aggregate, but they are monoliths: general because they must serve everyone, and too large to hand to an agent whole. koyu takes the opposite bet — small, fragmented, specialized per use — because agents thrive on systems they can read completely and modify safely.
The four domains¶
Data moves through four domains, each with its own clock. The seams between them are deliberately dumb — the bigger the timescale gap, the simpler the interface (shared-memory structs → files → HTTP):
| Domain | Clock | What it is |
|---|---|---|
| Runtime | µs – ms | On-robot processes: capture, control, IPC. supervisord + iceoryx2. |
| Workspace | sec – min | Local experiment store + provenance + sync. Your machine. |
| Cloud | durable | A thin, honest wrapper around R2: datasets, projects, runs, lineage. |
| CLI | hours | koyu fetch / pull / push — move data to GPUs and results back. |
The loop they form: the runtime records episodes into an outbox → the workspace ingests them into manifests and syncs to the cloud → the CLI materializes datasets onto a GPU box → training pushes checkpoints and metrics back to a run → evaluations produce new episodes, stamped with the checkpoint that generated them → back into the loop. Every arrow is a serialization point; every artifact knows its parent.
Use the parts you want¶
The domains are separable on purpose. Some people will adopt the runtime pattern (iceoryx2 + supervisord + a flight recorder) and ignore everything else. Some already live in ROS and just want the cloud — a place where their agent can dump datasets and checkpoints with three commands and get lineage for free. Some only want the templates. All of these are intended uses, not degraded ones. Nothing in koyu requires the rest of koyu.
Experiments, not code¶
The workspace and cloud look vaguely GitHub-shaped — there is push and pull — but the unit of storage is an experiment, not a codebase. Keep using git for code. A Run holds one experiment: the checkpoint, the metrics, the config, linked to the exact manifest (dataset) that trained it and to the evaluations that judged it. Runs nest — collect intervention data against a checkpoint, and that becomes a child run with its own manifest. The tree is the provenance.
Built to be modified¶
Everything local — runtime, workspace, CLI, the template code — is open source, and the APIs are deliberately composable. This is not a courtesy; it is the design. Agents make custom tooling cheap, so koyu assumes you will build your own dashboards, your own loaders, your own conventions on top. The workspace frontend ships as a starting point, not a product surface: change it. The only things asked to stay stable are the contracts — because they are what your tools and everyone else's agents compose against.
Where to go next¶
- Replicating a template? You need nothing but the template page — start at templates.
- Bringing your own data? Read the format — it is one page, and it is the constitution.
- Building a policy or an eval? The policy contract.
- You are an agent? agents.md is the whole entity model in forty lines.
- Working on a repo? Clone it and dump it into your context — every repo fits. The runtime and workspace pages carry only the invariants you must not break.