aetherfy.yaml
What aetherfy.yaml is on Aetherfy
aetherfy.yaml is the single declarative file that describes how an Aetherfy
agent runs. It is required — a deploy without it fails. It must sit at the
root of the archive you upload, or at the agent’s root path in a linked GitHub
repository. A deploy without it is refused with this sentence:
Missing required aetherfy.yaml. Add it beside your code with at least `runtime:`; every field it leaves out takes its default.An upload answers it as HTTP 422 DEPLOYMENT_CONFIG_PARSE_ERROR; a push to a
linked repository records a failed deployment naming the repository, commit,
branch and path, and fails the commit’s check (see GitHub).
Aetherfy accepts four filenames, and uses the first one it finds in this priority order:
| Priority | Filename |
|---|---|
| 1 | aetherfy.yaml |
| 2 | aetherfy.yml |
| 3 | .aetherfy.yaml |
| 4 | .aetherfy.yml |
A minimal valid file for Aetherfy is one field:
runtime: python3.12Autocomplete and checks in your editor
Start the file with this line, and an editor that speaks the YAML language server (VS Code with the Red Hat YAML extension, the JetBrains IDEs, Neovim with yaml-language-server) completes every field, shows its description on hover, and underlines an unknown field or a value Aetherfy would refuse, as you type:
# yaml-language-server: $schema=https://docs.aetherfy.com/aetherfy-yaml.schema.json
runtime: python3.12The line is a comment, so Aetherfy ignores it. afy init writes it as the
first line of every file it creates, and the configuration Aetherfy exports
(below) starts with it. The schema it names is the published
aetherfy.yaml schema, the same one these docs are
checked against.
A fuller example using most of the surface:
runtime: python3.12
type: job
entrypoint: main.py
memory_mb: 512
idle_timeout_minutes: 5
keep_alive: false
schedule: "0 3 * * *"
regions:
- us-east-1
github_dependencies:
- myorg/[email protected]A runtime: dockerfile agent lists the paths its process writes, because the
agent runs as an unprivileged user:
runtime: dockerfile
type: service
writable_paths:
- /data
- /var/cache/myappEvery field Aetherfy accepts in aetherfy.yaml
| Field | Type | Required | Default | Allowed values | Notes |
|---|---|---|---|---|---|
runtime | string | yes | — | python3.11, python3.12, python3.13, python3.14, python3.15, node22, node24, node26, node22-ts, node24-ts, node26-ts, bun, dockerfile | Fixed by the agent’s first release that goes live. A later change is rejected with RUNTIME_IMMUTABLE (HTTP 422). |
type | string | no | service | service, job | service runs a web server Aetherfy keeps reachable at the agent’s URL (it may be suspended while idle and resumed on the next request). job runs your code as a script with no server in it: Aetherfy invokes it, your program runs once and exits, and its exit code is what decides whether the run succeeded. A job never has a URL — see the task contract. Lowercased before validation. |
spawn | object or null | no | null | see below | Lets this agent start runs of your other agents. Off by default. See spawning. |
spawn.enabled | boolean | no | false | true, false | true requires workers: with none listed the deploy is refused with AGENT_SPAWN_WORKERS_REQUIRED (HTTP 422). |
spawn.workers | array of strings or null | no | null | agent names, or ["*"] | The agents this agent may spawn, either type. Each name must be a live agent at deploy time. "*" means any of your agents and must be the only entry. An empty list allows no spawns. |
regions | array of strings or null | no | null | us-east-1, eu-central-1, ap-southeast-1 | Not stored on the agent — consumed per deployment. When omitted, the deploy goes to the agent’s workspace’s regions, up to your plan’s maximum. Each must be one of the workspace’s. |
memory_mb | integer or null | no | 256 | 256, 512, 1024, 2048, 4096, 8192 | An explicit null is rejected. Also bounded by your plan’s maximum memory. Cores follow memory and cannot be set separately — the rule is on /platform/limits. |
idle_timeout_minutes | integer or null | no | 5 | at least 1, up to your plan’s maximum | An explicit null is rejected. The per-plan maximum (Free 5, Starter 15, Performance 30, Enterprise unlimited minutes) is checked on every deploy, exactly as when an agent is created or updated through the API or dashboard, and only where the timeout takes effect — a service with keep_alive off. A job or an always-on service never sleeps, so its value is never refused; making it take effect (switching to service, or keep_alive: false) with a value above the maximum fails the deploy with PLAN_LIMIT_EXCEEDED (HTTP 403, detail.limit is max_idle_timeout_minutes) and nothing in the file is applied. See /platform/limits. |
keep_alive | boolean or null | no | false | true, false | An explicit null is rejected. Rejected on type: job — a task’s machine is suspended between runs and resumes when a run is triggered, so there is nothing for always-on to keep awake. keep_alive: true makes the agent always-on: it is never suspended for being idle. On a paid plan that is an add-on that counts as usage (/platform/billing). On Free it costs nothing, and the agent runs until it has been awake for 75% of the month, then is paused until the month ends, which for an always-on agent is after about three weeks (up to about a day later, because awake time is booked once a day). New deploys are paused with it, and both resume with the month, or at once if you upgrade. A plan that does not allow always-on refuses the deploy with PLAN_LIMIT_EXCEEDED and detail.limit allows_always_on. |
drain_timeout_minutes | integer or null | no | 30 | 1 to 240 | An explicit null is rejected. Rejected on type: job, at any value: a task’s machine is not kept running for a release, and a task run that has started is not cut by a redeploy. How long a replaced version of a service keeps running to let its open calls end, counted from the redeploy; at the maximum a call that comes through the agent’s address is closed with code 1012 and the process is stopped, with 100 seconds to exit, so a replaced version runs at most this long plus 100 seconds. The ceiling, 240 minutes (4 hours), is the same on every plan and for always-on agents. See what a redeploy does to open calls. |
entrypoint | string or null | no | runtime default | a filename present in your archive | The file must exist or the build fails. Defaults are tabulated below. |
schedule | string or null | no | null | a 5-field UTC cron expression | Valid on either type, including an agent other agents spawn. See /agents/scheduled-tasks. |
github_dependencies | array of strings | no | [] | owner/repo@ref | Must fullmatch [A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+@[A-Za-z0-9._/-]+. Installed as the ref’s source archive, so a JavaScript package that builds itself on install is not built — see github dependencies. Private repositories require the Aetherfy GitHub App to be connected. |
writable_paths | array of strings | no | [] | absolute paths | For a runtime: dockerfile agent: the paths its process must be able to write. Aetherfy runs the agent as an unprivileged user and, before it starts, hands exactly these paths to that user — a directory with everything inside it, or a single file; a path that does not exist is created as a directory. Each must be clean (no .., no doubled or trailing /), listed once, and outside /etc, /run, /proc, /sys, /dev and /aetherfy; the most it takes is 32. The standard runtimes own their app directory, home directory and caches already and need none. See what your Aetherfy agent runs as. |
The agent’s name, description and workspace are not in aetherfy.yaml. The
file says how the agent runs; the platform owns what the agent is called, where
it lives and what it can reach (its workspace, its grants, its secrets, its name
and description). You set them when you create the agent and change them in the
dashboard or with afy update. A file that names any of them is refused at
deploy, with HTTP 422 DEPLOYMENT_CONFIG_PARSE_ERROR on an upload, and this
message (one clause per field the file declares, in the order of the table below).
afy deploy and afy diff refuse it the same way before anything is uploaded,
with the same sentence:
aetherfy.yaml says how the agent runs, not what it is called or where it lives. Remove `name:` (the agent's name is set on the platform: rename it with `afy update <agent> --name <new>` or in the dashboard).| Field in the file | Where it is set instead | The clause the refusal gives |
|---|---|---|
name: | afy update <agent> --name <new>, or the dashboard | the agent’s name is set on the platform: rename it with afy update <agent> --name <new> or in the dashboard |
description: | afy update <agent> --description <text>, or the dashboard | the agent’s description is set on the platform: afy update <agent> --description <text> or the dashboard |
workspace: | afy update <agent> --workspace <name>, or the dashboard’s Move | the workspace an agent lives in is set on the platform: move it with afy update <agent> --workspace <name> or the dashboard’s Move |
The runtime field is immutable on Aetherfy
runtime is the one field a live Aetherfy agent will not let you change. The
agent’s first release that goes live sets it — until then, each deploy takes the
runtime its file names, so a failed first deploy fixes nothing. After that,
deploying a different runtime is rejected with RUNTIME_IMMUTABLE and HTTP 422.
To move to a different runtime, delete the agent and create it again under the
same name.
Aetherfy accepts exactly 13 runtime values:
| Runtime | Shown as | Family | End of life | Deploys stop |
|---|---|---|---|---|
python3.11 | Python 3.11 | Python | 2027-10-31 | 2028-01-29 |
python3.12 | Python 3.12 | Python | 2028-10-31 | 2029-01-29 |
python3.13 | Python 3.13 | Python | 2029-10-31 | 2030-01-29 |
python3.14 | Python 3.14 | Python | 2030-10-31 | 2031-01-29 |
python3.15 | Python 3.15 | Python | 2031-10-31 | 2032-01-29 |
node22 | Node.js 22 | Node | 2027-04-30 | 2027-07-29 |
node24 | Node.js 24 | Node | 2028-04-30 | 2028-07-29 |
node26 | Node.js 26 | Node | 2029-04-30 | 2029-07-29 |
node22-ts | Node.js 22 (TypeScript) | Node with TypeScript | 2027-04-30 | 2027-07-29 |
node24-ts | Node.js 24 (TypeScript) | Node with TypeScript | 2028-04-30 | 2028-07-29 |
node26-ts | Node.js 26 (TypeScript) | Node with TypeScript | 2029-04-30 | 2029-07-29 |
bun | Bun | Bun | none | none |
dockerfile | Dockerfile | Your own container build | none | none |
A runtime’s end of life is the day its maintainers stop supporting it. From that day an agent already on it keeps deploying, with a warning, and Aetherfy creates no new agent on it. 90 days later deploys on it stop: Aetherfy builds no new image on it, and agents already running on it keep running. To move, create a new agent on a runtime that is still offered. none means the runtime has no end of life, so it is always offered.
python alone is not a valid runtime on Aetherfy: runtime: python fails the
deploy. Always write the full version, such as runtime: python3.14.
Entrypoint defaults on Aetherfy
If you omit entrypoint, Aetherfy uses the default for your runtime. The file
must exist in the code you upload, or the build fails.
| Runtime | Default entrypoint |
|---|---|
python3.11, python3.12, python3.13, python3.14, python3.15 | main.py |
node22, node24, node26 | index.js |
node22-ts, node24-ts, node26-ts | index.ts |
bun | main.ts |
For the dockerfile runtime, your Dockerfile defines how the program starts.
Letting an Aetherfy agent spawn other agents
Spawning is off unless you turn it on. When you do, you also list the agents this one may start — by name, of either type:
runtime: python3.12
type: service
spawn:
enabled: true
workers:
- ticket-classifier
- refund-processorspawn.enabled: true with no spawn.workers is refused at deploy with
AGENT_SPAWN_WORKERS_REQUIRED and HTTP 422. To fix it, list the agents this one
may spawn under spawn.workers, or write spawn.workers: ["*"] to allow any
of your agents.
A spawn of an agent that is not on the list is refused with
AGENT_WORKER_NOT_ALLOWED and HTTP 403. An empty list allows no spawns at all.
Why an Aetherfy agent lists the workers it may spawn
| What the list gives you | How |
|---|---|
| A compromised agent reaches only what it named. | The agent that spawns is usually the one facing the internet — a service taking requests from your users. If it is compromised — a bug, a prompt injected into an AI agent, a leaked key — the list is how far the damage reaches. Without it, every agent you own could be started, each run billed to you. With it, only the agents it declared. |
| A mistyped worker fails at deploy, not at runtime. | Every name in spawn.workers must be a live agent when you deploy, or the deploy is refused with WORKER_NOT_FOUND. A typo shows up in afy deploy, not as a failed spawn in production. |
| A worker cannot be deleted by accident. | Deleting an agent that another live agent lists is refused with AGENT_HAS_WORKER_DEPENDENTS (HTTP 409), naming the agents that depend on it. The check works because the dependency is declared. |
Letting an Aetherfy agent spawn any of your agents
To let an agent spawn any agent on your account, write "*" as the only entry:
runtime: python3.12
spawn:
enabled: true
workers: ["*"]"*" cannot be combined with names — ["*", "refund-processor"] is refused.
Choosing it gives up all three protections above: a compromised agent can start
any of your agents, there are no names for the deploy to check, and nothing is
protected from deletion because nothing is named. Use it when the set of workers
is genuinely open-ended, not to save listing them.
Like every field, spawn: describes the agent completely: a deploy without the
block turns spawning off, and a block without workers lists no workers, so
enabled: true without them is refused. Nothing carries over from the agent’s
previous deploy.
Using collections from an Aetherfy agent
There is nothing to declare. aetherfy.yaml has no collection field, and an
agent is not restricted to a collection it named — it never was.
Every agent lives in a workspace, and Aetherfy injects that workspace’s id
into it as AETHERFY_WORKSPACE_ID. The SDKs’ default, workspace="auto", reads
it, so any collection in the agent’s own workspace is reachable by name with no
configuration:
from aetherfy_vectors import AetherfyVectorsClient
client = AetherfyVectorsClient(workspace="auto")
client.search("animals", vector)
client.search("food", vector)
client.search("toys", vector)Collections your code creates at runtime work the same way and need no declaration either.
Aetherfy records which collections an agent actually reads and writes, so the
agent’s page in the dashboard (its deployments view) lists them — including the ones created at
runtime — without you configuring anything. That record is also what
afy collections delete reads to name the agents that used a collection in the last
35 days before it asks you to confirm. It does not stop the delete: nothing refuses
a delete because an agent used the collection; see
the collection lifecycle.
What idle_timeout_minutes actually does on Aetherfy
idle_timeout_minutes applies to service agents that are not always-on, and
it is the reason a rarely-used Aetherfy agent costs little to leave deployed.
After that many minutes without a real request, Aetherfy suspends the machine: the process is frozen in memory rather than shut down. The next request resumes it from that snapshot — a warm resume rather than a cold start: no image pull, no process launch, no re-initialisation, so connections and caches your code built at startup are still there when it wakes.
Two details decide how it behaves for you:
| Detail | Behaviour |
|---|---|
| What counts as activity | Real requests only. Aetherfy’s own GET /health checks are excluded deliberately — if they counted, no agent would ever go idle |
| Which agents are affected | service agents with keep_alive: false, and every job agent. A task is suspended between runs the same way an idle service is, and resumes when a run is triggered. keep_alive: true disables suspension entirely, and is rejected on type: job |
| An open WebSocket | Counts as activity for as long as it is held. The machine stays up for the life of the connection, and the idle window only starts once it closes |
So the first request after a quiet period is slower than the rest. A resume typically adds under a second on top of the response time your agent already has, and occasionally more.
This holds at every memory size an auto-sleep service can have, the largest included. A larger machine is suspended about 30 seconds after its idle window ends, and resumes on the next request.
Occasionally the snapshot does not survive — a host is taken down for
maintenance, or your machine is migrated. There is nothing to thaw, so the next
request starts the process instead of resuming it. That start typically adds a few
seconds to the first request, and the delay grows with the size of your app and the
work it does at startup (your imports, your clients). It is not a redeploy: your
image is already there, and nothing about your agent changes. If that delay matters,
as it does for a voice agent’s first ring, use keep_alive: true.
The request that starts the process waits for it. Sixty seconds is a ceiling, not the
wait: a start typically takes a few seconds. Requests that arrive while your server is
still starting are held and forwarded once it is listening, for up to 60 seconds from
the start, which is room for an app that starts slowly (a large model loaded at import,
for example). Only a server that is still not listening after those 60 seconds, or that
exits before it listens, gets requests answered 502 AGENT_UNAVAILABLE with a
request_id. The response says nothing more, because the reason can be your
program’s error output and that can contain a secret: find the request_id in your
agent’s logs, next to the reason — the exit code and the error output your program
printed, or that it did not start listening within 60 seconds. A server that starts
listening after those 60 seconds serves every request from that moment; only the
requests in between were refused.
The same applies to GET /health on your agent: anyone can read whether it is
healthy, starting or unhealthy, but the error that made it unhealthy is only in
your logs and in the reason Aetherfy shows you for a degraded agent.
One difference matters for your own code. A start from stopped runs your startup again, so a heavy agent adds more. A resume does not run any of that: the process is thawed with the connections and caches it already built, which is why the resume figure holds whatever your agent does at startup.
If either matters for your workload, keep_alive: true keeps the machine
running — at the cost described on
/platform/billing.
A held WebSocket and a short idle timeout are not in conflict
idle_timeout_minutes: 1 and a WebSocket open for two hours coexist, and the
machine stays up for those two hours. Nothing is misconfigured and nothing
overrode your setting: an open connection is activity, so the idle window
never starts while one is held. It begins when the last connection closes.
This is worth stating plainly because the numbers look contradictory on a bill. An agent with a one-minute idle timeout can show hours of uptime in a period, and that is the correct reading rather than a billing error — Aetherfy meters the time your machine is up, and it was up, serving the connection you opened. If you want a long-lived connection that does not hold a machine, close it when idle and reconnect; the resume is warm rather than a cold start.
A field you leave out takes its default on Aetherfy
aetherfy.yaml is the whole description of how your agent runs, and every
deploy applies all of it. A field you leave out takes the default in the table
above, never the value the agent had before: nothing carries over from an
earlier deploy, and nothing set elsewhere is kept, because only a deploy sets
these fields.
| In the deployed yaml | Effect on the Aetherfy agent |
|---|---|
| Field with a value | Set to that value |
| Field omitted | Set to its default |
Field explicitly null | The same as omitting it (entrypoint, schedule, regions, spawn, spawn.workers) |
So deploying a file without schedule removes the agent’s schedule, and one
without keep_alive turns always-on off. The same file always deploys the same
agent, whatever was deployed before it.
Four fields cannot be null, and an explicit null on any of them is
rejected: leave the field out for its default instead.
| Field | What null does |
|---|---|
memory_mb | Rejected |
idle_timeout_minutes | Rejected |
drain_timeout_minutes | Rejected |
keep_alive | Rejected |
regions is decided per deploy rather than stored: left out, the deploy goes to
the agent’s workspace’s regions, up to your plan’s maximum.
Aetherfy refuses unknown fields in aetherfy.yaml
Aetherfy refuses an aetherfy.yaml that names a field it does not accept, at
any depth. The whole file is refused — the valid fields beside the unknown one
are not applied either — and the message names the field, its path, and the
closest field Aetherfy does accept:
runtime: python3.12
type: job
schedul: "0 3 * * *"Config validation failed: unknown field `schedul`, did you mean `schedule`?Inside spawn: the path is dotted: spawn.workres is refused with
did you mean `spawn.workers`?. When no accepted field is close, the message
names only the unknown one. Every unknown field in the file is listed, separated
by ; , and the server lists any invalid values in the same message.
Every way of deploying gives the same answer:
| Where | What you get |
|---|---|
afy deploy | Refused before anything is uploaded: aetherfy.yaml: unknown field ..., the same sentence under the file’s name. afy diff refuses the file the same way. |
POST /api/v1/agents/{agent}/deploy | HTTP 422, DEPLOYMENT_CONFIG_PARSE_ERROR, the message above. |
| A push to a linked GitHub repository | The deployment is failed with the message above, and the commit gets a failure status carrying it. |
A redeploy or a rollback never re-reads a file: it runs that release’s own recorded configuration (see rollback).
Only field names are checked this way. A field you leave out is not an error: it takes its default.
To preview what a deploy would change, run afy diff in the directory holding
aetherfy.yaml:
afy diffIt exits non-zero when there are changes, so it also works as a CI gate.
Archive limits Aetherfy enforces
The code you upload is subject to hard limits. Exceeding them fails the deploy.
| Limit | Value | Behaviour beyond it |
|---|---|---|
| Compressed upload size | 50 MB | HTTP 413 |
| Decompressed stream ceiling | 500 MB | Rejected |
| Archive members | 20 000 | Rejected |
| Size of the yaml member itself | 1 MB | Rejected |
Keeping uploads small is mostly a matter of exclusions. The Aetherfy CLI honours
a .afyignore file and applies built-in defaults including .git, .env,
__pycache__, node_modules, venv, .DS_Store, and *.log.
Lockfile requirements on Aetherfy
Aetherfy builds reproducibly, so some runtimes require a lockfile alongside your manifest.
| Runtime family | Condition | Required lockfile |
|---|---|---|
node22, node24, node26, node22-ts, node24-ts, node26-ts | Always, with package.json | package-lock.json |
bun | When package.json declares a package | bun.lock or bun.lockb |
python3.11, python3.12, python3.13, python3.14, python3.15 | When a pyproject.toml is present | uv.lock |
A Python project using a plain requirements.txt does not need uv.lock.
For bun, commit whichever lockfile your bun writes. Bun 1.2 and later
default to the text bun.lock; bun.lockb is the older binary format and is
still accepted. A bun agent needs no lockfile at all when it has no
package.json, or when its package.json lists nothing under
dependencies, devDependencies, optionalDependencies,
peerDependencies or workspaces — Bun writes no lockfile for such a
project, so Aetherfy does not ask for one.
Exporting an agent’s Aetherfy configuration
Aetherfy exports the configuration an agent’s live release was deployed
with, as an aetherfy.yaml:
| From | How |
|---|---|
| The CLI | afy init --agent <name> in a folder: links the folder to the agent and, when the folder has no aetherfy.yaml yet, writes the export as one (an existing file is kept unless --force; see deploy) |
| The dashboard | Download YAML on the agent’s page |
| The API | GET /api/v1/agents/{agent}/yaml (lifecycle API) |
The export is the release’s recorded configuration, never the agent’s current
settings and never a template: every field this file owns, starting with the
editor line above. runtime, type, memory_mb, idle_timeout_minutes,
keep_alive, regions, github_dependencies and writable_paths are always written,
and drain_timeout_minutes on a service;
entrypoint, schedule and spawn are written when they are not at their
defaults. It never carries name, description or workspace. Deploying it
unchanged releases the same configuration again, so afy diff against it shows
nothing.
| The agent | What the export answers |
|---|---|
| Released, live, paused or stopped | Its live release’s configuration |
| Archived | Its last release’s, which is what a restore releases |
| A draft (never released) | HTTP 404 AGENT_NOT_DEPLOYED: there is nothing to export. afy init --agent writes a starting file for a draft instead |
| Released before Aetherfy recorded each release’s configuration | HTTP 422 RELEASE_CONFIG_NOT_ON_RECORD: deploy it again from its source |