How Mirtel works
Most tools tell you what your code did. Mirtel starts from what should have happened, then checks. That's how she catches the run that never started: there's no error to see, just a gap where a report should be.
The contract
Every agent has a contract, written by you, in your words:
- Name and platform, so you know which one it is.
- Goal: what it's for.
- Schedule: the days and times it should run, in your timezone, for example weekdays at 08:00 London time.
- What success looks like: a sentence, and optionally a minimum number of items (articles found, invoices chased).
- Grace period: how long after the scheduled time before a run with no report counts as Missed. The default is 30 minutes.
From the schedule, Mirtel works out every run you should expect. She doesn't store a list of misses. She works the whole ledger out again from the contract and the reports every time you look. So if you change a contract, say by raising the minimum items, she re-judges the past with the new rules.
An agent with no schedule is fine too. Its reports are listed as they arrive, and it can never be Missed.
The six verdicts
Each expected run gets one of these:
| Verdict | What it means |
|---|---|
| Done | The agent reported done, with at least the minimum items if you set one. |
| Empty | The agent reported empty, or reported done with fewer items than the minimum. It ran, but brought nothing home. |
| Failed | The agent reported failed. It should say why. |
| Needs you | The agent reported needs_you. It's stuck on a decision only you can make. |
| Missed | No report arrived by the scheduled time plus the grace period. |
| Due | Not yet. The run is coming up, or it's still inside its grace period. |
Mirtel only counts items. She shows your success sentence next to each run, but she doesn't read the output and grade it.
Early, late and retried runs
- A little early is fine. Each expected run owns a window that opens 10 minutes before its time and closes 10 minutes before the next one. A report anywhere in that window belongs to that run.
- Late still counts. A run that reports after the grace period still counts for the slot it was late for. It's just marked late.
- The latest report wins. If an agent fails, retries and then succeeds in the same window, the run counts as Done.
- Nothing is thrown away. A report that doesn't fit any window, such as one from an agent with no schedule, is listed as an off-schedule run.
- No backlog on day one. Mirtel only expects runs from the moment an agent is active until it's revoked. A new agent never starts with a pile of Missed.
Reports can say when the run started, up to 24 hours back, so an agent can report a little after the fact. They can't rewrite older history.
Your list, and alerts
The dashboard keeps a Needs your attention list: every Missed, Failed, Empty or Needs-you run from the last 7 days that you haven't marked as seen, plus any agents waiting for your approval. Marking one as seen takes it off the list. It stays in the ledger.
If you set a webhook (the MIRTEL_WEBHOOK_URL setting), Mirtel sends each new problem to it once. That works with Slack incoming webhooks, n8n, Zapier and the like. She checks every minute, because a missed run doesn't send anything to react to. A webhook is the only alert channel for now.
Mirtel's four promises
| Promise | How she keeps it |
|---|---|
| One key per agent | Every agent has its own key, and the key is also the agent's link, /r/ followed by the key. Revoking one agent touches nothing else. Rotating gives the agent a new link and the old one stops working. |
| You approve every agent | An agent can only sign itself up with a one-time token you made, which expires after 15 minutes by default. Until you approve it, its reports are refused. |
| Watches, never touches | Mirtel never calls your agents and stores no platform passwords. The only thing she sends out is the optional alert webhook. |
| Your workspace only | Which workspace a request belongs to always comes from its key, never from anything the caller says. |
Mirtel also keeps only a fingerprint (a hash) of each key, never the key itself. That's why she can show you a link only once.
Running your own Mirtel
Mirtel needs a server that stays running, with a disk it can write to. Put it behind HTTPS, because the link carries the key. Set MIRTEL_PUBLIC_URL to your public address (for example https://mirtel.example.com) so every link points at the right host. Without it, Mirtel guesses from each request, and behind some proxies that guess comes out as plain http:// or the wrong host name.
What she doesn't do yet
Some things you may have seen on the front page aren't built yet: AI grading of what agents produce, AI summaries, email or WhatsApp reports, accounts and teams. Schedules are days and times only, with no cron expressions or "every 2 hours". Until those exist, the docs don't pretend they do.