Worker API
ravel serve exposes an HTTP + SSE API on one port (default 4317),
bound to 127.0.0.1 by default — it has no authentication, by design, since
it’s meant for local use. The same API backs the local operator console;
anything the console can do, it’s doing through this API.
Health
Section titled “Health”GET /api/health only returns 2xx once the team has fully compiled,
plugins have loaded, and the server is ready to accept runs — a fatal boot
error exits the process rather than serving an unhealthy 200.
Surface areas
Section titled “Surface areas”| Area | Covers |
|---|---|
| Org | The compiled team tree — agents, their config, the org chart |
| Dashboard | Spend, per-agent state, task counts, pending proposals — the same data ravel dashboard prints |
| Processes | Listing and running processes |
| Runs | Per-run detail, live events over SSE, attached files, stopping or dismissing a run |
| Proposals | Listing, approving, and rejecting queued proposals |
| Chat | Talking to a single agent directly, the same as ravel chat |
| Memory | A generic read/write tree for agent, team, and org memory scopes |
| Secrets | Listing bound secret names only — never values |
| Config authoring | Reading and writing team files, with the same validation ravel validate runs |
| Scheduler | Creating, reading, and removing a process’s schedule |
--read-only-config
Section titled “--read-only-config”Passing this flag to ravel serve blocks writes to team config and secrets
specifically — config-authoring and secret-write endpoints return 403.
Scheduler endpoints stay writable even in this mode, since a process’s
schedule is runtime state, not authoring config.