Workspace

Local experiment store, provenance, and cloud sync. Clone koyu-workspace and hand it to your agent; this page is the semantics.

What it is for

The workspace is where experiments live before (and after) the cloud: a file-based store mirroring the cloud's entities — projects, runs, manifests, episodes — plus an ingester that sweeps the runtime's outbox, a sync engine that pushes/pulls against koyu.dev, and a small web UI.

Files are the truth. Every entity is a directory with a JSON file; your agent can cat and grep the entire state of your research. There is no database to interrogate.

Experiments, not code

The sync engine pushes and pulls, so it feels GitHub-shaped — it is not. Use git for code. Use runs for experiments. A run stores what a training or eval produced, linked to the manifest it consumed. Runs nest: collect intervention data against a checkpoint → child run with its own manifest → train on it → grandchild. The tree is your experiment history, and each node syncs to the cloud as a durable, shareable snapshot — checkpoint, metrics, the exact dataset that made it, and the evaluations that judged it.

Ingest: the seam with the robot

The runtime writes episode bundles to its outbox and never learns what a manifest is. The workspace ingester sweeps the outbox, mints identities, resolves each episode's requested manifest (intent recorded at capture, resolution decided at ingest), and files it into the store. Re-ingest is idempotent — the spool is the system of record and the store can be rebuilt from it.

Modify it

The shipped frontend is a starting point, deliberately. The store is a plain directory tree, the local API is small, the sync engine is callable as a library — all of it is meant to be reshaped by you and your agent to fit your lab's workflow. The only stable things are the entity shapes (which mirror the cloud API) and the format of what lands in the store.