Skip to Content
Agent computeDeploy an agent
Raw

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 login

For CI or any non-interactive shell, pass the key directly:

afy login --api-key afy_live_xxxxx

Confirm the CLI is talking to your Aetherfy account:

afy whoami

Create 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-agent

aetherfy.yaml — the configuration Aetherfy reads. It must sit at the root of the directory you deploy:

runtime: python3.14 type: service memory_mb: 256

Write 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 familyWhat Aetherfy importsWhat you export
python3.11, python3.12, python3.13, python3.14, python3.15your entrypoint moduleapp — a FastAPI application
node22, node24, node26, node22-ts, node24-ts, node26-tsyour entrypoint moduleapp — an Express application, or an object with a fetch method such as a Hono app, via module.exports = { app } or a default export
bunyour entrypoint moduleapp — the same shapes as Node.js
dockerfilenothing — you own the containersee /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 by if __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 /health route of your own is never reached.
  • A missing app export 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 --yes

With one workspace in your account (a new account has default), afy init puts the agent there without asking.

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-agent

afy 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 deploy

afy 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:

FlagEffect
--detach / -dReturn as soon as the upload finishes instead of waiting
--targetDeploy to another agent the folder is linked to, such as staging (see /cli/deploy)
--yes / -ySkip 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 --yes

Aetherfy 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 list

You 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-agent

Follow the logs as they arrive:

afy logs hello-agent --follow

Show more history, or narrow to a time window and a severity:

afy logs hello-agent --tail 200 --since 1h --level ERROR,WARN

Aetherfy 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 diff

afy 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 stepPage
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
Last updated on