---
slug: dashboard/agents
title: Agents in the dashboard
kind: reference
surface: dashboard
summary: Reference for the Agents area of the Aetherfy dashboard — the agent inventory, one agent's deployments and logs, and the YAML configurator — with every status, badge and note it shows, and the afy CLI command and REST route behind each action.
sources:
  - dashboard/src/app/(authenticated)/dashboard/agents/page.tsx
  - dashboard/src/app/(authenticated)/dashboard/agents/[name]/page.tsx
  - dashboard/src/app/(authenticated)/dashboard/agents/[name]/record.tsx
  - dashboard/src/app/(authenticated)/dashboard/agents/[name]/logs/page.tsx
  - dashboard/src/app/(authenticated)/dashboard/agents/configurator/page.tsx
  - dashboard/src/lib/agents/agent-paths.js
  - dashboard/src/lib/agents/agent-lifecycle.js
  - dashboard/src/lib/agents/agent-status-colors.ts
  - dashboard/src/lib/format/status-label.js
  - dashboard/src/lib/agents/agent-failure-codes.js
  - dashboard/src/lib/agents/waiting-push-badge.js
  - dashboard/src/lib/agents/auto-deploy-badge.js
  - dashboard/src/lib/agents/capability-badge.js
  - dashboard/src/lib/agents/last-run.js
  - dashboard/src/lib/agents/deployment-actions.js
  - dashboard/src/lib/health.ts
  - dashboard/src/components/health/DegradedBadge.tsx
  - dashboard/src/components/agents/DegradedAgentInventory.tsx
  - dashboard/src/components/AgentGithubLinkSection.tsx
  - dashboard/src/components/AgentSpawnSection.tsx
---

# Agents in the Aetherfy dashboard

## What the Aetherfy dashboard's Agents area is

