Quickstart

Get from a fresh machine to a working AI agent in a few minutes. If Claude Code or Codex is already installed locally, aether setup can connect it to Aether so you can delegate cloud tasks from the same conversation. Setup checks existing state and skips completed account and provider connections. Rerun it to enable delegation in another checkout or retry a failed connection.

Step 1: Install the CLI

On macOS or Linux, run:

curl -fsSL https://app.runaether.dev/install.sh | sh

See installation for Homebrew and Windows.

Step 2: Run Aether setup

aether setup

Run setup in the Git checkout you want to use. It is interactive only and walks through the following steps, opening your browser wherever the underlying flow requires it:

Runs the Aether login flow. This step is skipped if you are already authenticated.

Connect GitHub

Opens the GitHub App installation page and waits for the installation.

Set a default project

If you run setup inside a git repo whose GitHub remote is covered by the installation, it offers to create or select an Aether project from that repo and sets it as the CLI default. A repo-linked project claims the first available devbox prewarm slot at small immediately, so its seed can build while setup continues; if none is available, setup continues with a cold start.

Connect cloud agent providers

Detects Claude Code, Codex, and OpenCode on your machine and offers to connect their provider accounts for running cloud tasks. If none is detected, setup offers to install one with its official command after confirmation, verifies its version, and then connects it. Claude Code uses claude setup-token, Codex uses a device flow, and OpenCode imports its local auth file. Cursor is not part of setup.

Install the teleport skill

Offers to install the /aether-teleport skill to ~/.claude/skills/aether-teleport for Claude Code and ~/.agents/skills/aether-teleport for Codex.

Enable cloud delegation

Offers to connect supported local Claude Code and Codex clients to this checkout’s Aether project. Setup installs MCP configuration, hooks, and the delegation skill, then waits for each client’s native browser sign-in. Use the latest Aether CLI and a supported client version on macOS or Linux.

Upload secret files

Scans the current git repo for gitignored secret-file candidates that are not already uploaded, lists their paths and sizes, and uploads them to the default project only after you explicitly confirm.

Launch your first task

When onboarding is ready and the default project has no tasks, offers to launch the first task immediately. Repositories without .aether/environment.json get an environment-bootstrap task that proves every declared preview from inside the workspace before opening a pull request.

After setup, you can launch claude or codex and ask it to delegate a task, start a task with aether run "...", or teleport your current session.

Step 3: Confirm a default project

Every aether run needs a default project. If setup offered to create or select a project and set it as the CLI default, continue. Otherwise, move into a git repo whose GitHub remote is covered by your installation and rerun aether setup, or create and link a project manually before continuing.

Step 4: Run your first task

Local coding agent
CLI
Web

If you enabled cloud delegation, launch claude or codex from this checkout and approve its project MCP and hook trust prompts. Then ask:

Delegate a read-only repository orientation to Aether. Ask for the main
entry points and test commands with file paths, and give me the task link.

The task starts from pushed repository state. Your local uncommitted changes are not uploaded. See cloud delegation for branch selection and example workflows.

aether run "Add a dark mode toggle to the settings page" --size medium

The CLI watches the agent’s progress in your terminal. Pass --no-watch to create the task without watching. If you omit --size, the size is resolved server-side — the project’s default task size, else small — and the CLI prints size: project default (use --size to override).

Starting a task spins up an isolated workspace VM at the requested size and spends credits for the time that VM runs. Every plan can select small, medium, or large; the sizes differ in shape and credits/hour, not plan availability. Before the task starts, Aether checks that your billing state is in good standing and that you have enough credit for the selected size.

Step 5: Watch the agent work

The agent streams a live conversation: text, tool calls, and results. It may pause and park the task in awaiting_input to ask a question or propose a plan — respond to continue.

Local coding agent
Web
CLI

Continue working in the same conversation. Hooks check for cloud updates during local activity. If the local session has paused, ask it to check the Aether task; hooks cannot wake an idle or closed agent.

# Re-attach to a running task
aether task watch <id>

# Answer a question or send a follow-up
aether task respond <id> --message "use the Tailwind dark: variant"

See tasks and lifecycle for the states a task moves through.

Step 6: Review the result

For the read-only orientation task, ask your local agent to read the full result and summarize the entry points and test commands. You can use those findings in your next local change. For a task that changes code, review its changes and preview the running app. When the project is linked to a GitHub repo, the agent can open a pull request so you can review the diff in GitHub. Delegated changes are not automatically applied to your local checkout. If the agent started a dev server, a preview URL appears automatically:

https://3000-abc12345-1234567890abcdef1234567890abcdef.preview.runaether.dev

Open it to see your running application — HMR works through the proxy. See preview URLs.

Advanced: Set up each connection manually

If you prefer the web app or want to run each CLI command yourself, set up the same pieces individually.

Go to app.runaether.dev and sign up. New accounts land on the Free tier, which includes a monthly grant of starter credits — enough to run your first tasks. See billing and credits.

aether auth login

Signing up through the web app provisions your Free tier and credit grant.

Connect an agent provider

Tasks run on an agent provider, and you connect that provider with your own account. Codex is the default agent; connect it (or another provider: Claude Code or OpenCode) before running a task.

Open Settings → Connections and connect an agent provider. For Codex, authenticate with your ChatGPT/OpenAI account.

# Sign in to Codex with a device login
aether codex connect

See connect agent providers for every provider’s auth flow.

Create a project and link a repo

A project is the container for your code, environment variables, and task history.

Click New Project from the dashboard, give it a name, and link a GitHub repository if you have one. Connect GitHub first under Settings → Connections if you haven’t already.

aether project create --name "my-first-project"

Then link a GitHub repository to the project:

aether github import --repo owner/repo

Linking a repo is optional — you can start a project from scratch — but it lets the agent open pull requests against your code. See projects.

Connect local delegation

To delegate from a local Claude Code or Codex session, run aether setup in the linked checkout and enable cloud delegation. Setup reuses completed account and provider connections and handles the native browser sign-in. Follow the cloud delegation guide to launch your client and try a first task.

What’s Next?

Core Concepts

Projects, workspaces, tasks, agents, credits, and integrations.

Agents & Models

The three selectable providers and how to pick one.

Billing & Credits

How VM-runtime credits work and what running a task costs.

CLI Reference

Full command reference for the Aether CLI.

Getting Started

Using Aether

Step 1: Install the CLI

Step 2: Run Aether setup

Step 3: Confirm a default project

Step 4: Run your first task

Step 5: Watch the agent work

Step 6: Review the result

Advanced: Set up each connection manually

Connect an agent provider

Create a project and link a repo

Connect local delegation

What’s Next?

Core Concepts

Agents & Models

Billing & Credits

CLI Reference

​Step 1: Install the CLI

​Step 2: Run Aether setup

​Step 3: Confirm a default project

​Step 4: Run your first task

​Step 5: Watch the agent work

​Step 6: Review the result

​Advanced: Set up each connection manually

​Sign up and authenticate

​Connect an agent provider

​Create a project and link a repo

​Connect local delegation

​What’s Next?

Core Concepts

Agents & Models

Billing & Credits

CLI Reference

Step 1: Install the CLI

Step 2: Run Aether setup

Step 3: Confirm a default project

Step 4: Run your first task

Step 5: Watch the agent work

Step 6: Review the result

Advanced: Set up each connection manually

Sign up and authenticate

Connect an agent provider

Create a project and link a repo

Connect local delegation

What’s Next?