Troubleshooting

Aether can’t find a CLI

Apps launched from Finder or a desktop launcher get the desktop session’s PATH, not your shell’s. If claude, codex, pi, opencode or agy is installed somewhere like ~/.local/bin:

• add that folder to the desktop session’s PATH, or
• set the binary’s full path in Settings.

A turn seems stuck

If a turn receives no events for 60 seconds, the chat tells you, with the process state and the last event seen. Check whether an approval card is waiting, possibly from a subagent. Esc in the composer stops the turn; the CLI gets 3 seconds to finish before it is killed.

Orchestration

Check these in order.

1. The chat is a lead. The Lead chip must be on. Tools are injected when the CLI starts, so a chat started before the toggle has no aether tools until its driver restarts. Turn Lead on before the first message, or start a new chat.

2. Only one Aether owns the socket. A second instance (another user, another $HOME, a sudo launch) can’t bind orchestrator.sock and prints aether: orchestration off: another Aether owns the socket. You only see this when launching from a terminal. Close the other instance.

3. The socket exists. While Aether runs, ls -l the orchestrator.sock in your config folder. If it is missing, check that $HOME is set for the desktop session and the config folder is writable. Launching from a terminal shows the error.

4. The CLIs are on the desktop PATH. See above.

5. The MCP server answers. With Aether running:

   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' | /usr/local/bin/aether mcp

   It should print JSON with serverInfo.name set to "aether". Without AETHER_ORCH_TOKEN, an empty tools/list is correct.

6. Antigravity is registered. ~/.gemini/config/mcp_config.json should have an aether entry whose command is your Aether binary and which is not disabled. If it is stale, run agy mcp add aether /usr/local/bin/aether mcp again, or delete the entry and let Aether retry.

7. Versions match. Orchestration changed in early versions (spawn nonce, socket caps, lead respawn on toggle). Update Aether and restart the lead chat.

Linux: the window or browser panel won’t start

Aether needs a working Vulkan driver for its UI, and GTK 3 with WebKitGTK 4.1 for the browser panel. Install your distribution’s packages for those, or run scripts/setup-linux.sh on Ubuntu 24.04 or Debian 13 when building from source.