The Agents area of the Aetherfy dashboard, at
[app.aetherfy.com/dashboard/agents](https://app.aetherfy.com/dashboard/agents),
has three places:

| Address | What it is |
|---|---|
| `/dashboard/agents` | The inventory: one card per agent, deployed agents first, then the ones not deployed yet |
| `/dashboard/agents/{name}` | One agent's record. Its root is the agent's **deployments**; a second tab holds its **logs** |
| `/dashboard/agents/configurator` | A form that writes an `aetherfy.yaml` for you to copy. It reads and writes no agent |

An Aetherfy agent's configuration lives in its `aetherfy.yaml`, and the dashboard
shows it read-only: memory, runtime, always-on, workspace and schedule change when
you edit the file and deploy (see [the aetherfy.yaml reference](/agents/aetherfy-yaml)).
What the dashboard does change is operational: pausing, archiving, running,
rolling back, and the GitHub link.

## The Aetherfy agent status badge

Every Aetherfy agent card, and the agent's record, carries one status badge followed
by the words `last known`. The badge is the status Aetherfy last recorded, not a
check made when the page loaded — reading an agent's live machines would wake a
sleeping one and bill it. For a live answer use `afy status <agent>` or
[`GET /api/v1/agents/{agent}/status`](/agents/api-lifecycle).

The dashboard prints a status in capitals, with underscores as spaces
(`usage_paused` reads USAGE PAUSED). The values are the ones the
[agent API returns](/agents/api-lifecycle):

| Label | Meaning |
|---|---|
| `pending` | Created; nothing built yet |
| `building` | A deployment is building |
| `deploying` | Built; machines coming up |
| `running` | Serving |
| `failed` | The last deployment failed, or the compute plane lost the agent's app or image (the card says which) |
| `paused` | You paused it. Resume it to serve again |
| `Usage Paused` | Aetherfy paused it because your plan's usage limit was reached; the badge's tooltip says so. Raise your spend limit or upgrade |
| `stopped` | Aetherfy stopped it because the account was suspended |
| `suspended` | Account-level suspension |
| `archived` | Torn down to free its quota slot; configuration and code kept |
| `deleting` | Being deleted |

`last known` is the literal mark beside the badge; its tooltip reads
`Last known state from our records, not a live check`.

## Badges beside the Aetherfy agent status

These appear on an Aetherfy agent card after the status, only when they apply.

| Label | Meaning |
|---|---|
| `Starting once its stop finishes` | You resumed the agent while its previous stop was still finishing. Aetherfy accepted the start and carries it out when the stop completes; the status stays `paused` until then. You can leave the page |
| `Starting on a new machine` | You resumed the agent and its machine's host had no room, so Aetherfy is starting it on a new machine from its current release |
| `Starting` | A start is on its way for a reason this dashboard build does not name |
| `Start dropped` | A start you asked for was not carried out. The line under the badge says why (see the next table) |
| `ALWAYS-ON` | `keep_alive` is on: the agent never sleeps |
| `DOCKER` | A custom-Dockerfile agent. Aetherfy injects no runner, so it does not inspect what the image serves |
| `WEBSOCKET` | Detected from the running app: it serves WebSocket routes as well as HTTP |
| `HTTP` | Detected from the running app: HTTP only. No badge at all means Aetherfy has not observed the app yet |
| `AUTO-DEPLOY` | Linked to a GitHub repository; every push to the tracked branch deploys the agent |
| `AUTO-DEPLOY OFF` | Linked, but pushes are not deploying: the account's GitHub connection was removed, or the tracked branch was deleted. The tooltip says which; the link is kept |
| `PUSH WAITING` | Followed by a commit. A push arrived while a deploy was in progress and deploys when it ends, unless a newer push arrives first — see [GitHub integration](/agents/github) |
| `DEGRADED` | Followed by regions ready out of regions total: a multi-region deploy is still converging in the background |

While a start is on its way, the pause control on the card withdraws it rather
than starting a second one: the latest intent wins, as with
`afy stop` ([pausing and resuming](/cli/agents)).

## Notes under the Aetherfy agent badges

| Label | Meaning |
|---|---|
| `Started on a new machine: a cold start` | The last start recreated the agent's machines on a new host, so it was a cold start rather than a resume. Shown until the agent is paused again |
| `it was archived` | Why a start was dropped: the agent was archived |
| `it was deleted` | Why a start was dropped: the agent was deleted |
| `a spend-limit pause or an account suspension took it` | Why a start was dropped: a billing hold |
| `the agent failed (its app or image was lost)` | Why a start was dropped: the agent failed |
| `its stop never finished, so it was not started` | Why a start was dropped |
| `its start never finished` | Why a start was dropped |
| `it left paused another way` | Why a start was dropped: something else changed the agent's state first |
| `the platform could not carry it out` | Why a start was dropped, for a reason this dashboard build does not know |

The dashboard prints each reason as a sentence, capitalised. The same reasons are
`resume.reason` on the agent ([starting while the previous stop is still
finishing](/agents/api-lifecycle)).

When an Aetherfy agent carries a failure reason, on any status, the card shows
the control plane's sentence for it in a panel under the card, with the `afy`
command that acts on it: `afy deploy <agent>` when the app, image or machine was
lost or every machine is failing its health check (a `running` agent can carry
those last two), and `afy restore <agent>` once a refused restore's cause (the
plan's agent limit, the usage limit, a payment, the plan's settings) is dealt
with. The reasons are the agent's `failure_code` values, listed at
[listing and reading agents](/agents/api-lifecycle).

## The Aetherfy agent card's fields

| Label | Meaning |
|---|---|
| `TYPE` | `SERVICE` or `JOB` |
| `RUNTIME` | The runtime, e.g. `python3.11`, or `dockerfile` |
| `MEMORY` | Memory per machine, in MB |
| `ALWAYS-ON` | `ON` or `OFF` — set `keep_alive` in `aetherfy.yaml` to change it |
| `WORKSPACE` | The agent's workspace; absent when it has none |
| `SCHEDULE` | The 5-field cron expression, evaluated in UTC — only on a scheduled task |
| `NEXT RUN` | When the schedule fires next, in your local time, or `Paused` |
| `LAST TICK` | Shown only when the schedule's last decision did not start a run: `skipped` or `missed`, with the reason as its tooltip |
| `LAST RUN` | The newest run's state and age, or `Never` |
| `ALLOWED WORKERS` | The task agents this service may spawn (`allowed_workers` in `aetherfy.yaml`) |
| `SPAWNABLE BY` | The services whose `allowed_workers` names this task |
| `ID` | The first characters of the agent's id |

