> ## Documentation Index > Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt > Use this file to discover all available pages before exploring further. # Cloud delegation > Keep working in Claude Code or Codex while Aether runs tasks in the cloud Give your local coding agent a cloud teammate. Delegate a repository review, a test investigation, or an independent change to Aether, then keep working in the same Claude Code or Codex session. Your local agent can read the result, answer follow-up questions, and bring the findings back into your work. Each delegated task runs in an Aether cloud workspace. You can follow it from your local conversation or open its task link in the web app. ## Before you start * Install the [latest Aether CLI](/cli/installation). * Use a Git checkout linked to an [Aether project](/guides/github-integration), with a [cloud agent provider connected](/guides/connect-agent-providers). * Use a stable local client on **macOS or Linux**: **Claude Code 2.1.257 or newer**, or **Codex CLI 0.153.4 or newer**. Setup accepts newer stable releases. Prerelease builds and custom `CODEX_HOME` or `CLAUDE_CONFIG_DIR` directories are currently unsupported. Both clients support linked Git worktrees. Run `aether setup` in each checkout where you want delegation. If you installed Codex delegation with an older Aether CLI, upgrade and rerun setup to update its hooks, then restart Codex and review the changed hook commands. Our latest compatibility smoke passed with Claude Code **2.1.272** and Codex CLI **0.154.0**. Aether validates the hook fields it uses and reports incompatible payloads instead of guessing their meaning. Cloud tasks use the project's normal agent, model, and workspace-size defaults. They consume [workspace runtime credits](/concepts/billing-and-credits), including when the task is read-only. ## Set up your checkout From the checkout where you use your local coding agent, run: ```bash theme={"dark"} aether setup ``` Confirm the project matches this repository. If a CLI default is already set, setup keeps it; use `aether setup --project ` to select a different project for this run. Answer **yes** to **Enable Aether cloud delegation in this checkout?** Setup installs the connection, lifecycle hooks, and `aether-delegate` skill for each detected supported client. Setup opens each client's native browser sign-in. Use the same Aether account as the CLI, review the requesting client and return address, and choose **Allow access**. Complete the browser flow on the computer running setup so it can return to the local client. Setup waits for authorization and prints `Cloud delegation connected for claude-code` or `Cloud delegation connected for codex-cli`. When both clients are installed, it connects both. You do not need a separate `mcp login` command. Launch a new session in this checkout, or restart your existing one after setup: ```bash theme={"dark"} claude ``` ```bash theme={"dark"} codex ``` Review and approve the client's project MCP and hook trust prompts. The connection appears as `aether_delegation`; the installed skill teaches your agent how to use it. ## Delegate your first task Paste this into your local coding conversation: ```text theme={"dark"} Delegate a read-only repository orientation to Aether using the project's default branch. Ask the cloud agent to identify the main entry points and test commands, and report its findings with file paths. Do not change files. Give me the task link. While it runs, help me plan my next local change. ``` Your local agent creates the cloud task and gets a task link. A task being accepted means it has been queued; the result is ready when the cloud agent finishes its turn. As you continue the local conversation, hooks check for updates and tell your agent when there is a result or a request for input. The agent can read the full response, summarize it, and acknowledge the update after handling it. If the local conversation has paused, send: ```text theme={"dark"} Check the Aether task. Read its full result and summarize the findings. ``` A successful first run leaves you with a cloud task link and a result you can use in the original local conversation. ## Useful ways to split the work | Keep doing locally | Delegate to Aether | Ask for | | --------------------------- | ----------------------------------------------- | -------------------------------------------------- | | Plan or implement a change | Review the relevant code on a pushed branch | File references, edge cases, and missing tests | | Work on the next feature | Reproduce a test failure in a cloud environment | The command, failure output, and likely cause | | Build one part of a feature | Implement a separate, clearly scoped part | Changes, verification results, and a PR for review | Include the branch, scope, and completion criteria in the delegation request. A task starts from **pushed repository state**; your local uncommitted changes and conversation transcript are not uploaded. Push a branch first if the cloud agent needs your latest code, and name that branch in the request. Configure required dependencies and secrets in the [project environment](/guides/environment-json). Cloud changes stay in the cloud task's branch. Ask for a PR, review it, and decide how to bring the changes into your work. Receiving a result does not merge or apply it to your local checkout. ## How results reach your session * **While you work:** hooks check at session start, prompts, and supported tool events. Your agent gets a notice when unread updates are available. * **When your agent finishes a turn:** the Stop hook can ask it to continue once for an actionable unread update. It does not keep the agent running indefinitely. * **When the task needs input:** your local agent can read the question or plan and send an answer or decision through the same connection. * **When your local agent is idle or closed:** cloud work can continue, but hooks cannot wake that agent. Resume the session or ask it to check the task. Reading a result does not clear its unread state. The installed skill tells the agent to acknowledge the exact update only after reading or handling it. ## Delegation, Teleport, or a CLI task? | What you want to do | Use | | --------------------------------------------------------------------------- | ------------------------------------- | | Keep a local session going and give a separate task to a cloud agent | **Cloud delegation**, from this guide | | Move the current conversation and working state to Aether to continue there | [Teleport](/guides/teleport) | | Start and follow a cloud task directly from a terminal | [`aether run`](/cli/run) | Delegation keeps the local conversation in charge of the handoff and result. Teleport carries the current session itself into the cloud. ## Connection and permissions The connection uses hosted MCP at `https://api.runaether.dev/mcp`. Setup supplies the project configuration; adding only this URL to a generic MCP client does not install the hooks or establish a local session. Claude Code and Codex store and refresh their own OAuth credentials. Those credentials permit cloud delegation, including billable task creation, but exclude account settings, billing details, and direct database access. Hooks use your saved Aether CLI login separately. Keep both signed in to the same Aether account. Hooks send session identifiers and event metadata. They do not upload prompt text, transcripts, local files, or tool output. Information your local agent explicitly puts in a delegated task or follow-up is sent to Aether. ## Troubleshooting | What you see | What to check | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Setup never offers cloud delegation | Run it inside a Git checkout, select a project, and make sure `claude` or `codex` is on `PATH`. | | Setup reports that your client is too old or its version cannot be parsed | Check `claude --version` or `codex --version`, then install a stable release at or above the minimum above. If an older Aether CLI says `unverified host version`, update Aether too. | | `delegation setup requires the host's default configuration directory` | Use the client's default profile without `CODEX_HOME` or `CLAUDE_CONFIG_DIR` overrides. | | Browser sign-in was cancelled or failed | Run `aether setup` again in this checkout and complete the connection. Setup reports the failure rather than marking it connected. | | The connection needs authentication after restarting | Rerun setup with working native credential storage. On macOS, use your normal home and an accessible login keychain; a temporary `HOME` without a default keychain can make the native login fail to persist. | | Tools are missing, or the agent has no Aether session handle | Confirm setup enabled delegation, launch the agent in the installed checkout, and approve its project MCP and hooks. Restart the session after installing. | | Hooks report an authentication or project mismatch | Check `aether auth status`. Use the same account for CLI and MCP, and confirm setup targeted the right project. | | The cloud task finished but nothing appeared locally | Send a new prompt asking your agent to check the task. Hooks do not wake an idle or closed session. | For installation files, organization selection, and removal, see the [`aether delegation` reference](/cli/delegation).