Environment variables hold configuration your project needs at runtime — API keys, database URLs, feature flags. They are stored per project, encrypted at rest, and injected into the agent’s process environment when a task starts.
How It Works
Project environment variables are merged into the environment of the agent process over its connection to Aether. They are not written to a .env file on disk. Anything the agent or your dev servers spawn inherits them through the normal process environment, so frameworks like Next.js, Vite, and Express pick them up the same way they pick up shell exports.
The merge order, last value winning, is:
- Base workspace variables (
PROJECT_ID, PROJECT_CWD, AETHER_API_URL)
- Your project environment variables
- Platform and connected-provider keys
If you need an actual file on disk inside the workspace — a .env, a service-account JSON, a certificate — use a secret file instead. Secret files and environment variables are separate features. Values are encrypted at rest. Listing variables shows keys only; values are never returned in a list to avoid accidental exposure.
Setting Variables
Open Settings → Environment Variables, enter the key and value, then save.
Omit --value to be prompted securely without the value appearing in your shell history:Keys must match [a-zA-Z_][a-zA-Z0-9_.]*. Listing Variables
Output shows keys and when each was last updated — values are not shown:
Getting a Variable
Prints the decrypted value to stdout, so it pipes cleanly into other commands.
Deleting a Variable
Pass --force to skip the confirmation prompt.
Importing from a File
Import variables in bulk from a .env-format file:
Read from stdin with -:
Importing merges with existing variables: a key already set is updated, and keys not present in the file are left unchanged.
When Changes Take Effect
Variables are read when the agent connects at the start of a task. Updating a variable while a task is running does not change the live process — the new value applies to the next task.
API Endpoints
Environment variables are also available through the REST API. See the API reference rather than re-describing the request and response shapes here:
