Caldera documentation
Caldera shows a workspace what its autonomous agents are doing, and lets admins steer them. An agent is any program that works on its own, for example one that reads a task board, works on cards with Claude Code and writes the result back. Caldera shows each agent's state, health, quota gauges, runs with cost, and panels the agent declares itself. Admins can pause, resume, ask for a run now, change a setting within the agent's own bounds, and ask for a log.
Read this first
An agent never depends on Caldera. Caldera is not in an agent's control path. If Caldera is down, slow or answering nonsense, every agent keeps working, every pause can still be set and lifted on the agent's own machine, and the only thing missing is the picture. Everything on these pages follows from that rule. See Concepts and vocabulary.
Caldera never connects to an agent. The agent calls out, over HTTPS, at a fixed interval. Commands travel back in the answer to a report. Nothing on the agent's machine listens.
This documentation is for people who connect agents to Caldera and run them.
The app is at https://app.calderaapp.io. A workspace has to be activated for
Caldera before its agents can report; without activation Caldera answers 403.
Where to start
| You want to | Read |
|---|---|
| Understand the parts and the words | Concepts and vocabulary |
| Get an agent into Caldera, and choose between the two ways | Connecting an agent |
| Write your own reporter | The agent protocol |
| Run an agent under the runtime | The runtime caldera.pyz |
| Package an agent so one command sets it up | Blueprints and The manifest |
| Connect an agent that keeps its own processes | Adapter mode and its contract |
| Update, pin, roll back, pause, rotate a token, or fix a problem | Operating agents |
| Know what the Claude account line on an agent's page means | The Claude account hint |
The two ways to connect an agent
- An own reporter. A few lines in any language that POST the agent's state to Caldera. The agent keeps running exactly as before.
- A blueprint under the runtime. A prepared, versioned bundle that one
command,
caldera init, sets up on a machine. The runtimecaldera.pyzthen runs the agent, reports for it, applies updates with a health check and rolls back by itself when a new version is worse.
A third mode, the adapter, is the runtime for an agent that keeps its own processes: the runtime starts and stops nothing and asks one command the agent provides.
Machine-readable schemas
The JSON Schemas for the manifest and the adapter answers are published next to the pages:
caldera.agent.schema.json, the manifestadapter-status.schema.jsonadapter-settings-get.schema.jsonadapter-log-list.schema.jsonadapter-answer.schema.json
Caldera has no public REST API for scripts: the routes the app uses need a signed-in session. The agent protocol is the API an agent speaks.