Blog · Guide · 28 October 2026

Run a scheduled agent with AEGIS: schedules, runs and what you see when one fails

Disclosure: 100monkeys.ai builds AEGIS, so read this guide as a maker's account. It was drafted by one of our AI agents from the public AEGIS documentation, chiefly the Schedules page and the Schedule Tools reference, and reviewed by the company. Every field, route and message below is quoted from those pages. We did not run these calls for this guide, and where the docs leave a step open we say so.

AEGIS by 100monkeys.ai, in beta, is a self-hosted orchestrator that runs autonomous agents in isolated, policy-enforced runtimes. This guide puts one of your agents on a timer, reads back what each fire did, and shows the four outcomes a fire can have, so a run that did not happen is as visible as one that did.

What a schedule is

The docs define it in one sentence: "A schedule starts one of your agents or workflows as you, either once at a time you choose or again and again on a recurrence." Three consequences follow, and each one shapes the steps below.

A schedule is your own object, "never a field of the agent or workflow it runs".
It runs as a person. "A schedule always runs as a person. A service account, or an operator acting for no person, cannot make, change, pause, resume, run or delete one."
Each fire is an ordinary run. "At each fire the orchestrator starts the run exactly as aegis.task.execute or aegis.workflow.run would for you, with the schedule's intent, input and connections."

Step 1. Pick the agent and the timing

Use an agent you have already run once by hand with aegis task execute <AGENT>, so you know what a good run looks like.

Then choose one of two timings. You give exactly one of them.

Once: at, an RFC 3339 time "at least one minute from now and at most a year ahead".
Recurring: recurrence with cron, timezone and jitter_seconds. The cron has five fields (minute, hour, day of month, month, day of week), "no seconds field and no @daily-style shorthand". The time zone is an IANA name and defaults to UTC. Jitter delays each run by a random amount up to that many seconds, at most 3600.

Two limits to plan around: "A schedule runs at most once every 5 minutes", and you may hold at most 25 schedules that are not deleted.

Step 2. Choose what the run may reach

A scheduled run reaches only the connections its profile or contexts name, and "a schedule with neither reaches none of your connections." A schedule carries one or the other, never both. If your agent reads mail or a repository, name the profile now; otherwise the fire will be refused for a missing connection, and the refusal will say so.

Step 3. Create the schedule

There is no aegis schedule shell command in the CLI Reference. You create a schedule with the REST route POST /v1/schedules (scope schedule:write), with the MCP tool aegis.schedule.create, or from the Schedules page in Zaru. The tool takes these arguments, as the reference lists them:

aegis.schedule.create {
  "name": "Morning inbox triage",
  "target_kind": "workflow",
  "target": "email-inbox-triage",
  "intent": "Sort the new mail",
  "input": { "mailbox": "ann@example.com" },
  "recurrence": { "cron": "*/30 * * * *", "timezone": "UTC", "jitter_seconds": 300 }
}

That example is the docs' own schedule. Swap target_kind to agent and target to your agent's name. The answer is {"schedule": {...}} with its state, next_run_at and last_run. Read next_run_at back before you walk away.

Step 4. Fire it once, now

Do not wait for the first scheduled time to learn whether it works. The owner can start one run immediately with POST /v1/schedules/{id}/run or aegis.schedule.run_now. It runs "exactly as a fire starts it: as the owner, with the schedule's target, input, connections or profile, and attachments", and "nothing else changes": the schedule keeps its state and timing.

Step 5. Read the runs

aegis.schedule.runs { "schedule_id": "<id>", "limit": 20 }

The route is GET /v1/schedules/{id}/runs?limit=. Runs come newest first, each with its scheduled_time (null for a run started now), fired_at, outcome, detail and execution (its id, kind and status). Take the execution id to the CLI to read the run itself: aegis task logs <EXECUTION_ID>, with --errors-only when you want only the failures.

Step 6. Know the four outcomes

Every fire is recorded once per scheduled time, so a fire Temporal repeats "answers the first fire's record instead of starting a second run". Each record has one outcome:

started: the run started, and the fire records its execution id.
skipped_overlap: "The run the previous fire started is still running, so this fire starts nothing." Zaru shows it as "Skipped: the last run was still running".
skipped_paused: the schedule is paused.
refused: "The run could not start. The fire records the refusal's sentence, for example a required connection that was not chosen."

A started outcome says the run began, not that it succeeded. The run's own status is in execution.status, and the reason it failed is in its logs.

Step 7. Know what happens when fires keep failing

"When the last three fires of a recurring schedule were all refused, the schedule pauses itself, with the reason 'Paused after three runs could not start: <the last refusal>.'" Read paused_reason on the schedule, fix the cause, then resume with aegis.schedule.resume. A fire missed while the orchestrator restarts "is still made up to 10 minutes late; later than that, the time is skipped."

Step 8. Approvals still apply

A scheduled run acts as you, "so every tool call that waits for your approval in a conversation waits for it in a scheduled run too". In Zaru the request is listed on the Approvals page "From your schedule <name>".

What the docs leave open

A shell command. The CLI Reference lists no schedule subcommand, so self-hosters use the REST routes or an MCP client.
Who "you" is on the local stack. Schedules run as a person and need schedule:write, while the aegis init stack runs with no IAM. The docs do not say how a schedule is owned there; we did not test it.

To put a person between the scheduled agent and anything it sends, read How to give an orchestrator an approval step. To read what a run did, read Reading an AEGIS execution log.

Install AEGIS from 100monkeys.ai