Running and managing agents

Running an Aetherfy agent on demand

Any deployed top-level agent on Aetherfy can be run on demand, whether or not it has a schedule. A type: job agent runs its entrypoint; a type: service agent is sent one request to its POST /aetherfy/run route, described on /agents/task-contract. This is the way to test a task before trusting it to a cadence, and the way to re-process a window after a failure.


afy run nightly-report

Pass input as inline JSON, and block until the run finishes:


afy run nightly-report --payload '{"date":"2026-07-17"}' --wait

Or read the input from a file:


afy run nightly-report --payload-file ./input.json --wait

Flag	Short	Effect
`--payload`	`-p`	Inline JSON input. Must be a JSON object.
`--payload-file`	`-f`	Read the JSON input from a file. Must be a JSON object.
`--wait`	—	Block until the run ends. Exits 0 on success, 1 on failure.

--payload and --payload-file are mutually exclusive — pass one or neither, never both.

Your code reads that input by fetching it from the Aetherfy API rather than receiving it as an argument; see /agents/task-contract.

--wait exits 0 on success and 1 on failure, which makes afy run usable directly as a CI step that fails the pipeline when the task fails. It stops watching after 30 minutes, but the run itself keeps going — check how it ended with afy runs nightly-report.

A manual run on Aetherfy is entirely separate from the schedule. It does not consume an occurrence, does not shift the next scheduled fire, and is not recorded against the schedule.

Errors you can get back:

Error	HTTP	Meaning
`AGENT_NOT_DEPLOYED`	422	The agent has no deployment to run
`AGENT_RUN_INELIGIBLE_STATE`	409	The agent’s current state does not permit a run
`AGENT_RUN_CONCURRENCY_LIMIT_EXCEEDED`	429	The account already has as many task runs in flight as its plan allows. Wait for some to finish; see Limits

A manual run is never refused because the agent is already running: the new run gets a machine of its own. See The task contract.

Pausing and resuming an Aetherfy schedule

Pausing stops scheduled runs without touching aetherfy.yaml and without redeploying. It is the right tool for a temporary stop — during an incident, a migration, or a downstream outage.


afy schedule pause nightly-report
afy schedule resume nightly-report

Behaviour	Detail
Idempotent	Pausing a paused schedule, or resuming a running one, is not an error
Manual runs still work	`afy run` is unaffected by a pause
No back-fill on resume	The next run is the next future occurrence
No schedule set	Both commands return 422 `AGENT_SCHEDULE_NOT_SET`

The no-back-fill rule is the one to internalise. A schedule paused for a week does not fire a week’s worth of runs the moment you resume it — Aetherfy picks up at the next future occurrence and the paused occurrences are simply gone. If the work matters, run it manually to catch up.

There is no afy schedule set command on Aetherfy. Schedules are declared in aetherfy.yaml and applied by deploying. To change the expression, edit the file and deploy; to remove it entirely, deploy schedule: null. See /agents/scheduled-tasks.

Note that deploying schedule: null clears any pause you had set along with the schedule itself.

Overlaps and missed windows on Aetherfy

Aetherfy drops occurrences that cannot run. It never queues them.

Situation	What Aetherfy does
Overlap — the previous run is still in flight when the next is due	The due occurrence fires. A `type: job` agent’s busy machine is left to finish its run, and the new run gets a machine of its own; a `type: service` agent serves it as another request.
Runs-in-flight limit — the account already has as many task runs in flight as its plan allows	The due occurrence is skipped and recorded with `AGENT_RUN_CONCURRENCY_LIMIT_EXCEEDED`, the code a manual run or a spawn is refused with. A service’s occurrence is never skipped this way.
Missed window — the occurrence could not be evaluated within a 5-minute late-fire grace	It is recorded as missed, and the schedule moves to the next future occurrence. No catch-up burst.

Nothing waits in line behind a run. A task that hangs does not hold its schedule: its run ends at the 60-minute run backstop, and each occurrence before then starts a run of its own, until the account’s runs-in-flight limit skips the rest. A schedule that fires more often than its runs finish therefore widens rather than queues — size the schedule to the run.

The trade-off is explicit: Aetherfy does not guarantee that every occurrence runs. If you need that, a schedule is the wrong instrument — write the work into a durable queue and let a task drain the queue on each fire. That way a skipped fire costs you latency, not data.

Last-fire badges on Aetherfy

Aetherfy records what happened at the most recent occurrence as a badge. A badge describes the fire, not the outcome of the run it may have started.

Badge	Meaning
FIRED	A run was started — check the run history for how it ended
SKIPPED	The account was at its runs-in-flight limit, so this occurrence did not fire. `afy status` prints the recorded reason, `AGENT_RUN_CONCURRENCY_LIMIT_EXCEEDED`, next to it
MISSED	The occurrence could not fire — for example the late-fire window elapsed, or a plan limit blocked it

Keep the two ideas separate: FIRED tells you Aetherfy started a run, and says nothing about whether that run succeeded. For success or failure you want the run history, at /agents/runs-and-logs.

Skipped and missed occurrences never create a run, so they cost nothing.

How Aetherfy billing affects scheduled runs

When an account is over its usage limit, or has an unresolved payment issue, Aetherfy records scheduled occurrences as missed instead of firing them.

Nothing is lost and nothing needs re-enabling afterwards. Raise the limit, upgrade the plan, or settle the payment, and the next occurrence fires normally on its own. Missed occurrences are not backfilled, so if the skipped work matters, run it manually with afy run.

Manage all of this at https://app.aetherfy.com/dashboard/settings/billing .

A schedule on Aetherfy adds no charge of its own. You pay for the compute the runs actually consume.

Stopping, archiving, and deleting an Aetherfy agent

These three act on the agent itself rather than on its schedule, and the difference between them is what happens to your plan’s quota.

Command	What it does	Reversible with	Holds a quota slot
`afy stop <name>`	Pauses the agent — every machine stops and Aetherfy will not re-wake it on incoming traffic	`afy start <name>`	Yes
`afy archive <name>`	Destroys the underlying app to free the plan quota slot, while preserving the configuration and the stored code bundle	`afy restore <name>`	No
`afy delete <name>`	Removes the agent	—	No


afy stop nightly-report
afy start nightly-report
 
afy archive nightly-report
afy restore nightly-report
 
afy delete nightly-report

Choose by intent. Stopping is for a short pause where you want the agent instantly available again — but it still occupies a slot in your plan’s agent quota, so it does not help you deploy something else. Archiving is what frees that slot; restoring is subject to a fresh plan-quota check at restore time, so an archived agent is not guaranteed to come back if you have filled your quota in the meantime.

To stop only the scheduled runs while leaving the agent deployed and reachable, use afy schedule pause instead of any of these.