Step 1: Install the CLI
On macOS or Linux, run:Step 2: Run Aether setup
1
Sign in
Runs the Aether login flow. This step is skipped if you are already authenticated.
2
Set a default project
If you run setup inside a git repo with a GitHub remote, it offers to create an Aether project from that repo and sets it as the CLI default, opening the GitHub App installation page first when GitHub is not connected yet, holds no installation, or needs its authorization renewed. When GitHub is connected but none of your installations is for the repo’s owner (a second account or organization), setup stops with
GitHub App is not installed for <owner>; run 'aether github connect' and grant repository access: run aether github connect for that account or organization, then run setup again. Anywhere else it offers to create a project without a repository; its tasks start from scratch, and aether task save gives a task’s work a repository later. A repo-linked project claims the first available devbox prewarm slot at medium immediately, so its seed can build while setup continues; if none is available, setup continues with a cold start.3
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.4
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.5
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.
6
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 (or runs the test suite when there is nothing to serve) before opening a pull request. The web onboarding launches the same task by default. A project without a repository asks what the first task should build.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
Everyaether run needs a default project. If setup offered to create or select a project and set it as the CLI default, continue. Otherwise, rerun aether setup and accept the project it offers (from the git repo you are in, or one without a repository), or create a project manually before continuing.
Step 4: Run your first task
- Local coding agent
- CLI
- Web
If you connected your client to Aether, launch The task starts from pushed repository state. Your local uncommitted changes are not uploaded. See cloud delegation for branch selection and example workflows.
claude or codex from this checkout and ask:medium, large, or xl; 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 inawaiting_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.
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: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
- Web
- CLI
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.
Choose what tasks run on
Codex is the default harness. Codex and Claude Code tasks can run on Aether inference without a stored connection; OpenCode needs a held connection. You can add named connections and choose a default per harness in Settings → Connections.- Web
- CLI
Open Settings → Connections. Use the Aether inference row, or choose Add to pick an option, name the connection and sign in. For Codex, the options are ChatGPT plan and OpenAI API key.
Create a project and link a repo
A project is the container for your code, environment variables, and task history.- Web
- CLI
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 task save, which gives the project that repository. See projects and GitHub integration.
Connect local delegation
To delegate from a local Claude Code or Codex session, add Aether as an MCP server in that client and sign in once. The project is found from the checkout’sorigin remote. Follow the cloud delegation guide to connect 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.