A run's state reads like a deployment's (next section): `completed` for a run that
finished, `failed` for one that did not.

When a scheduled run was blocked by a billing limit, the card shows
`Scheduled runs are blocked: plan limit reached.` until a later run fires.

## The Aetherfy agent card's actions

Each Aetherfy action in the dashboard is a call to the control plane that the CLI
and the REST API make too.

| Action | Shown when | CLI | REST |
|---|---|---|---|
| **NEW_AGENT** — registers an agent: name, runtime, type, description, workspace | Always | `afy create` ([creating an agent](/cli/agents)) | `POST /api/v1/agents` ([lifecycle](/agents/api-lifecycle)) |
| Pause / resume | Deployed and `running`, `paused` or `failed` | `afy stop` / `afy start` | `POST /api/v1/agents/{agent}/stop`, `/start` |
| Archive | Deployed and `running` or `paused` | `afy archive` | `POST /api/v1/agents/{agent}/archive` |
| Restore | `archived` | `afy restore` | `POST /api/v1/agents/{agent}/restore` |
| **RUN NOW** — one run, no payload | Deployed and `running` or `stopped` | `afy run` ([on demand](/cli/agents)) | `POST /api/v1/agents/{agent}/run` ([runs](/agents/api-runs)) |
| Pause / resume the schedule | A scheduled task | `afy schedule pause` / `resume` | `POST /api/v1/agents/{agent}/schedule/pause`, `/resume` |
| Run history — the last runs, each linking to its logs | Deployed | `afy runs` | `GET /api/v1/agents/{agent}/runs` |
| Logs | Always | `afy logs` ([logs](/cli/logs)) | `GET /api/v1/agents/{agent}/logs` |
| **MORE → GITHUB LINK** — link, re-link or unlink a repository | Always | `afy github link` / `unlink` ([GitHub](/cli/github)) | `POST` / `DELETE /api/v1/agents/{agent}/github` |
| **MORE → DOWNLOAD YAML** — the agent's current configuration as `aetherfy.yaml` | Always | `afy pull` | `GET /api/v1/agents/{agent}/yaml` |
| Delete — type the agent's name to confirm | Always | `afy delete` | `DELETE /api/v1/agents/{agent}` |
| **DEPLOYMENTS** — opens the agent's record | Always | `afy deployments` | `GET /api/v1/agents/{agent}/deployments` |

Archiving and restoring are explained at [Running and managing agents](/agents/managing);
a restore refused by the plan's agent limit opens an upgrade prompt rather than an error.

## The Aetherfy agent record: deployments

An Aetherfy agent's record, `/dashboard/agents/{name}`, opens on its deployments:
one row per version, newest first, with `VERSION`, `STATE`, `REGIONS`,
`CREATED`, `DEPLOYED` and `OPERATION`. Expanding a row adds its deployment id,
image size, queue position, start time, regions ready and — for a failed build —
`BUILD OUTPUT`, the tail of the build log. The page re-reads itself while a
deployment is in flight. Below the versions, the record lists the collections the
agent was observed reading or writing.

| Label | Meaning |
|---|---|
| `queued` | Waiting for a builder |
| `building` | Building the image |
| `deploying` | Built; machines coming up and health-checked. The previous version keeps serving meanwhile |
| `active` | Serving. The serving row is also marked `→ CURRENT` |
| `failed` | Did not deploy. The expanded row carries the reason |
| `superseded` | A newer deployment replaced it |
| `rolled_back` | Replaced by a rollback to an earlier version |
| `NO DEPLOYMENTS YET` | The agent has never been deployed |

