afy init, deploy, deployments, and rollback

The Aetherfy deployment commands

Four Aetherfy CLI commands cover the path from an empty directory to a running agent and back again.

A first deployment on Aetherfy is normally two commands:

afy init
afy deploy

Generating an Aetherfy manifest with afy init

afy init [path] scans a directory, detects the runtime and entrypoint, and writes an aetherfy.yaml manifest. The path argument is optional and defaults to ..

Interactive by default; any flag above skips its prompt.

# Interactive
afy init
 
# Fully specified, non-interactive
afy init ./services/scraper \
  --name catalogue-scraper \
  --runtime python3.12 \
  --entrypoint main.py \
  --type job \
  --region eu-central-1 \
  --memory 512 \
  --schedule '0 3 * * *' \
  --yes

Behaviour of the two boolean shortcuts in the Aetherfy CLI:

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

The schedule prompt appears only for job type in interactive mode. The resulting schedule: key is what makes the agent a scheduled task; see /agents/scheduled-tasks and the full manifest reference at /agents/aetherfy-yaml.

Deploying to Aetherfy with afy deploy

afy deploy [path] validates the manifest, archives the directory, uploads it to Aetherfy, builds an image, and deploys it. The path argument is optional and defaults to ..

# Deploy the current directory
afy deploy
 
# Deploy a subdirectory, non-interactively, in CI
afy deploy ./services/scraper --yes
 
# Upload and return immediately
afy deploy --detach
 
# Target an agent explicitly
afy deploy --agent catalogue-scraper

The order of operations is: 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.

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:

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 from a public GitHub repository without a local clone.

afy deploy --from-github aetherfy/examples
afy deploy --from-github aetherfy/examples@v1.2.0
afy deploy --from-github aetherfy/examples@8f2c1b0d9e4a7c3f5b1d6e8a0c2f4b6d8e0a2c4f

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.
• Without --yes in a non-interactive shell the command fails and tells you to re-run with --yes.

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. 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 agents 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 agents 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 deployments, newest first. It takes one required argument and has no flags of its own; it honours the global -o json.

afy deployments catalogue-scraper
afy deployments catalogue-scraper -o json

State glyphs used by the Aetherfy CLI:

When the newest deployment failed, the Aetherfy CLI prints a suggested rollback command underneath the table.

Rolling back an Aetherfy deployment

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

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.

Because the build is skipped, a rollback on Aetherfy is substantially faster than a fresh afy deploy of the same code.