afy init, deploy, deployments, redeploy, and rollback
The Aetherfy deployment commands
Five Aetherfy CLI commands cover the path from an empty directory to a running agent and back again.
| Command | Purpose |
|---|---|
afy init [path] | Create an agent for this folder, or link the folder to an existing one |
afy deploy [path] | Upload the code to the agent this folder is linked to, build an image, and deploy it |
afy deployments <agent> | List the agent’s deployment history |
afy redeploy <agent> [version] | Rebuild a version from its stored source, with the agent’s current secrets |
afy rollback <agent> [version] | Re-deploy a previously built version |
A first deployment on Aetherfy is normally two commands:
afy init
afy deployafy init creates the agent in a workspace, writes aetherfy.yaml, and links the
folder to the agent. afy deploy then goes to that agent. A deploy never creates
an agent.
The link between a folder and its agent
A folder is linked to its agent by .aetherfy/agent.json, a file the CLI writes and
you commit:
{
"targets": {
"default": "6f1c2b7e-0a2d-4f8e-9c31-2b0d5a7e4411"
}
}Each target maps a name to an agent id, never to a name. Renaming the agent, or moving it to another workspace, does not unlink the folder, and a deploy cannot land on a different agent that later took the old name.
Commit .aetherfy/. The link is what makes every clone and every CI job deploy
to the same agent. The CLI warns when git will not carry it:
| Situation | Warning |
|---|---|
| The file is not committed | .aetherfy/agent.json is not committed. Commit it so every clone and CI job deploys to the same agent. |
A .gitignore rule hides it | .aetherfy/agent.json is ignored by git. Unignore and commit it so every clone and CI job deploys to the same agent. |
The folder is in a repository but git is not on the PATH | This folder is in a git repository, but git is not on PATH: could not check that .aetherfy/agent.json is committed. Commit it so every clone and CI job deploys to the same agent. |
Outside a git repository the CLI says nothing. A deploy that cannot find its agent is refused, and every refusal names the command that fixes it:
| Situation | The refusal says |
|---|---|
| The folder has no link file | This folder is not linked to an agent (no .aetherfy/agent.json). Link it to an existing agent with afy init --agent <name>, or create one with afy init. A deploy never creates an agent |
| The folder has no such target | This folder has no target <target> (its targets: …). Link one with afy init --agent <name> --target <target> |
| The target links an agent the account does not have | Target <target> links agent <id>, which this account does not have (deleted, or another account’s). Relink with afy init --agent <name> |
Creating or linking an agent with afy init
afy init [path] sets a folder up to deploy to an agent. The path argument is
optional and defaults to .. It works in two ways:
- With no
--agent, it creates a NEW agent. It scans the folder (detecting the runtime and entrypoint), asks which workspace the agent lives in and how it runs, creates the agent, writesaetherfy.yaml, and links the folder. The runtime it detects is one the platform offers: a version your project asks for that is no longer offered (a Node release that has reached its end of life, say) is moved up to the lowest offered version above it, and the command says so; a project that names no version getspython3.14for Python ornode24for Node. - With
--agent <name>, it links the folder to an EXISTING agent. If the folder has noaetherfy.yamlyet, it writes the agent’s configuration as one: the live release’s exported configuration, or, for an agent that has never been released, a new file generated from the folder. An existingaetherfy.yamlis kept unless you pass--force. This also works in an empty folder.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--name | string | the folder’s name | Name of the new agent (skips the prompt) | |
--agent | string | empty | Link this folder to this existing agent instead of creating one | |
--target | string | default | Name of the link written; the folder’s other targets are kept | |
--workspace | string | empty | Workspace the new agent lives in (asked when the account has several) | |
--runtime | string | detected | A runtime the server accepts (afy init lists them; skips the prompt) | |
--entrypoint | string | detected | Entrypoint file, e.g. main.py or index.js (skips the prompt) | |
--type | string | service | Agent type: service or job (skips the prompt) | |
--region | string | see below | A region your plan allows in the workspace (skips the prompt) | |
--memory | int | the smallest allowed | Memory in MB, a size your plan allows (skips the prompt) | |
--keep-alive | bool | false | Make the agent always-on: it never sleeps. What it costs depends on your plan and memory (/platform/billing); on Free it costs nothing and the agent is paused once it has been awake for 75% of the month. Skips the billing prompt | |
--force | -f | bool | false | Overwrite an existing aetherfy.yaml without asking |
--yes | -y | bool | false | Accept every prompt’s default (non-interactive) |
--schedule | string | empty | Schedule: runs the agent as a scheduled task on a 5-field cron expression in UTC, min every 5 minutes, e.g. '0 3 * * *' |
--workspace takes a workspace name. With one workspace in the account, that
one is used; with several you are asked, and without a terminal --workspace is
required. Which regions and memory sizes are offered, and which runtimes, is read
from the server: only what your plan allows in that workspace.
Interactive by default; any flag above skips its prompt. Every choice is a
numbered list, and the line shows the default’s number in brackets. Type a choice as
its number, its full text or its first word (service for service, 1 for the
first line), or press Enter on an empty line to take the default. Anything else is
refused with exit code 2 and "x" is not one of 1-N for <question>. Nothing was done., and input that ends before a question is answered is refused the same way
(no answer: the input ended before the question was answered. Nothing was done),
so a script never lands on a guess. A text question (the name, for one) also takes
an empty line as its default. A file named aetherfy.yaml that
already exists is a question in a terminal (aetherfy.yaml already exists. Overwrite [y/N]; a no exits 1 with Cancelled: aetherfy.yaml was kept) and a
refusal without one, exit 2 before asking: This overwrites aetherfy.yaml; pass --force to confirm without a prompt.
# Interactive
afy init
# Fully specified, non-interactive
afy init ./services/scraper \
--name catalogue-scraper \
--workspace research \
--runtime python3.12 \
--entrypoint main.py \
--type job \
--region eu-central-1 \
--memory 512 \
--schedule '0 3 * * *' \
--yes
# Link this folder to an existing agent
afy init --agent invoice-parserThe two boolean shortcuts:
| Flag | Effect |
|---|---|
--yes / -y | Accepts every prompt’s default. It does not imply --force. |
--force / -f | Overwrites an existing aetherfy.yaml. Required even alongside -y. |
The non-interactive defaults Aetherfy applies under --yes:
| Setting | Default |
|---|---|
| Name | The directory name |
| Workspace | The account’s only workspace; with several, --workspace is required |
| Type | service |
| Region | The workspace’s first region |
| Memory | The smallest size your plan allows |
| Always-on | Off |
| Runtime | Detected — afy init --yes fails if the runtime cannot be detected |
The first line of the generated aetherfy.yaml is the editor line
# yaml-language-server: $schema=https://docs.aetherfy.com/aetherfy-yaml.schema.json,
which gives editors autocomplete and checks for the file. See
the aetherfy.yaml reference.
The file holds how the agent runs; its name and workspace are the platform’s, so
they are not in it.
The schedule prompt appears for either type in interactive mode. The
resulting schedule: key is what makes the agent a scheduled task; see
/agents/scheduled-tasks.
Staging and production: one codebase, two agents
Targets deploy one codebase to several agents. Link a second agent under another target name, and commit the result:
afy init --agent invoice-parser --target default
afy init --agent invoice-parser-staging --target stagingDeploys then differ only by --target, so two CI jobs can share one script:
afy deploy --target staging # on every merge
afy deploy # on a release tagTwo ways to keep their data apart:
- A staging workspace, with its own agent, collections and secrets. The platform enforces the wall: staging’s key cannot reach production’s collections.
- One workspace, separate collection names, taken from a per-agent secret (for
example
COLLECTION_PREFIX=staging-). Easier to set up, but a convention of your code, not a wall: either agent’s key reaches both.
Deploying to Aetherfy with afy deploy
afy deploy [path] validates the manifest, archives the directory, uploads it to
the agent the folder is linked to, builds an image, and deploys it. The path
argument is optional and defaults to .; the link is read from that folder.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--detach | -d | bool | false | Return immediately after upload without waiting for completion |
--target | string | default | Which of the folder’s linked agents to deploy to | |
--from-github | string | empty | Deploy the code of a public GitHub repo: owner/repo[@ref] | |
--yes | -y | bool | false | Skip the overage confirmation prompt and proceed (non-interactive) |
# Deploy the current directory to its linked agent
afy deploy
# Deploy to the folder's "staging" target
afy deploy --target staging
# Deploy a subdirectory, non-interactively, in CI
afy deploy ./services/scraper --yes
# Upload and return immediately
afy deploy --detachThe order of operations is: read the link, validate aetherfy.yaml, archive the
project directory as a gzipped tarball, upload, build the image, deploy.
afy deploy is one of the Aetherfy commands that exits 1 on failure, so it is
safe to rely on its status in a pipeline. That includes a deployment that fails
after the upload, and a wait that runs out before the deployment finishes;
afy redeploy and afy rollback exit the same way.
When the Aetherfy control plane has something to tell you about the release, afy deploy
prints it right after the release is accepted, as a Warning: line in the control
plane’s own words, and the exit code does not change. Today that is the warning that the
agent’s runtime has passed its end of life: it names the day deploys on it stop and the
runtime to create a new agent on (see the warnings on a deployment).
With --json the warnings are in the warnings array of the deployment.
Every command whose answer carries these warnings prints them, wherever they sit in the
answer: afy redeploy, afy rollback and afy cancel on the release; afy status,
afy create, afy update and afy init --agent on the agent; a move by
afy update --workspace on the redeploy it starts; and afy list and afy deployments,
which say each sentence once with the agents or the versions it covers.
A deploy applies the whole aetherfy.yaml: a field the file leaves out takes its
default, never the value the agent had before. Preview the result first with
afy diff.
Files excluded from an Aetherfy deploy archive
The archive respects a .afyignore file in the project directory. On top of
whatever it contains, the Aetherfy CLI always excludes these built-in defaults:
| Pattern |
|---|
.git |
.gitignore |
.env |
.env.* |
__pycache__ |
*.pyc |
*.pyo |
.pytest_cache |
.mypy_cache |
node_modules |
.npm |
venv |
.venv |
env |
.DS_Store |
Thumbs.db |
*.log |
.afyignore |
Because .env and .env.* are excluded unconditionally, environment values must
reach the agent as Aetherfy secrets rather than as files — see
/cli/secrets.
An example .afyignore:
tests/
fixtures/
*.ipynb
docs/Deploying to Aetherfy directly from a public GitHub repository
--from-github owner/repo[@ref] deploys the code of a public GitHub repository
without a local clone, to the agent this folder is linked to. The repository
supplies the code only: which agent it goes to is the folder’s link (and
--target).
afy deploy --from-github myorg/my-agent
afy deploy --from-github myorg/[email protected]
afy deploy --from-github myorg/my-agent@8f2c1b0d9e4a7c3f5b1d6e8a0c2f4b6d8e0a2c4f| Detail | Value |
|---|---|
| Ref default | main |
| Accepted refs | Branch, tag, or a full 40-character commit SHA |
| Local requirement | git must be installed locally |
| Repository visibility | Public only |
For private repositories and push-triggered deploys, use the Aetherfy GitHub App instead — see /cli/github.
Aetherfy plan overage confirmation on deploy
If a deployment would push your account’s usage beyond the plan allowance, the Aetherfy CLI asks for confirmation before proceeding.
--yesaccepts the prompt and proceeds non-interactively.- Answering no exits
1withCancelled: nothing was deployed, never0. - Without
--yesin a non-interactive shell the command exits2, before asking, and tells you to pass it:This deployment adds ~$<n>/mo of usage; pass --yes to confirm without a prompt.
CI pipelines that deploy to Aetherfy should therefore always pass --yes:
export AETHERFY_API_KEY=afy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
afy deploy --yesPlan allowances are documented at /platform/limits.
Aetherfy runs one deployment per agent at a time. Starting a second while the
first is still building or deploying returns HTTP 409 DEPLOYMENT_IN_PROGRESS, and so
does one started while a push of the agent is being prepared.
This is worth handling in CI, where two pushes in quick succession are the
normal way to hit it: wait for the first to reach a terminal state, or cancel it
with afy cancel <agent> before starting another.
Partially successful multi-region Aetherfy deployments
A deployment that succeeds in some regions and not others is reported by the Aetherfy CLI as:
Deployment is serving but DEGRADED — N/M regions ready.The agent is serving traffic from the regions that came up. Check
afy status <name> for the per-region detail, and afy logs <name> for
the failure reason in the regions that did not.
Listing Aetherfy deployment history
afy deployments <agent> lists the agent’s releases, newest first, 20 at a time. A run
is not a deployment: the agent’s runs are afy agents runs. It takes one required argument and honours --json.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--since | string | none | Only deployments created within this long ago: a whole number followed by s, m, h or d (30m, 24h, 7d), the form afy logs --since takes |
--status | string | none | Only deployments in this state, for example failed |
--limit | integer | 20 | How many to show, 1 to 100 |
--before | string | none | The deployment id to continue after: the previous page’s next page id |
afy deployments catalogue-scraper
afy deployments catalogue-scraper --status failed --since 7d
afy deployments catalogue-scraper --limit 50 --before 0b7d1f66-3a9e-4c25-9f10-77c2b4e51a08
afy deployments catalogue-scraper --jsonA bad --limit or --since is refused with a sentence before anything is sent. When
older deployments exist the last line says how to read them, as afy points list does
for points: More deployments: pass --before <id> for the next page. The paging is by
position, not by offset, so a deployment created between two pages moves nothing. With
--json the output is an object, {"deployments": [...], "next_before_id": ...}, where
next_before_id is the id to pass as --before and is null on the last page.
The lines about the latest deployment below (a suggested rollback, the build output, a
partially deployed latest) and the pushes preparing and waiting are printed only for the unfiltered first
page, because with --since, --status or --before the first row is not the latest.
| Column | Meaning |
|---|---|
| Version | The version number — the value you pass to afy rollback |
| State | Deployment state, with a glyph |
| Created | When the deployment was created |
| Error | Failure reason, when there is one |
A run is not a deployment: the list holds the agent’s releases only, so a failed
run never appears in it as a version and never becomes the “latest deployment”.
List runs, with the release each executed, with afy runs
(/cli/agents). When the newest release failed, the Aetherfy CLI
prints the rollback command for the last release that went live and can be
rolled back to, and prints none when there is no such release.
State glyphs used by the Aetherfy CLI:
| Glyph | State |
|---|---|
● | active |
✗ | failed |
○ | superseded |
· | queued |
⟳ | building |
⟳ | deploying |
↩ | rolled_back |
The Error column is 60 characters wide. A longer message is cut there with an
ellipsis, and printed in full under the table as v<version> error: <message>,
because a refusal is written for the reader and its end is where the fix is: a
push without aetherfy.yaml names the repository, commit, branch and path it
looked in, and a frozen account’s refused deploy says what to reduce. afy status
shows the newest failed deploy’s full message too, as Deploy error.
When the newest deployment failed, the Aetherfy CLI prints a suggested rollback
command underneath the table, and — when the build stage is what failed — the
build output under a Build output: heading. That block is the tail of what the
failing step printed, so it says which step failed rather than repeating the
short reason in the Error column. afy deploy prints the same block when a
deploy it is watching fails.
Nothing is printed when the deployment failed somewhere other than the build — a region that never came up, or a cancellation — because there is no build output to quote.
A push to a linked repository that arrives while a deploy is in progress waits for it, and has no row in this history until it starts. The table is followed by a line naming it, so the next deploy is not missing from the history:
Push waiting: 9f8e7d6, received 2026-09-26 12:00 UTC — deploys when the deploy in progress endsA push that Aetherfy is still cloning and checking is the next entry too. It prints above the push waiting behind it, and both can show:
Push preparing: 1a2b3c4, since 2026-11-14 10:15 UTC — becomes the next deployment when it is readyRolling back an Aetherfy deployment
afy rollback <agent> [version] re-deploys a previously built version.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--detach | -d | bool | false | Return immediately without waiting for completion |
Called with only the agent name, it prints the deployment history so you can choose a version:
afy rollback catalogue-scraperCalled with a version, it rolls back to it:
afy rollback catalogue-scraper 3The version is a bare integer. afy rollback catalogue-scraper v3 is
rejected by the Aetherfy CLI with Version must be a positive integer.
| Property | Behaviour |
|---|---|
| Build step | Skipped — the target version’s already-built image is re-deployed directly |
| Valid targets | A version whose image, or whose code archive, is still stored: active, superseded and rolled_back versions, and a failed one that got as far as an image (it failed while launching or in its health check) |
| Invalid targets | A failed build, which has neither. No rollback is accepted while a deployment is queued, building or deploying |
Because the build is skipped, a rollback on Aetherfy is substantially faster than
a fresh afy deploy of the same code.
Redeploying an Aetherfy agent to apply secrets
afy redeploy <agent> [version] re-runs a version’s build from the
source archive Aetherfy stored for it.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--detach | -d | bool | false | Return immediately without waiting for completion |
This is the CLI counterpart of the dashboard’s Redeploy button
(the deployments view), and it is not
a rollback: a redeploy builds the version again from its stored source, and a
rollback re-deploys an image that already exists. Both are new deployments, and every
new deployment reads the agent’s secrets as they stand, once, before any machine is
created; an image never carries secrets. So a secret you store with afy secrets set
reaches a running service at its next deployment, whichever kind it is.
Called with only the agent name, it rebuilds the active deployment — the one whose environment a newly stored secret is missing from:
afy redeploy catalogue-scraperCalled with a version, it rebuilds that version instead:
afy redeploy catalogue-scraper 3As with afy rollback, the version is a bare integer.
| Property | Behaviour |
|---|---|
| Build step | Runs: the version’s stored source is built again |
| Secrets | The agent’s current ones, read once before any machine is created (a rollback reads them the same way) |
| Configuration | Unchanged; the archive is not re-read for memory, regions or any other setting |
| Valid targets | Versions whose stored source archive still exists |
| Archive retention | The ten most recent successful deployments; a failed build’s archive is deleted |
afy redeploy is not a retry for a failed build. Aetherfy deletes the code
archive as soon as a build fails, so nothing remains to rebuild — and re-running
the same build would fail the same way. Fix the code and run afy deploy again,
or push to the linked repository. A deployment that built successfully but failed
to launch keeps its archive, so that one can be redeployed.
A type: job agent needs no redeploy to pick up a new secret, but not because
every run is a new machine — a task agent reuses its machine between runs.
Aetherfy records which secret set each machine was created from, and refuses to
send a run to a machine whose set no longer matches; it creates a current machine
for that run instead. The value is applied, at the price of a cold start on every
run until you redeploy. Services keep their environment until they are rebuilt,
which is what this command does.