Skip to Content
Agent computeaetherfy.yaml reference
Raw

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:

PriorityFilename
1aetherfy.yaml
2aetherfy.yml
3.aetherfy.yaml
4.aetherfy.yml

A minimal valid file for Aetherfy is one field:

runtime: python3.12

Autocomplete 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.12

The 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/myapp

Every field Aetherfy accepts in aetherfy.yaml

FieldTypeRequiredDefaultAllowed valuesNotes
runtimestringyes—python3.11, python3.12, python3.13, python3.14, python3.15, node22, node24, node26, node22-ts, node24-ts, node26-ts, bun, dockerfileFixed by the agent’s first release that goes live. A later change is rejected with RUNTIME_IMMUTABLE (HTTP 422).
typestringnoserviceservice, jobservice 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.
spawnobject or nullnonullsee belowLets this agent start runs of your other agents. Off by default. See spawning.
spawn.enabledbooleannofalsetrue, falsetrue requires workers: with none listed the deploy is refused with AGENT_SPAWN_WORKERS_REQUIRED (HTTP 422).
spawn.workersarray of strings or nullnonullagent 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.
regionsarray of strings or nullnonullus-east-1, eu-central-1, ap-southeast-1Not 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_mbinteger or nullno256256, 512, 1024, 2048, 4096, 8192An 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_minutesinteger or nullno5at least 1, up to your plan’s maximumAn 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_aliveboolean or nullnofalsetrue, falseAn 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_minutesinteger or nullno301 to 240An 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.
entrypointstring or nullnoruntime defaulta filename present in your archiveThe file must exist or the build fails. Defaults are tabulated below.
schedulestring or nullnonulla 5-field UTC cron expressionValid on either type, including an agent other agents spawn. See /agents/scheduled-tasks.
github_dependenciesarray of stringsno[]owner/repo@refMust 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_pathsarray of stringsno[]absolute pathsFor 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 fileWhere it is set insteadThe clause the refusal gives
name:afy update <agent> --name <new>, or the dashboardthe 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 dashboardthe 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 Movethe 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:

RuntimeShown asFamilyEnd of lifeDeploys stop
python3.11Python 3.11Python2027-10-312028-01-29
python3.12Python 3.12Python2028-10-312029-01-29
python3.13Python 3.13Python2029-10-312030-01-29
python3.14Python 3.14Python2030-10-312031-01-29
python3.15Python 3.15Python2031-10-312032-01-29
node22Node.js 22Node2027-04-302027-07-29
node24Node.js 24Node2028-04-302028-07-29
node26Node.js 26Node2029-04-302029-07-29
node22-tsNode.js 22 (TypeScript)Node with TypeScript2027-04-302027-07-29
node24-tsNode.js 24 (TypeScript)Node with TypeScript2028-04-302028-07-29
node26-tsNode.js 26 (TypeScript)Node with TypeScript2029-04-302029-07-29
bunBunBunnonenone
dockerfileDockerfileYour own container buildnonenone

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.

RuntimeDefault entrypoint
python3.11, python3.12, python3.13, python3.14, python3.15main.py
node22, node24, node26index.js
node22-ts, node24-ts, node26-tsindex.ts
bunmain.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-processor

spawn.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 youHow
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:

DetailBehaviour
What counts as activityReal requests only. Aetherfy’s own GET /health checks are excluded deliberately — if they counted, no agent would ever go idle
Which agents are affectedservice 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 WebSocketCounts 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 yamlEffect on the Aetherfy agent
Field with a valueSet to that value
Field omittedSet to its default
Field explicitly nullThe 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.

FieldWhat null does
memory_mbRejected
idle_timeout_minutesRejected
drain_timeout_minutesRejected
keep_aliveRejected

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:

WhereWhat you get
afy deployRefused 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}/deployHTTP 422, DEPLOYMENT_CONFIG_PARSE_ERROR, the message above.
A push to a linked GitHub repositoryThe 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 diff

It 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.

LimitValueBehaviour beyond it
Compressed upload size50 MBHTTP 413
Decompressed stream ceiling500 MBRejected
Archive members20 000Rejected
Size of the yaml member itself1 MBRejected

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 familyConditionRequired lockfile
node22, node24, node26, node22-ts, node24-ts, node26-tsAlways, with package.jsonpackage-lock.json
bunWhen package.json declares a packagebun.lock or bun.lockb
python3.11, python3.12, python3.13, python3.14, python3.15When a pyproject.toml is presentuv.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:

FromHow
The CLIafy 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 dashboardDownload YAML on the agent’s page
The APIGET /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 agentWhat the export answers
Released, live, paused or stoppedIts live release’s configuration
ArchivedIts 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 configurationHTTP 422 RELEASE_CONFIG_NOT_ON_RECORD: deploy it again from its source
Last updated on