Skip to Content
Agent computeOverview
Raw

Aetherfy agent compute

What Aetherfy agent compute is

Aetherfy agent compute runs your code on managed machines. You bring a directory containing your program and one configuration file; Aetherfy builds an image, places machines in one or more regions, injects your secrets as environment variables, and keeps a record of every version you deploy.

An agent is the compute primitive. An agent has a name, a runtime, a type, resource configuration, and optionally a schedule and a link to a GitHub repository.

An agent’s name becomes the first part of its URL, so it has to be a valid DNS label: lowercase letters, digits and hyphens only, no leading, trailing or doubled hyphen, and at most 37 characters. That budget is a DNS label’s 63, less the 17-character suffix Aetherfy appends and the 9-character prefix on the agent’s origin hostname — the origin is the longer of the two names, so it is the one that binds. A small set of names that read as infrastructure — api, admin, login, www and similar — is reserved, and so is any name beginning e2e-test-, which belongs to Aetherfy’s own test suite. A reserved name is refused when the agent is created, naming the rule; nothing is silently renamed, because the name you choose becomes the permanent first part of the address. Renaming an agent does not change its URL: the address is fixed when the agent first deploys and stays put, so an integration pointing at it keeps working.

What Aetherfy expects of your code depends entirely on which of the two agent types you deploy, and the difference is described in the next two sections.

The two Aetherfy agent types

Aetherfy has exactly two agent types, chosen with the type field in aetherfy.yaml. The default is service.

TypeLifecycleHTTP serverHealth checkScheduling
serviceLong-lived, supervisor styleYes — your program serves requestsYesYes — each run is a request to its POST /aetherfy/run
jobRuns once and exitsNoNoYes — each run executes the entrypoint

A service agent on Aetherfy is always-on in the supervisor sense: it gets a health check, an idle watcher, and is auto-started when a request arrives. Use it for anything that answers requests.

A job agent runs once and exits. It has no HTTP server, no health check, and no exposed port. Either type can carry a schedule — see /agents/scheduled-tasks.

What Aetherfy expects your code to export

The two types make opposite demands of your entrypoint, and this is the fact most worth reading before you write any code.

servicejob
How Aetherfy starts your codeImports the entrypoint as a moduleExecutes the entrypoint as a script
What your entrypoint must exportapp — a FastAPI application on the Python runtimes, an Express application on the Node and Bun runtimesnothing
Who runs the HTTP serverAetherfy, on port 8080nobody — there is no server
Who answers GET /healthAetherfy, in front of your app — a /health route of your own is never reachednobody
if __name__ == "__main__":Never runs — the module is imported, not executedRuns normally

For a job agent there is genuinely no framework to adopt and no handler signature to implement: Aetherfy runs your file top to bottom and reads its exit code, which is the whole contract at /agents/task-contract.

For a service agent the export is mandatory, and omitting it stops the deploy: an entry point that does not load is never reported healthy, so the deploy fails with your interpreter’s own error message as its reason rather than producing an agent that answers an error to every request. The full contract, with a working example, is at /agents/quickstart.

The dockerfile runtime opts out of all of this: you supply the container, so you own the server, the port and the health endpoint. See /agents/dockerfile.

How Aetherfy shuts a service down

When Aetherfy stops a service machine — a redeploy, a stop, or a scale-down — it sends SIGTERM to your server and every process it started, and the machine has 120 seconds before SIGKILL. Your server gets all of that window except the few seconds the platform keeps for itself after it — to kill what is left, read your last output and flush your logs — which is 100 seconds with today’s settings. Anything still running when your server’s share ends is sent SIGKILL, workers included. That window is for finishing in-flight requests and closing connections cleanly.

A redeploy does not stop the old version like that. It keeps the old version running for as long as it still has calls open, up to a maximum you set. The next section says what happens, and the 120 seconds above is what a stop, a pause or a scale-down give.

And you do not need to install a signal handler to get a clean stop: the runtime Aetherfy injects handles SIGTERM for you on every standard runtime. Processes your app starts receive the same SIGTERM, and are killed with it when the window ends.

What a redeploy does to a service’s open calls

A redeploy is a blue-green swap. The new version starts and must be healthy before anything is stopped. From then on, new requests and new calls go to the new version. The old version is not stopped at that moment: it keeps running to let what is open end, and it keeps the API key it started with for as long as it runs, so a request or a call still in progress can still read and write Aetherfy collections and call the agents API. The old version’s key ends when its machine has stopped.

