Skip to main content
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 is the fastest path to connect it to Aether. aether setup is one idempotent, interactive command that checks current state before every step and skips anything already done, so re-running it also works as a status and doctor check.

​
Step 1: Install the CLI

On macOS or Linux, run:
See installation for Homebrew and Windows.

​
Step 2: Run Aether setup

aether setup is interactive only. It walks through the following steps, opening your browser wherever the underlying flow requires it:
1

Sign in

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

Connect GitHub

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

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.
4

Connect local coding agents

Detects Claude Code, Codex, and OpenCode on your machine and offers to connect each one that is not already connected. 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.
5

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.
6

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.
7

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.
aether setup ends with: ready to aether run "..." or type /aether-teleport inside Claude Code.

​
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

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.
Follow the task in the conversation view. When the agent asks a question or proposes a plan, answer inline to resume it.
See tasks and lifecycle for the states a task moves through.

​
Step 6: Review and open a PR

Once the agent finishes a turn, 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. If the agent started a dev server, a preview URL appears automatically:
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.

​
Sign up and authenticate

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.

​
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.
See connect agent providers for every provider’s auth flow. 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.
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.

​
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.