Skip to main content
A connection is one owner’s authorization to use an inference provider, holding its credential under a name. Aether inference is a connection every organization has, with nothing to store. Claude Code and Codex tasks can run on Aether inference without a stored connection; OpenCode needs a held connection. A connection’s kind is the credential it holds: a plan, an API key, an auth file, or your agent’s own login on its host. An option qualifies the kind by its vendor. Works with says which harness an option runs on: Connections are named, and any option can be held more than once: two Claude plans and an Anthropic API key can coexist. Saving one never touches another. Names are unique per option, so a second add of the same option needs a different name.

​
Default connection

You have a default connection for each harness. Tasks use it when neither their own setting nor a profile pin says otherwise.
  • The first task-usable connection you add becomes the default when none was chosen. Your agent’s own host login is not task-usable and never becomes a task default.
  • Adding a second connection never moves the default. Choose Make default for Claude Code tasks, Make default for Codex tasks, or Make default for OpenCode tasks from a row’s menu in Settings → Connections to move it yourself.
  • Disconnecting the default is refused while you hold another task-usable connection for that harness. Choose a different default first.
  • Disconnecting the last task-usable connection sets the default to Aether inference for Claude Code and Codex. For OpenCode it removes the default: Aether inference does not serve OpenCode, so choose or add a connection before another turn can run.
  • With nothing ever chosen, Claude Code and Codex tasks run on Aether inference by rule. OpenCode tasks are refused until you add a connection.
A connection running your personal agent or pinned by a profile cannot be disconnected until you move that agent or profile. Claude Code and Codex tasks that run on a disconnected row follow their harness’s default. Affected OpenCode tasks always need an explicit connection choice, even when another OpenCode connection is the default. A turn’s record of what it ran on keeps its name and option even after rename or disconnect.

​
Add a connection

Every connection lives in one collection on the API: GET /connections lists them all, each with its option, which decides the agents it works with. Each option’s add route is named by its slug, the option with hyphens for underscores (openrouter_api_key is openrouter-api-key): POST /connections/{slug} adds one, and POST /connections/{id}/reconnect reconnects one in place with a credential of its option. A ChatGPT plan is added and reconnected through its device flow instead, and your agent’s own ChatGPT login is never added here. PATCH /connections/{id} renames a connection and DELETE /connections/{id} removes it. See the Connections API. Connect from the web app under Settings → Connections, or with the CLI. Each provider’s CLI commands share the same shape:
  • connect (and api-key where the provider takes one) adds a connection under --name. Without --name, the connection is named after its option, for example Claude plan.
  • reconnect --name <name> refreshes an existing plan or auth file in place; api-key --reconnect <name> rotates a held key. The id stays unchanged, so your agent, profiles and tasks keep pointing at the same row.
  • status lists every connection the agent works with, with whether it needs re-authentication.
  • The disconnect command removes one connection by name. If you hold only one, you can omit the name; see each harness’s CLI reference for its command.

​
Codex

Codex works with a ChatGPT plan connected by device login, or an OpenAI API key.
In Settings → Connections, choose Add, pick the ChatGPT plan or the OpenAI API key, name the connection, and either start the device login or paste the key.
The device flow stores plan credentials that Aether refreshes as needed. One ChatGPT account can be only one of your connections. The device flow starts at POST /connections/chatgpt-plan/device-auths, which carries mode add with the new connection’s name, or mode reconnect with the connection_id of the ChatGPT plan it reconnects, and answers the sign-in’s id; GET /connections/chatgpt-plan/device-auths/{id} reads it until it is complete. A key is sent to POST /connections/openai-api-key.

​
Claude Code

Claude Code authenticates with a Claude plan’s setup token or an Anthropic API key.
In Settings → Connections, choose Add, pick the Claude plan or the Anthropic API key, name the connection, and paste the setup token printed by claude setup-token or the key.
The token is sent to POST /connections/claude-plan and a key to POST /connections/anthropic-api-key.

​
OpenCode

OpenCode authenticates with the auth.json file written by your local OpenCode login (opencode auth login). The file is uploaded verbatim and materialized into each task’s config directory at session start.
In Settings → Connections, choose Add, pick OpenCode auth file and name the connection. Follow the CLI command shown, then click Check status.
The file is sent to POST /connections/opencode-auth-file.
OpenCode models routed through OpenRouter can use your own OpenRouter API key. aether opencode api-key, or the OpenRouter API key option under Add, adds it as a connection of its own, sent to POST /connections/openrouter-api-key. See Agents and models.

​
Refresh an existing connection

Use reconnect, not connect, when a setup token expires or a key changes. Reconnect never adds a second connection:
An unknown name fails and lists the connections you hold. Names are unique per option, so reconnect selects the requested option when two options share a name. A name held only under another option returns the API’s connection_option_mismatch sentence unchanged. API-key --name (add) and --reconnect (replace) cannot be used together. aether setup offers to reconnect a flagged connection instead of adding another. If several connections need re-authentication, it asks which one to reconnect. API keys are entered at a secure prompt. A provider with a healthy connection is already configured and is skipped by setup; use the commands above to refresh another row.

​
Next Steps

Agents and Models

Pick the agent, model, and reasoning effort per task.

Tasks

Choose what your task runs on.