Configuration
Most settings are in the app (⌘,), which has a searchable two-pane layout. This page covers what is on disk.
Config folder
Section titled “Config folder”| Platform | Location |
|---|---|
| macOS | ~/Library/Application Support/aether |
| Linux | $XDG_CONFIG_HOME/aether, or ~/.config/aether when XDG_CONFIG_HOME is unset |
On macOS, if ~/Library/Application Support/aether/settings.json does not exist but $XDG_CONFIG_HOME/aether/settings.json (or ~/.config/aether/settings.json) does, Aether uses the XDG folder instead. Existing installs never migrate by surprise.
The folder is created readable by your user only.
What’s inside
Section titled “What’s inside”| Path | Contents |
|---|---|
settings.json |
All settings. |
aether.db |
Chats, transcripts and per-chat provider, model, access and effort (SQLite). |
attachments/ |
Copies of files attached to messages. Every CLI must be able to read this folder. |
skills/ |
Aether’s own skills, one <name>/SKILL.md folder each. |
orchestrator.sock |
The Unix socket lead chats’ MCP server talks to while Aether runs. |
pi-lead.ts |
The Pi extension Aether writes for Pi lead chats. |
Settings you may edit by hand
Section titled “Settings you may edit by hand”| Key | Default | Meaning |
|---|---|---|
max_children |
8 |
How many children a lead chat can run at once. Clamped to 1 to 50. |
Elsewhere on disk
Section titled “Elsewhere on disk”- OpenRouter API key: the system keychain, never
settings.json. - Notes:
~/notesby default, set in Settings > Tools > Notes. - Dictation model: downloaded on first use, removable from Settings > Composer.
Environment variables
Section titled “Environment variables”| Variable | Used by |
|---|---|
AETHER_ORCH_SOCK |
aether mcp: the socket path. Defaults to orchestrator.sock in the config folder. |
AETHER_ORCH_TOKEN |
aether mcp: the lead token. See manual setup. |
XDG_CONFIG_HOME |
The config folder location. |
Development builds also read a local .env. Packaged builds never include .env or credentials.