Connections

Agents

Agents are first class: the roast CLI and an Agent Skill, scoped tokens, approvals and the audit log.

An AI agent can use Roastwarden for you: you tell it in your own words, and it does the bookkeeping. "I bought 5 kg of Ethiopia Guji from Sweet Maria's for $46 plus $9.50 shipping" becomes a purchase with its cost per roast; "how did today's roast compare with the last three?" gets the numbers read side by side. Any agent that can run commands in a terminal works: Hermes Agent, Claude Code, Codex, or your own.

It does this through the roast command, which can do nearly everything the dashboard does with your records, and an Agent Skill, a short manual the agent reads when a task needs it: the commands, what each answer means, and the rules (never control the real roaster, report an approval, never work around it). The skill is built into roast, so the two always match.

What you can ask

• Green coffee: a purchase or an order of several coffees with price and shipping, a supplier's product link ("add this, I want 5 lb"), the shopping list, a stock correction after weighing, what your coffee cost this month.
• After a roast: its weight, when first crack really was, notes, a rating, cupping scores.
• Reading roasts: a roast's numbers against its profile and history, two roasts compared, what the roaster's own model predicts, a new bean's first roast.
• Planning and paper: planned roasts for the week, bag labels for today's roasts, a PDF report of a roast, a coffee or a month.
• Looking after it: status, backups, notifications, a support bundle, adding a roaster and checking it.

What it can't do is roast. Live control (setpoint, heater, fan, a profile drive) is yours, at the roaster. A token never controls a physical roaster unless you allow it for that roaster.

Setting up an agent

Three steps: a token for the agent, roast on the agent's machine, and the skill where the agent finds it.

1. Make a token. Settings → Tokens (in the Agents & access group; switch the Agents module on under Settings → Modules if it is not there). Give it a name ("Kitchen assistant") and a preset:

   Preset	For an agent that…
   Read-only	answers questions: reads roasts, profiles, beans and settings, changes nothing
   Inventory	also keeps the coffee's records: beans, stock, orders, the plan, labels
   Roast	also starts roasts and records events (on a roaster you allow)
   Admin	also changes settings and reads the audit log

   Leave Ask me first on: a change the agent makes then waits until you approve it in Settings → Approvals (or from a notification). Copy the token: it is shown once.

2. Get roast onto the agent's machine. The server's own image has it, for the server's architecture:

   docker cp roastwarden:/usr/local/bin/roast ~/.local/bin/roast
   roast --version

   Each release also has roast for Linux x86_64 and aarch64 (the roast CLI).

3. Sign in and install the skill, on that machine, as the user the agent runs as:

   roast login https://roastwarden.example     # paste the token when asked
   roast skill install claude-code             # or: hermes, agents
   roast status                                # the agent can use roast now

   roast login checks the token against the server and keeps the address and token in ~/.config/roastwarden/roast.json, readable only by you, so the agent's shell needs no environment. The token page shows these lines with your server's address filled in.

roast skill install writes the skill where each agent looks:

An agent with no skills folder can still use it: roast skill show prints the skill, to paste into its instructions (an AGENTS.md, a system prompt). After you update roast, run roast skill install again so the skill matches.

Keeping it in hand

• Approvals: with Ask me first, every change waits for your yes. Printing labels and switching a roaster's control on always wait, whatever the token. "Stop asking" on the token page lets a trusted agent's changes through.
• The audit log (Settings → Audit) lists every call each token made, refused ones too.
• Revoke a token on the token page and the agent is out at once; roast logout on its machine forgets the saved token.
• Some things are only yours, with the owner key: managing tokens, signing browsers out, letting a token control a roaster, restoring a backup.

More: the roast CLI (every command), Security (tokens, approvals, the audit log).