aetherfy.yaml

What aetherfy.yaml is on Aetherfy

aetherfy.yaml is the single declarative file that describes an Aetherfy agent. It is required — a deploy without it fails. It must sit at the root of the archive you upload, or at the root of the build context when Aetherfy builds from a linked GitHub repository.

Aetherfy accepts four filenames, and uses the first one it finds in this priority order:

A minimal valid file for Aetherfy is two fields:

name: hello-agent
runtime: python3.12

A fuller example using most of the surface:

name: nightly-report
runtime: python3.12
type: job
description: Rolls up yesterday's events and writes a summary row.
workspace: reporting
database_collection: report-embeddings
entrypoint: main.py
memory_mb: 512
idle_timeout_minutes: 5
keep_alive: false
schedule: "0 3 * * *"
regions:
  - us-east-1
github_dependencies:
  - myorg/shared-lib@v1.2.0

Every field Aetherfy accepts in aetherfy.yaml

The runtime field is immutable on Aetherfy

runtime is the one field an existing Aetherfy agent will not let you change. Deploying a different runtime to an agent that already exists 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 nine runtime values:

python alone is not a valid runtime on Aetherfy. Documentation published previously showed runtime: python, and that value fails the deploy. Always write the full version, such as runtime: python3.12.

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.

For the dockerfile runtime, your Dockerfile defines how the program starts.

Using more than one collection from an Aetherfy agent

There is no list form of database_collection, and none is needed. The field is a single default-collection hint recorded on the agent — it does not restrict what the agent can reach at runtime.

Aetherfy injects AETHERFY_WORKSPACE into every agent, and the SDKs use it as the namespace. Any collection in that 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)

So set database_collection if you want the agent’s primary collection recorded on its record, and ignore it otherwise.

Merge-patch semantics in Aetherfy

Aetherfy applies your aetherfy.yaml as an RFC 7396 merge patch, not as a full replacement. This is the single most consequential behaviour on this page: a field you leave out is preserved, not reset to its default.

So a configuration you deploy that omits schedule keeps whatever schedule the agent already has. To actually remove a schedule you must write it explicitly:

name: nightly-report
runtime: python3.12
type: job
schedule: null

Three fields are non-nullable, and an explicit null on any of them is rejected rather than treated as a clear:

Merge-patch is also why a deploy from a linked GitHub repository does not wipe settings you made elsewhere — fields absent from the pushed file keep the values you set through the Aetherfy dashboard or API.

Unknown keys are silently ignored by Aetherfy

The aetherfy.yaml parser does not reject unknown top-level keys. A typo does nothing at all and the deploy still succeeds, which makes this the most common way to believe a setting is applied when it is not.

name: nightly-report
runtime: python3.12
type: job
schedul: "0 3 * * *"   # typo: silently ignored, this agent has NO schedule
memorymb: 1024         # typo: silently ignored, memory stays at its old value

Both lines above are accepted and both do nothing. Note the contrast with the Aetherfy REST API, which rejects unknown fields with a 422 — the leniency is specific to the configuration file.

Verify before you rely on a field. afy agents diff previews exactly what a deploy would change and what it would preserve:

afy agents diff nightly-report

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.

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.

A Python project using a plain requirements.txt does not need uv.lock.

Exporting an agent’s current Aetherfy configuration

afy agents pull writes out the configuration Aetherfy currently holds for an agent:

afy agents pull nightly-report

It emits the declarative subset of the fields, and re-deploying what it emits is a no-op. Two fields are deliberately not emitted, because neither is stored on the agent as durable state:

Use afy agents pull when you want to bring an agent that was configured through the Aetherfy dashboard back under version control.