The page, and the run record

What a run writes down

A run shows a line per step with what it returned, what it took and what it cost, its state as it stands, and, while it is waiting, who was asked and until when. A step that asked a model is one of those lines with a price on it, which is how a job that quietly grew a second model call shows up as a second line and a bigger number.

Answering a parked job usually happens wherever the question arrived, but POST /api/runs/<id>/answer with {"text":"yes"} does it from the page.

The page

React, in chloe-ui/, a package of its own: react and esbuild are its dependencies, so the runtime's only one is zod. It bundles itself in memory when the page is asked for, so an edit there is live and no built file is ever committed or served from disk. Without it installed there is no page and no way to sign in, and the jobs, the cron lines and the channels carry on.

One app on several addresses. / is the overview, /agents/<name> is one agent, /agents/<name>/files/<path> is one of that agent's files or folders at the path it has on disk, /agents/<name>/chat is talking to it, /agents/<name>/log is its history, and /log is every agent's history searched together. On either log, ?run=<id> opens one run in a panel down the right.

The login

Made on the first visit. A fresh copy has no account, so the first person to open the page is asked to choose a username and a password, and once one exists that page is not offered again. Everything on the port is behind it: the page, the API, and npm run agent, which signs itself in by reading the account. A channel's own path is the one exception, and it carries its own secret.

The server binds loopback. Putting it on the internet means putting a reverse proxy with a password in front of it.

State

Everything the agents write lives in data/, beside chloe.config.ts, and git should ignore it. Copying that folder plus cloning your repo is the whole of moving to a new machine.

data/agents.db   conversations and the run history
data/login.json  the one account the page lets in, mode 600
data/<name>/     whatever that agent decides to keep

It is worked out from where your repo is, so there is nothing to set, and state in settings.local.json moves it. Files a setting points at, like a key file, are not state and stay wherever that setting says. A folder outside the repo that an agent uses, like where its backups go, is a full path written in that agent's own file.

git clean -x would delete data/. Do not run that in a repo that holds it.