What happens to a call that is open when you redeploy depends on the kind of agent:

Your agentA call in progressNew callsWhen the old version ends
Inbound: callers connect to your agent’s address (a WebSocket for a Twilio Media Stream, a browser client)Keeps talking on the old version until the caller hangs upGo to the new versionOne minute after the last call and request have ended, the old version is sent SIGTERM, finishes and exits
Outbound worker that joins calls itself, such as a LiveKit Agents worker or a Pipecat botFinishes on the old versionNone: the old version takes no new callsOne minute after nothing it can see is open, the old version is sent SIGTERM. A worker that drains on SIGTERM finishes its current calls, takes no new ones, then exits by itself
A process that ignores SIGTERMKeeps running until the maximumGo to the new versionAetherfy stops it at the maximum

On a redeploy your process receives SIGTERM and should finish its open calls, then exit, within the maximum. Aetherfy holds the SIGTERM back while a call that comes through your agent’s address is open, because uvicorn closes its WebSockets when it receives one. A call your agent makes itself, to a room or a phone number, does not pass through Aetherfy, so Aetherfy cannot see it: it sends the SIGTERM after the minute and waits for your process to exit on its own. An outbound worker must drain on SIGTERM. LiveKit Agents does by default. Pipecat ends its calls on SIGTERM by default, so it needs the handler shown on /agents/voice-agents.

The maximum: drain_timeout_minutes

The old version keeps running for at most drain_timeout_minutes, counted from the redeploy. The default is 30 minutes and the ceiling is 240 minutes (4 hours), the same for every plan and for always-on agents. Set it in aetherfy.yaml; it is refused on a type: job agent, which is not kept running for a release.

It exists because a connection that never closes would otherwise keep the replaced version running for good: with its old code, its still-valid key, one more old machine for every redeploy, and the bug that the redeploy fixed still serving those calls.

At the maximum, a call that comes through your agent’s address is closed with close code 1012 (service restart) and the reason release replaced: call time limit reached, whatever the runtime, and your process is sent SIGTERM if it has not had it, and gives it the share of the stop window above that your server gets, to exit. A replaced version therefore runs for at most drain_timeout_minutes plus that share. A client that sees 1012 can reconnect: the new connection reaches the new version. A call your agent made itself is not closed by Aetherfy, and ends when your process does. If your worker has its own drain timeout, keep it at or below drain_timeout_minutes: LiveKit Agents defaults to 3600 seconds, so pass --drain-timeout or raise drain_timeout_minutes, or Aetherfy stops the worker at the maximum and an outbound call gets no close from Aetherfy.

What a redeploy costs while it drains

A redeploy keeps the previous version running for about a minute after the new one serves, and longer while a call is open, up to the maximum. That time is billed as awake time until the machine stops, on top of the new version’s machine (/platform/billing): the old version is awake serving requests and calls. The minute is a quiet window that starts again whenever a request or a new connection reaches the old version, and it ends the drain only when nothing is open.

Requests during the swap

A request that is new may still reach the old version for a few seconds after the replacement is live, because Aetherfy’s routing takes a moment to follow the swap. The old version serves it, as it serves a new call that starts in those first seconds: such a call can run on the previous version until it ends, up to the maximum. A request that reaches the old version after its server has been told to stop is answered 503 AGENT_DRAINING with a Retry-After; it was not run, so send it again and it reaches the new version. An HTTP request already in flight keeps running on the old version until it finishes, up to the maximum.

The 120 seconds is a service figure. A job agent gets a much shorter grace period, because a task is expected to end on its own — see /agents/task-contract.

The type is set in configuration, not chosen at deploy time:

runtime: python3.12 type: job

How Aetherfy agents are configured

One file describes an Aetherfy agent: aetherfy.yaml, at the root of the code you upload. It is required. Aetherfy also accepts the filenames aetherfy.yml, .aetherfy.yaml, and .aetherfy.yml, in that priority order.

The file declares the runtime, the type, memory, the entrypoint, an optional schedule, and an optional workspace. Every deploy applies the whole file, so a field you omit takes its default rather than keeping the value the agent had. The complete field table and the rules are on /agents/aetherfy-yaml.

