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

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.

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

An agent belongs to at most one workspace, declared with the workspace field in aetherfy.yaml:

name: my-agent
runtime: python3.12
workspace: my-workspace

Workspace names on Aetherfy are immutable after creation, so a workspace-scoped secret’s audience is stable — moving an agent means changing which workspace it declares, not renaming the workspace.

Deleting an Aetherfy secret

afy secrets delete my-agent API_KEY

afy secrets delete always asks for confirmation on Aetherfy. There is deliberately no --force flag on it, so it cannot be made silent in a script.

Secret key rules on Aetherfy

Reserved names Aetherfy rejects

The entire AETHERFY_ prefix is reserved. Attempting to set any key beginning with it is rejected, which prevents a secret from shadowing the environment Aetherfy provides to your agent.

These exact names are reserved:

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 at deploy or run time, so a running machine keeps the value it started with. A new value takes effect on the next deploy or the next run.

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

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

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

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 7 days — see /agents/runs-and-logs. Log the presence of a secret, as above, never its contents.