Skip to Content
CLIafy deploy & deployments
Raw

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.

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

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

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:

SituationWarning
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 PATHThis 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:

SituationThe refusal says
The folder has no link fileThis 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 targetThis 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 haveTarget <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, writes aetherfy.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 gets python3.14 for Python or node24 for Node.
  • With --agent <name>, it links the folder to an EXISTING agent. If the folder has no aetherfy.yaml yet, 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 existing aetherfy.yaml is kept unless you pass --force. This also works in an empty folder.
FlagShortTypeDefaultDescription
--namestringthe folder’s nameName of the new agent (skips the prompt)
--agentstringemptyLink this folder to this existing agent instead of creating one
--targetstringdefaultName of the link written; the folder’s other targets are kept
--workspacestringemptyWorkspace the new agent lives in (asked when the account has several)
--runtimestringdetectedA runtime the server accepts (afy init lists them; skips the prompt)
--entrypointstringdetectedEntrypoint file, e.g. main.py or index.js (skips the prompt)
--typestringserviceAgent type: service or job (skips the prompt)
--regionstringsee belowA region your plan allows in the workspace (skips the prompt)
--memoryintthe smallest allowedMemory in MB, a size your plan allows (skips the prompt)
--keep-aliveboolfalseMake 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-fboolfalseOverwrite an existing aetherfy.yaml without asking
--yes-yboolfalseAccept every prompt’s default (non-interactive)
--schedulestringemptySchedule: 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-parser

The two boolean shortcuts:

FlagEffect
--yes / -yAccepts every prompt’s default. It does not imply --force.
--force / -fOverwrites an existing aetherfy.yaml. Required even alongside -y.

The non-interactive defaults Aetherfy applies under --yes:

SettingDefault
NameThe directory name
WorkspaceThe account’s only workspace; with several, --workspace is required
Typeservice
RegionThe workspace’s first region
MemoryThe smallest size your plan allows
Always-onOff
RuntimeDetected — 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 staging

Deploys 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 tag

Two 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.

FlagShortTypeDefaultDescription
--detach-dboolfalseReturn immediately after upload without waiting for completion
--targetstringdefaultWhich of the folder’s linked agents to deploy to
--from-githubstringemptyDeploy the code of a public GitHub repo: owner/repo[@ref]
--yes-yboolfalseSkip 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 --detach

The 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
DetailValue
Ref defaultmain
Accepted refsBranch, tag, or a full 40-character commit SHA
Local requirementgit must be installed locally
Repository visibilityPublic 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.

  • --yes accepts the prompt and proceeds non-interactively.
  • Answering no exits 1 with Cancelled: nothing was deployed, never 0.
  • Without --yes in a non-interactive shell the command exits 2, 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 --yes

Plan 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.

FlagTypeDefaultMeaning
--sincestringnoneOnly 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
--statusstringnoneOnly deployments in this state, for example failed
--limitinteger20How many to show, 1 to 100
--beforestringnoneThe 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 --json

A 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.

ColumnMeaning
VersionThe version number — the value you pass to afy rollback
StateDeployment state, with a glyph
CreatedWhen the deployment was created
ErrorFailure 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:

GlyphState
●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 ends

A 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 ready

Rolling back an Aetherfy deployment

afy rollback <agent> [version] re-deploys a previously built version.

FlagShortTypeDefaultDescription
--detach-dboolfalseReturn 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-scraper

Called with a version, it rolls back to it:

afy rollback catalogue-scraper 3

The version is a bare integer. afy rollback catalogue-scraper v3 is rejected by the Aetherfy CLI with Version must be a positive integer.

PropertyBehaviour
Build stepSkipped — the target version’s already-built image is re-deployed directly
Valid targetsA 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 targetsA 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.

FlagShortTypeDefaultDescription
--detach-dboolfalseReturn 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-scraper

Called with a version, it rebuilds that version instead:

afy redeploy catalogue-scraper 3

As with afy rollback, the version is a bare integer.

PropertyBehaviour
Build stepRuns: the version’s stored source is built again
SecretsThe agent’s current ones, read once before any machine is created (a rollback reads them the same way)
ConfigurationUnchanged; the archive is not re-read for memory, regions or any other setting
Valid targetsVersions whose stored source archive still exists
Archive retentionThe 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.

Last updated on