Aetherfy supports these runtimes, and only these:

FamilyValues
Pythonpython3.11, python3.12, python3.13, python3.14, python3.15
Nodenode22, node24, node26, node22-ts, node24-ts, node26-ts
Bunbun
Containerdockerfile

python on its own is not a valid runtime on Aetherfy. Older published examples showed runtime: python; that value fails the deploy. Write the full version, for example runtime: python3.14.

The runtime is fixed by the agent’s first release that goes live. Changing it after that is rejected with RUNTIME_IMMUTABLE (HTTP 422); to move an agent to a different runtime, delete it and recreate it.

Deploying to Aetherfy

Aetherfy offers two deploy paths, and they produce the same result.

PathHow it startsBest for
CLIafy deploy uploads the current directoryLocal development, CI steps, first deploy
GitHubA push to the tracked branch triggers a deploymentOngoing delivery from a repository

The CLI binary is afy. Install it by following /cli; the command surface for agents is catalogued at /cli/agents. To go from an empty directory to a running agent in one sitting, follow /agents/quickstart.

The GitHub path uses an Aetherfy GitHub App. Once a repository is linked to an agent, a push to the tracked branch makes Aetherfy clone the repository at the pushed commit, re-parse aetherfy.yaml, and deploy. Auto-deploy can be paused on the link without unlinking it. Setup is on /agents/github.

Deployments, runs, and workspaces on Aetherfy

Three nouns carry most of the meaning in Aetherfy agent compute.

NounWhat it is
DeploymentOne version of an agent. Building an image produces a deployment.
RunAn ephemeral execution of a job agent. A run reuses the agent’s existing image, with no build step — unless that image is no longer available, in which case the run first rebuilds it from the agent’s stored source.
WorkspaceA group of agents that share secrets and can discover each other.

Every Aetherfy run carries a trigger source that records why it happened:

trigger_sourceMeaning
cronFired by the agent’s schedule
manualStarted on demand, with afy run
spawnStarted by a parent agent

Every agent lives in exactly one workspace, chosen when it is created and changed by moving the agent. Secrets set on a workspace are visible to every agent in it; secrets set on an agent override workspace secrets with the same key. See /agents/secrets.

Anything an Aetherfy agent writes to the vector database is attributed automatically, through the API key Aetherfy injects, to that agent and to the version that wrote it: the deployment, or for a task the run. See attested authorship.

That injected key reaches only the collections of the agent’s own workspace, and of any workspace you grant it with afy access or on the agent’s page in the dashboard: a collection in any other workspace is refused to it. See what an agent’s key reaches.

Regions and plans for Aetherfy agents

Where an Aetherfy agent runs depends on your plan. The regions Aetherfy accepts are us-east-1, eu-central-1, and ap-southeast-1.

PlanRegional behaviour
FreeOne region per workspace, chosen when the workspace is created
StarterOne region per workspace, chosen when the workspace is created
PerformanceMulti-region
EnterpriseMulti-region

Multi-region placement begins at the plan named Performance. On Free and Starter, each Aetherfy workspace operates in one region, which you choose when you create the workspace, rather than per agent. Your plan also bounds the memory an agent may request and whether it may stay always-on. See /platform/regions and /platform/limits.

Map of the Aetherfy agents documentation

PageWhat it covers
/agents/quickstartGet an API key, install nothing else, deploy a working agent, read its logs
/agents/aetherfy-yamlEvery configuration field, what an omitted field means, archive limits, lockfile requirements
/agents/scheduled-tasksThe schedule: field, the 5-field UTC cron expression format, what Aetherfy rejects
/agents/task-contractHow your code runs and exits, how it reads its input payload, the at-most-once guarantee
/agents/managingRunning on demand, pausing and resuming a schedule, overlaps and missed windows
/agents/runs-and-logsRun history, run and agent states, log retrieval flags and retention limits
/agents/metricsWhat each compute figure counts, its source, and why activity is not a fleet count
/agents/secretsAgent-scoped and workspace-scoped secrets, key rules, reserved names
/agents/githubConnecting the GitHub App, linking a repository, what a push does
/agents/rollbackReturning an agent to an earlier deployment without rebuilding
/examples/agent-with-memoryA worked example combining an agent with the Aetherfy vector database
Last updated on