Runs and logs

Listing the runs of an Aetherfy agent

A run on Aetherfy is one ephemeral execution of a type: job agent. List recent runs newest-first:

afy runs nightly-report
afy runs nightly-report --limit 50

The default limit is 20 and the maximum is 100.

The listing shows six columns:

Aetherfy lists only runs with a trigger source of cron or manual. Runs started by a parent agent are excluded from this listing — they belong to the parent’s history instead.

What the Aetherfy runs API returns

The equivalent Aetherfy REST call is:

GET /agents/{id}/runs

Each row Aetherfy returns carries these fields:

The two machine fields are null on a run of a type: service agent, which is a request to a machine the service already has rather than a machine of its own. Its duration_seconds runs from the moment that machine accepted the run to the moment the run’s outcome was reported.

release_version is the version of the release a run executed — the number afy deployments and afy rollback use, not the run’s own place in the agent’s deployment history. A type: job run executes the release whose image it was started from; when that image had been lost and the run rebuilt it, the release whose stored code it was rebuilt from. A type: service run executes the release the machine that took it was serving. It is null for a service run no machine accepted, and for runs recorded before Aetherfy kept it.

The agent record carries its most recent entry of this list as last_run, which is what afy status prints as Last run.

before is a keyset cursor rather than an offset, so paging backwards through a long history stays correct even as new runs arrive.

Run and deployment states on Aetherfy

Aetherfy uses one state vocabulary for both deployments and runs. Four of the states are terminal — once a record reaches them it will not change again.

completed applies to runs, which end by design. A long-lived service deployment that is working sits at active and stays there until a newer deployment supersedes it.

A run is active only once a machine has accepted it. Until then it is deploying, and a run that no machine accepts within 2 minutes of Aetherfy starting to hand it over is failed with “The run was never accepted by a machine, so your code was not executed.” Your code did not start, so there is nothing of yours to debug.

A run that stalls before that point, still queued, building or deploying 7 minutes after it was created, is also recorded as failed, with a reason naming the step that never finished. The 7 minutes run from when the run was created, so time the run spends queued behind other deployments counts toward them (see /agents/task-contract). Aetherfy checks for stalled runs every 5 minutes, so such a run can show its pending state for up to 5 minutes past those 7 minutes before it is failed.

What decides completed versus failed for a run is the process exit code — see /agents/task-contract.

Agent status values on Aetherfy

An agent has its own status, separate from the state of any individual deployment or run.

usage_paused is the one to recognise on sight: the agent is not broken and nothing needs repairing in your code. Raise the limit or settle the payment at https://app.aetherfy.com/dashboard/settings/billing  and the agent resumes.

Retrieving logs from Aetherfy

Everything an agent writes to stdout and stderr becomes its logs on Aetherfy.

afy logs nightly-report

Scope the output to a single run, using a Run ID from afy runs:

afy logs nightly-report --run 9f3a1c72-5b8e-4d61-a0f4-7c2e9b5d3a18

Combined:

afy logs nightly-report --tail 200 --since 1h --level ERROR,WARN --stream stderr

One caveat worth knowing before you debug against it: on Aetherfy --follow polls, and it ignores both --tail and --since. It also does not honour JSON output. Use --follow to watch what happens next; use --tail and --since to look at what already happened.

Log record fields on Aetherfy

Every log record Aetherfy stores carries:

The system stream holds lines Aetherfy itself emits about the machine, as distinct from your program’s own output on stdout and stderr.

How Aetherfy reads a line’s level

Your output carries no level field, so Aetherfy reads one from the start of each line, and only from there. A level is recognised when the line begins — after an optional timestamp such as 2026-09-17 12:40:36,123 or [2026-09-17T12:40:36Z] — with one of DEBUG, INFO, WARN, WARNING, ERROR, CRITICAL, FATAL or TRACE, written in one of three ways:

WARNING is stored as WARN, CRITICAL and FATAL as ERROR, and TRACE as DEBUG. A line with no level at its start takes its stream’s: INFO on stdout, ERROR on stderr. The word anywhere else is part of the message — No Error found on stdout is INFO — and so is a capitalised word opening a sentence, such as Error handling is on. This is best-effort parsing: to be sure of a line’s level, print it in one of the three forms above.

What Aetherfy does not record for you

Aetherfy logging is plain stdout/stderr capture, and nothing more. It does not auto-instrument calls your agent makes to model providers — there is no automatic capture of prompts, completions, token counts, latency or tool calls from an OpenAI, Anthropic or other SDK running inside your agent.

If you want that, log it yourself. A print() or logger.info() around the call lands in exactly the same place as the rest of your output and is searchable with afy logs --level:

import json, time
 
started = time.monotonic()
response = call_your_model(prompt)
print(json.dumps({
    "event": "llm_call",
    "model": "your-model-id",
    "elapsed_ms": round((time.monotonic() - started) * 1000),
    "prompt_chars": len(prompt),
}))

Keep the per-line and per-deployment limits below in mind if you log full prompts — they are easy to exceed.

Log limits and retention on Aetherfy

Aetherfy caps log volume in several dimensions. Logs are an operational aid, not a durable data store — write anything you need to keep to a real destination.

When an agent exceeds the per-line or volume caps, the Aetherfy log forwarder backs off and emits a marker in the stream so the gap is visible rather than silent:

[SYSTEM] N log line(s) dropped

If you see that marker, the agent is logging faster than Aetherfy will accept. Reduce per-line size or log volume — a very large payload dumped per iteration is the usual cause.

A run’s output is read to its last line before the run’s outcome is reported. If your code starts a background process that keeps the run’s output open after your main process exits, Aetherfy stops reading 2 seconds later, ends the run, and says so in the run’s log:

[SYSTEM] output from a process run <run id> left running was cut off 2s after the run ended

Anything that background process prints after that point is not captured.

While a run is in flight, Aetherfy keeps its machine from being suspended. If that cannot be established after several attempts, the run’s log says so once, at ERROR, and Aetherfy keeps trying:

[SYSTEM] Aetherfy run <run id> could not hold its machine awake: 5 attempts in a row did not connect (last: <reason>). The provider may suspend the machine mid-run; still retrying.

A long run that stops partway with this line in its log was most likely suspended by the platform, not ended by your code.