Deploy an agent to Aetherfy
This tutorial takes you from an empty directory to a deployed Aetherfy agent
that answers HTTP requests, then shows you its logs. It uses the afy CLI
throughout and asks you to make no design decisions along the way.
You need the afy CLI installed before you start. Installation instructions are
on /cli.
Get an Aetherfy API key
Create an API key at
https://app.aetherfy.com/dashboard/settings/api-keys .
Keys look like afy_live_xxxxx. Copy it when it is shown.
The Aetherfy CLI reads your key from its stored login, and it also honours the
AETHERFY_API_KEY environment variable if one is set.
Sign in to Aetherfy with afy login
Run afy login and paste the key when prompted:
afy loginFor CI or any non-interactive shell, pass the key directly:
afy login --api-key afy_live_xxxxxConfirm the CLI is talking to your Aetherfy account:
afy whoamiCreate the agent’s files for Aetherfy
Make a directory and add two files. This example is a service agent — a
long-lived process that answers HTTP requests.
mkdir hello-agent
cd hello-agentaetherfy.yaml — the configuration Aetherfy reads. It must sit at the root of
the directory you deploy:
runtime: python3.14
type: service
memory_mb: 256Write the runtime version in full. runtime: python is not valid on
Aetherfy and fails the deploy; the Python values Aetherfy accepts are
python3.11, python3.12, python3.13, python3.14, python3.15.
main.py — the entrypoint. main.py is the default entrypoint for every
python3.* runtime on Aetherfy, so you do not need to declare it.
A service agent on a Python runtime exports a FastAPI application in a
variable named app, and does not start a server itself. Aetherfy runs the
server for you: it imports your entrypoint, serves the app it finds there on
port 8080, and answers its own GET /health. This is the one contract the
tutorial asks you to follow exactly — the next section explains what happens if
you do not.
"""A minimal Aetherfy service agent: a FastAPI app exported as `app`."""
import os
from fastapi import FastAPI
# Aetherfy imports this module and serves THIS object. The name must be `app`.
app = FastAPI()
# Runs at import time, when Aetherfy starts the agent. Anything printed to
# stdout becomes this agent's logs on Aetherfy.
print("hello-agent starting", flush=True)
@app.get("/")
def index():
return {
"message": "hello from Aetherfy",
"agent": os.environ.get("AETHERFY_AGENT_NAME", "unknown"),
"region": os.environ.get("AETHERFY_REGION", "unknown"),
}
@app.post("/echo")
def echo(body: dict):
"""Reads a JSON request body and returns it. Aetherfy adds no routing of
its own — every route you declare on `app` is served as you wrote it."""
return {"you_sent": body}Both routes are yours. Aetherfy serves whatever you declare on app and adds
only GET /health, so the request shapes, paths and status codes are the
framework’s business and not Aetherfy’s — reach for FastAPI’s or Express’s own
documentation when you need path parameters, validation or custom responses.
There is no second file to write. Aetherfy installs FastAPI and uvicorn into
every Python service image itself, so this example needs no
requirements.txt at all. Add one when your agent has dependencies of its own;
Aetherfy installs from it when it is present.
The Aetherfy service contract, and what breaks without it
The export above is not a style preference. Aetherfy imports your entrypoint as a module and looks for one specific name:
| Runtime family | What Aetherfy imports | What you export |
|---|---|---|
python3.11, python3.12, python3.13, python3.14, python3.15 | your entrypoint module | app — a FastAPI application |
node22, node24, node26, node22-ts, node24-ts, node26-ts | your entrypoint module | app — an Express application, or an object with a fetch method such as a Hono app, via module.exports = { app } or a default export |
bun | your entrypoint module | app — the same shapes as Node.js |
dockerfile | nothing — you own the container | see /agents/dockerfile |
Every export shape Aetherfy accepts on Node.js and Bun — Express, Hono, a bare
fetch handler, and a WebSocket server exported beside the app — has a complete
project you can deploy on /agents/node-and-bun.
Three consequences follow, and the third is the one that costs an afternoon:
- Do not start a server yourself. Aetherfy runs uvicorn (or Node) against
your
app. Code guarded byif __name__ == "__main__":never executes, because Aetherfy imports the module rather than running it as a script. - Do not implement
GET /health. Aetherfy answers that path itself, in front of your app, so a/healthroute of your own is never reached. - A missing
appexport fails the deploy, and says so. Aetherfy checks for the export before building, and checks again at startup: an entry point that does not load is never reported healthy, so the deploy stops and its reason carries your interpreter’s own error message. Read the deploy’s reason first — it names the file and what went wrong with it.
This contract applies to service agents only. A job agent is executed as a
plain script, exports nothing, and is covered by
/agents/task-contract.
Letting afy init write the configuration instead
You do not have to write aetherfy.yaml by hand. afy init inspects a directory,
detects the project type, generates aetherfy.yaml for you, creates the agent and
links the folder to it, in one step. (In a folder that already has an
aetherfy.yaml, as above, it asks before overwriting it; -f / --force
overwrites without asking. The next section keeps your file instead.)
Every prompt it asks has a matching flag — --name, --workspace, --runtime,
--entrypoint, --type, --region, --memory, --keep-alive and
--schedule. --keep-alive is a yes/no toggle and takes no argument;
--workspace takes a workspace name. -y / --yes accepts all defaults,
which makes it usable in CI:
afy init --name hello-agent --runtime python3.14 --type service --yesWith one workspace in your account (a new account has default), afy init
puts the agent there without asking.
Create the agent and link the folder to it
Your code deploys to an agent: a named record on Aetherfy that owns the deployments, the machines and the logs. Create it, then link this folder to it:
afy create hello-agent
afy init --agent hello-agentafy create makes the agent in a workspace (your account’s only one, default
for a new account; with several, it asks, and without a terminal --workspace <name> says which). afy init --agent writes .aetherfy/agent.json, which links
this folder to the agent, and keeps the aetherfy.yaml you wrote. Commit
.aetherfy/ along with your code, so every clone and CI job deploys to the same
agent. /cli/deploy has the
link file’s rules.
The agent exists but runs nothing yet. A deploy never creates an agent: a folder with no link is refused, naming the command that links it.
Deploy the agent to Aetherfy
From inside the directory, run:
afy deployafy deploy uploads the current directory to the agent the folder is linked to,
builds an image, launches machines, waits for completion, and streams status as it
goes. It asks for confirmation only when the deploy would add usage beyond your
plan’s included amount (see billing);
a deploy that adds none does not prompt.
aetherfy.yaml says how the agent runs. The agent’s name, workspace and
description are the platform’s: they are not in the file, and a file that names
them is refused. Rename the agent with afy update hello-agent --name <new>;
the folder stays linked to it, because the link names the agent by id.
In a folder with no aetherfy.yaml, afy init --agent <name> also writes the
agent’s current configuration as one, which is how a teammate’s clone starts from
an agent that already exists.
Useful flags on the Aetherfy deploy command:
| Flag | Effect |
|---|---|
--detach / -d | Return as soon as the upload finishes instead of waiting |
--target | Deploy to another agent the folder is linked to, such as staging (see /cli/deploy) |
--yes / -y | Skip the overage confirmation prompt |
A pipeline deploying to an existing agent passes --yes, which answers the
overage prompt when a deploy raises one:
afy deploy --yesAetherfy does not upload everything in the directory. Files matching
.afyignore are excluded, along with built-in defaults including .git,
.env, __pycache__, node_modules, venv, .DS_Store, and *.log.
Confirm the Aetherfy agent is running
When the deploy finishes, the deployment reaches the active state and the
agent’s status becomes running. Check it from the CLI:
afy listYou can see the same thing in the dashboard at https://app.aetherfy.com/dashboard/agents ; Agents in the dashboard explains each badge and state it shows.
If the deploy failed instead, the deployment ends in the failed state and the
error is recorded against it. List the history with afy deployments hello-agent
to read the failure, and see /agents/runs-and-logs for
what each state means.
Call the Aetherfy agent
A deployed service agent has its own address, shown by afy list and
on the agent in the dashboard:
curl -s https://hello-agent-k3m7x2q5hwd4nzra.aetherfy.dev/{"message": "hello from Aetherfy", "agent": "hello-agent", "region": "iad"}The POST /echo route from main.py is served exactly as written:
curl -s https://hello-agent-k3m7x2q5hwd4nzra.aetherfy.dev/echo \
-H "Content-Type: application/json" \
-d '{"hello": "world"}'{"you_sent": {"hello": "world"}}No API key. Your agent’s address is public and serves whoever calls it — the key authenticates you to Aetherfy, not your callers to your agent. If your agent needs to authenticate its callers, that is a route you write.
The address is fixed at your first deploy
The sixteen characters after the name are generated the first time the agent
deploys, and the address never changes afterwards — including when you
rename the agent. An agent renamed hello-agent to greeter keeps serving
at hello-agent-k3m7x2q5hwd4nzra.aetherfy.dev.
That is deliberate: a rename that moved the address would break every integration, link and webhook already pointing at it. The practical rule is rename before your first deploy and the address follows the new name; rename after and it stays as it was.
Rename with afy update <agent> --name <new>. There is nothing on disk to
update: aetherfy.yaml does not carry the name, and a folder linked with
afy init keeps deploying to the agent, because the link names it by id. Code
that calls the agent by its old name stops finding it. Full behaviour is on
/cli/agents.
There is no way to issue a second address for the same agent, and there will
not be one — the address is derived from the agent rather than looked up, so
one agent has exactly one address. job agents have none at all: they run to
completion and exit, so nothing is listening.
Read the Aetherfy agent’s logs
Everything your program writes to stdout and stderr becomes the agent’s logs on
Aetherfy. The startup line from main.py above appears here:
afy logs hello-agentFollow the logs as they arrive:
afy logs hello-agent --followShow more history, or narrow to a time window and a severity:
afy logs hello-agent --tail 200 --since 1h --level ERROR,WARNAetherfy keeps logs for your plan’s retention, and at most your plan’s size per account: 3 days and 50 MB on Free, 14 days and 250 MB on Starter, 30 days and 1 GB on Performance. The size counts each line’s message bytes (at least 64); when an account is over it the oldest lines go first, and an account may run over its size for up to an hour. The full flag list, the per-line and volume caps, and the dropped-line marker are documented on /agents/runs-and-logs.
Preview a change before deploying it to Aetherfy
Aetherfy applies the whole of aetherfy.yaml on every deploy, so a field you
leave out takes its default rather than keeping its existing value. Before a
deploy you are unsure about, preview exactly what would change:
afy diffafy diff exits non-zero when there are changes, which makes it usable
as a CI gate that fails a pipeline on unintended configuration drift.
What to do next with Aetherfy
| Next step | Page |
|---|---|
| Every configuration field and what an omitted field means | /agents/aetherfy-yaml |
| Turn this into a run-once task on a schedule | /agents/scheduled-tasks |
| How a task reads input, exits, and is retried (it is not) | /agents/task-contract |
| Give the agent API keys and other secrets | /agents/secrets |
| Deploy automatically on every push | /agents/github |
| The rest of the Aetherfy CLI surface | /cli/agents |