The states are the ones [the deployments API](/agents/api-deployments) returns, printed in
capitals with underscores as spaces, the same way as an agent's status (`rolled_back` reads
ROLLED BACK).

| Action | CLI | REST |
|---|---|---|
| Roll back to a version — re-deploys that version's image, or rebuilds it from its stored code when the image is gone | `afy rollback <agent> <version>` ([rollback](/cli/deploy)) | `POST /api/v1/agents/{agent}/deployments/{version}/rollback` |
| **Redeploy** a version — rebuilds that version's code with the current secrets | `afy redeploy <agent> <version>` | `POST /api/v1/agents/{agent}/deployments/{version}/redeploy` |

Each is offered only on the versions the API says it can do it for. Both ask for
confirmation and both create a new version; see [Rollback](/agents/rollback) and
[Secrets](/agents/secrets) for when to pick which. A rollback or redeploy refused
by your plan's current limits opens an upgrade prompt.

When the agent is `archived`, a line above both tabs says its app was destroyed,
so nothing in the list is serving, and that restoring it is the way back.

## The Aetherfy agent record: logs

The `LOGS` tab of an Aetherfy agent's record shows its log lines with `TIME`,
`LEVEL`, `STREAM` and `MESSAGE`, filtered by time window, text search, level
(`INFO`, `WARN`, `ERROR`, `DEBUG`, `SYSTEM`) and stream (`stdout`, `stderr`,
`system`). `FOLLOW` polls for new lines. Opened from the run history, it is scoped
to one run. It is the same data as `afy logs` ([logs](/cli/logs)) and
`GET /api/v1/agents/{agent}/logs` ([runs and logs](/agents/runs-and-logs)).

| Label | Meaning |
|---|---|
| `NO LOGS FOUND` | Nothing matches the filters in the window |
| `LIVE` | Following new lines |

## The Aetherfy YAML configurator

The configurator at `/dashboard/agents/configurator`, reached from **CONFIGURATOR**
on the inventory, builds an `aetherfy.yaml` from a form — name, type, runtime,
regions, memory, idle timeout, always-on, spawning, a schedule with a preview of
its next runs, workspace and GitHub dependencies — and gives you the text to copy.
It registers, deploys and changes nothing; deploy the file with `afy deploy`.
`afy init` writes a starting file from the terminal ([afy init](/cli/deploy)), and
[Scheduled tasks](/agents/scheduled-tasks) covers the schedule fields.

## When the Aetherfy control plane cannot be reached

If the Aetherfy control plane does not answer, the inventory falls back to what
Aetherfy has stored and says so:

| Label | Meaning |
|---|---|
| `LAST-KNOWN INVENTORY` | The banner: this list is read from stored records |
| `ON RECORD —` | Followed by how many agents are on record |
| `NO AGENTS ON RECORD` | The stored records hold no agent |

Every action is disabled in this state, with the reason beside it: the control
plane carries out every action on the page. The agents themselves are not
affected.

## What the Aetherfy dashboard does not do for agents

| Not in the dashboard | Where instead |
|---|---|
| Deploy new code | `afy deploy` ([deploying](/cli/deploy)), or a push to a linked repository ([GitHub](/agents/github)) |
| Rename an agent | `afy rename` only — it also rewrites the `name:` in your local `aetherfy.yaml`, which a browser cannot reach ([renaming](/cli/agents)) |
| Change memory, regions, always-on, idle timeout or the schedule | Edit `aetherfy.yaml` and deploy |
| Change an agent's workspace or description | `afy update` ([updating](/cli/agents)) or `PATCH /api/v1/agents/{agent}` |
| Cancel a queued or building deployment | `afy cancel` or `POST /api/v1/agents/{agent}/deployments/{version}/cancel` |
| Run with a payload | `afy run --payload` |
| Spawn a worker | `POST /api/v1/agents/{agent}/spawn` from your service ([spawning](/agents/api-runs)) |
| Read live machine state | `afy status` or `GET /api/v1/agents/{agent}/status` |
| Manage an agent's secrets | The [Secrets area](/dashboard/secrets) |