Skip to main content
A project is the top-level container in Aether. It groups your source, environment variables, an optional GitHub repository link, and the history of agent work into a single unit.

​
What’s in a Project

Every project carries:
  • Source code stored on a persistent volume inside its workspace VM
  • Environment variables encrypted at rest and injected on workspace start — see Environment variables
  • GitHub link (optional) connecting the project to a repository and a default branch
  • Task defaults — the agent, model, mode, and automation settings new tasks inherit
  • PR-review policy — when Aether reviews pull requests for the repo
  • Tasks — the history of agent runs in the project
Each project has a unique UUID. Reference it by the full ID or by a short prefix (the first 8 characters).

​
Creating a Project

In Settings → Projects, click New project, pick a GitHub repo, and click Continue. This creates the project, links the repository, and sets the default branch in one step.
Projects do not carry a VM-size default. Choose the size when you create each task, and assign any prewarmed capacity separately under Warm Slots.
A task can only run against a project that is linked to a GitHub repository. See GitHub integration to connect the GitHub App and import a repo.

​
Task Defaults

Task defaults are the per-project settings a new task inherits when you don’t override them in the composer. They cover:
Set defaults in Settings → Projects → Task defaults, or save the current composer settings as the project default with the save button in the composer’s settings menu.

​
PR-Review Policy

Each project controls when Aether reviews pull requests on its linked repository. The policy is set in the web app under Settings → Projects. See Automation for how PR reviews surface and how to trigger one manually.

​
Listing Projects

The dashboard shows your projects with their status and last activity.

​
Getting Project Details

Returns the full project object including name, description, repository link, default branch, task defaults, and PR-review policy.

​
Selecting a Default Project

If you work on one project frequently, set it as the default so you can omit the project argument from other commands:
This opens an interactive selector. Once set, commands like aether run and aether env list target the selected project automatically.

​
Archiving a Project

Archiving stops live activity: active workspaces and volumes are destroyed, automations are disabled, and environment variables, secret files, and integration routes are removed. Task, run, and billing history is retained. Archiving is irreversible, but you can create a new project from the same repository. The --force flag skips the confirmation prompt.

​
Short ID Prefix Resolution

Aether resolves short prefixes by matching the first 8 characters of the UUID. If a prefix matches multiple projects, the CLI returns an error and asks for more characters.