Skip to Content
Raw

Secrets

What Aetherfy secrets are

A secret on Aetherfy is a named value — an API key, a database URL, a signing token — that Aetherfy stores encrypted at rest with AES-256 and injects into your agent’s machine as a plain environment variable at deploy or run time.

Your code reads them exactly as it reads any environment variable. There is no SDK call and no fetch step.

Values are never readable back. The Aetherfy CLI and API return only keys and metadata. Once you set a secret you cannot retrieve its value from Aetherfy by any route — if you lose it, rotate it at the source and set it again.

The two secret scopes on Aetherfy

Every Aetherfy secret has exactly one scope.

ScopeVisible toSet with
Agent-scopedOne agentafy secrets set <agent> KEY=value
Workspace-scopedEvery agent in that workspaceafy secrets set --workspace <workspace> KEY=value

When both scopes define the same key, the agent-scoped secret wins — it overrides the workspace-scoped value for that agent only. Every other agent in the workspace continues to see the workspace value.

That precedence is the intended way to give one agent a different credential from its siblings without splitting the workspace or duplicating the shared secrets across every agent.

Both scopes are settable from either surface. This page shows the CLI throughout; the dashboard offers the same two scopes and lists every secret with the agent or workspace it belongs to, at app.aetherfy.com/dashboard/secrets  (see Secrets in the dashboard). The precedence rule above is enforced at deploy time and applies whichever surface set the secret.

Setting and listing Aetherfy secrets

Set one or more secrets on an agent in a single command:

afy secrets set my-agent API_KEY=sk-xxxxx DB_URL=postgres://user:pass@host/db

Setting a key that already exists updates it — Aetherfy treats this as an upsert, not an error.

To keep a value out of your shell history and out of the process list, pipe it in instead:

echo "sk-xxxxx" | afy secrets set my-agent API_KEY --stdin

List the keys Aetherfy holds for an agent. Only keys and metadata come back, never values:

afy secrets list my-agent

Aetherfy enforces no limit on the number of secrets an agent may have, and no maximum value size.

Workspace-scoped Aetherfy secrets

Secrets shared by every agent in a workspace are set against the workspace rather than an agent:

afy secrets list --workspace my-workspace afy secrets set --workspace my-workspace SHARED_API_KEY=sk-xxxxx afy secrets delete --workspace my-workspace SHARED_API_KEY

Every agent lives in exactly one workspace, chosen when it is created and changed only by moving it. A workspace secret follows the workspace, not its name: renaming the workspace keeps its secrets and the agents that receive them, and moving an agent to another workspace gives it that workspace’s secrets instead, from the redeploy the move makes.

Deleting an Aetherfy secret

afy secrets delete my-agent API_KEY

afy secrets delete asks [y/N] first on Aetherfy; answering no exits 1. A script passes --yes to delete without the question, and without it (and without a terminal) the command is refused with exit 2, so a pipeline cannot delete by accident. See /cli/secrets.

Secret key rules on Aetherfy

RuleDetail
Length1–255 characters
First characterA letter or an underscore
Remaining charactersLetters, digits, _, and -
KeyValid on Aetherfy
API_KEYYes
_INTERNAL_TOKENYes
db-url-2Yes
2ND_KEYNo — starts with a digit
MY.KEYNo — . is not allowed

Reserved names Aetherfy rejects

The rule is the prefix, and only the prefix: every key beginning AETHERFY_ is rejected, in any letter case, whether or not Aetherfy currently injects a variable by that name. There is no list of individually-blocked names to check against — if it starts with AETHERFY_, you cannot set it.

That is deliberately broader than the set Aetherfy injects today. The prefix belongs to the platform, so a variable added in a future release can never collide with a secret you already set.

The variables Aetherfy does inject, and which your code can read, are listed on /agents/task-contract.

If you need your own value for something in that space, give it a different name — OPENAI_API_KEY or MY_API_KEY rather than AETHERFY_API_KEY.

Changing a secret does not redeploy an Aetherfy agent

This is the most important operational fact on this page, and the one most likely to cost you an hour.

Changing a secret on Aetherfy does not redeploy or restart a running agent. Secrets are injected when a machine is created, so a machine that already exists keeps the values it was created with for its whole life. A new value takes effect on the next deploy.

Agent typeHow the new value takes effect
serviceOn its next deployment — see the three ways below. Nothing else changes it
jobOn the next run. Aetherfy sees that the machine it would have reused was created from a different secret set, and creates a new one with the current values instead — so that run pays a cold start

A job agent therefore needs no action to pick up a new secret, but it is not free: until you deploy the agent, every run that would have resumed a warm machine builds a fresh one instead. Deploy it when you are done rotating.

The three ways to apply a secret to a service

Any deployment applies the current values, so pick whichever you already have to hand. None of them needs you to change the code.

PathUse it when
Redeploy in the dashboard, on the deployments pageYou are already in the dashboard, or the code is not on the machine you are at
afy redeploy <agent>You are in a terminal but do not have the source checked out
afy deployYou have the source and are shipping a code change anyway
git push to a linked repositoryThe agent is linked to GitHub, its auto-deploy is not paused, and a push already deploys it

Redeploy and afy redeploy rebuild the running version from the source Aetherfy already stored, so they apply secrets without changing your code.

A rollback uses your secrets as they stand, too. A rollback restores an earlier release’s own code and its recorded configuration, but not its secrets: an image never carries secrets, and every new deployment, a rollback included, reads the agent’s current secrets once before it creates any machine. So if you rotated a key and then roll back to last week’s version, that version runs with the new key. To run with an old value, set the old value again first.

So after rotating a credential for a long-lived service agent:

afy secrets set my-agent API_KEY=sk-new-value afy redeploy my-agent

Without that second command the agent keeps presenting the old credential until something else redeploys it.

An Aetherfy agent is never deployed without its secrets

A deployment reads the agent’s secrets, its own and its workspace’s, once, before any machine is created, and gives every machine of that deployment the same set.

If the secrets cannot be read (Aetherfy’s database did not answer), the read is retried in place: four attempts in all, waiting 1, 2 and 4 seconds between them. The deployment is not queued again. When every attempt fails, the deployment fails with nothing built, and its error_message is this sentence:

Couldn’t read this agent’s secrets, so it wasn’t deployed. Retry the deploy.

It is plain prose with no error code; deploy again when you see it. The other paths that build an agent’s machines read the secrets themselves and fail the same way, without touching anything already running:

PathWhat happens when the secrets cannot be read
A deploy (afy deploy, a push, a redeploy, a rollback, a move)The deployment fails with the sentence above, and nothing is built
A region still pending after a deployIt stays pending and is retried on that region’s own schedule. The regions already serving are untouched
A run that needs a new machineThe run fails
A machine recreated because its host was fullThe old machine is left as it was

A secret that cannot be decrypted is a different failure: the deploy fails at once, without the retries.

Reading a secret from your Aetherfy agent code

Secrets arrive as ordinary environment variables, so read them with the standard facility for your runtime.

Python:

import os import sys api_key = os.environ.get("API_KEY") if not api_key: print("API_KEY is not set on this agent", file=sys.stderr, flush=True) sys.exit(1) print("API_KEY is present", flush=True)

Node:

const apiKey = process.env.API_KEY; if (!apiKey) { console.error('API_KEY is not set on this agent'); process.exit(1); } console.log('API_KEY is present');

Never print a secret’s value. Everything written to stdout and stderr becomes the agent’s logs on Aetherfy, and those logs are readable with afy logs for your plan’s retention (3 days on Free) — see /agents/runs-and-logs. Log the presence of a secret, as above, never its contents.

Last updated on