Concepts and vocabulary
What Caldera is and is not, the one rule everything is built around, the parts and how they talk, the words used on every other page, roles, activation, and what Caldera keeps.
What Caldera is
Caldera shows a workspace what its agents are doing and lets admins steer them. For every agent a person sees:
- a level (healthy, notice, warning, fault) and a state line,
- what is running now,
- gauges (a fraction used, for example "week 52 % of the quota"),
- health items, and recent runs with cost, tokens, models and subjects,
- panels the agent declares itself (lists, tables, key-value pairs, text),
- the agent's settings as a form, within bounds the agent sets,
- the history of commands and the agent's answers.
An admin can pause, resume, ask for a run now, change settings, ask for a log, and, for an agent installed from a blueprint, move the agent to another version.
What Caldera is not
- Not a scheduler and not a work source. Caldera gives an agent no tasks, prompts or goals. An agent decides on its own what to work on and when.
- Not a way into an agent's machine. Caldera never connects to an agent. Nothing on the agent's machine listens.
- Not an alarm. Showing an agent as silent is information. An agent keeps its own watcher and its own notification channel.
- Not a document product. Caldera has no pages, blocks or search.
The fixed rule
The operation of an agent must never depend on Caldera.
In practice:
- Caldera is not in an agent's control path. An agent never waits for Caldera, never asks it for permission and never fetches work from it.
- The reporter is a separate process with a bounded failure: a timeout, a log line, the next attempt. Caldera being down, slow or answering nonsense affects the reporter and nothing else.
- Authoritative state lives on the agent's machine: pause, limits, schedule and settings. Caldera stores a copy of the last report, for display. Losing Caldera's data loses history, never configuration.
- There is no state that only Caldera can undo. Everything a command can do is also reachable and reversible on the machine. A command type whose effect cannot be undone locally is not part of the protocol.
- A command is a wish. The agent checks it against its own hard bounds and may refuse. A refusal is a normal answer.
- Caldera does not replace an agent's own alerting.
For blueprints the rule reads: setting an agent up may need Caldera, running it never does. If Caldera is down, nobody can install a new agent; no running agent notices.
The check. Point the reporter at an unreachable host. The agent must run a scheduled run to the end, and a pause set before the outage must be lifted through the agent's own channel. This belongs to connecting every agent; the procedures are in Connecting an agent.
The parts
| Part | What it is |
|---|---|
| The Caldera app | A web app at app.calderaapp.io. An overview of all agents, one page per agent (overview, runs, settings, commands) and the blueprint screens. It refreshes every 10 seconds. |
| The server | Answers the app, receives the agents' reports and serves the runtime caldera.pyz and everything the install dialog shows. |
The runtime caldera.pyz |
A Python program on the agent's machine. It reports, applies commands and updates, and starts and stops the agent. See the runtime. |
| The agent | The program that does the actual work. Caldera never decides what it does. |
| An own reporter | Instead of the runtime, an agent may report on its own with a few lines of code. See Connecting an agent. |
What travels, in which direction
| Direction | What |
|---|---|
| Agent to Caldera | The whole current state in a report every interval; logs when asked; bundle downloads. |
| Caldera to agent | Only the answer to a report: pending commands, the interval, and the versions Caldera wishes (desired, runtime_desired). |
| Person to Caldera | The app, with a signed-in session. The routes the app uses accept no personal token. |
| Installer to Caldera | caldera init: preview and redeem of a one-time code, with no token at all. |
Vocabulary
| Term | Meaning |
|---|---|
| Agent | An entry in Caldera with its own token. It stands for a program that reports. It belongs to a workspace. |
| Report | The agent's whole current state, sent every interval. Caldera shows what the last report said. |
| Command | A wish from an admin, carried in the answer to a report: pause, resume, run_now, set, log. A closed set. |
| Ack | The agent's answer to a command, sent in a later report: ok or not, and a message. |
| Control | A button the agent offers: pause, resume, run_now. Unknown ones are dropped. |
| Gauge | A figure from 0 to 1 with an optional mark, for example quota used against a limit. |
| Panel | Something only this agent has, in one of four shapes: list, table, kv, text. Never markup. |
| Setting | A field of the form the agent declares, with a type (percent, number, bool, datetime, text, select) and bounds. The agent enforces them. |
| Blueprint | A prepared agent: a named, versioned bundle of files plus one manifest, caldera.agent.yaml. See Blueprints. |
| Version | One immutable release of a blueprint (semantic version). A draft can change until it is published; a published version never changes. |
| Catalog | The blueprints Caldera ships itself: read-only, the same in every workspace, one version each. |
| Install code | A one-time code (caldera_inst_..., valid once for 15 minutes) that sets up one agent on one machine with caldera init. |
| Binding | Access an agent needs to one of the suite's other products. At install Caldera creates a bot in the workspace for it and hands the agent its token. |
| Bot | A workspace member without a login, owned by a person and capped at that person's role. Never a seat. |
| Desired version | What Caldera wishes the agent to run. Sent in the answer to a report as desired. |
| Applied version | What the agent says it runs now. The one that works. |
| Installed version | What the install code brought. Never changes after the install. |
| Runtime | caldera.pyz: the program that sets an agent up and then runs and reports for it. |
| Adapter | One command an agent provides so that the runtime can steer an agent that keeps its own processes. See adapter mode. |
| Hold | The runtime's memory of a version it rolled back from or refused. It is not applied again until Caldera names another version. |
Levels, silence and attention
- Every health item and the state have a level:
ok,info,warn,bad. An unknown level reads asinfo. - The agent's level is the worst of its state and its health items.
- An agent that has not reported for three intervals, at least two minutes,
is shown as silent and as
bad, whatever it last said. - While somebody has an agent's page open, Caldera asks the agent to report every 10 seconds instead of its configured interval, so a command is collected within seconds. The agent clamps the interval to its own range.
Roles and permissions
The workspace role decides. There is no per-agent access list.
| Action | owner / admin | member | guest |
|---|---|---|---|
| See agents, runs, settings, command history, blueprints | yes | yes | no |
| Send commands (pause, resume, run now, settings) | yes | no | no |
| Fetch and read logs | yes | no | no |
| Create, rename, delete an agent; rotate its token | yes | no | no |
| Create, upload, publish, delete blueprints and versions | yes | no | no |
| Issue an install code; set a desired version; update the runtime | yes | no | no |
Steering is admin-only because a setting on an autonomous agent is often a cost decision, and a log is content, not metadata.
Activation
Caldera is a product of its own with its own address. A workspace has to be
activated for Caldera; without it a person gets 403 product_not_activated
and an agent's report gets 403 too. Activation is not something a workspace does
for itself, and there is no self-service sign-up for Caldera yet.
An agent token is not a way into anything else. It acts as no one. It reaches the report, log and bundle routes for its own agent and nothing else.
What Caldera keeps
| Data | Kept |
|---|---|
| The last report of each agent | Until the next one replaces it |
| Runs | The newest 2000 per agent; the same run id overwrites |
| Commands, and the logs they carry | 30 days. A log is agent content; only admins of the workspace can read it. |
| Blueprint archives | Until the version is deleted (a draft) or the blueprint is |
Everything an agent sends is data
Caldera draws every string as text, never as markup. Links are kept only if they
start with http:// or https://; anything else is dropped and the title
stays. Strings and lists longer than their caps are cut, not refused. An agent
never ships code or markup into Caldera.
What Caldera does not do
- Assign work to an agent.
- Call into an agent.
- Notify when an agent goes silent. Agents keep their own alerting.
- Hold third-party credentials (mail, calendar, chat tokens). They stay on the agent's machine.