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

# Projects

> Create projects, link a repository, and set per-project task defaults

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](/guides/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).

```
Full ID:   a1b2c3d4-e5f6-7890-abcd-ef1234567890
Short ID:  a1b2c3d4
```

## Creating a Project

<Tabs>
  <Tab title="Web">
    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.
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    aether project create --name "my-app" --description "A Next.js SaaS starter"
    ```

    The CLI prints the new project's name and short prefix.
  </Tab>
</Tabs>

Projects do not carry a VM-size default. Choose the size when you [create each task](/guides/tasks#creating-tasks), and assign any prewarmed capacity separately under [Warm Slots](/concepts/warm-slots).

<Note>
  A task can only run against a project that is linked to a GitHub repository. See [GitHub integration](/guides/github-integration) to connect the GitHub App and import a repo.
</Note>

## Task Defaults

Task defaults are the per-project settings a new [task](/guides/tasks) inherits when you don't override them in the composer. They cover:

| Default | Description |
| - | - |
| `agent_type` | Coding agent the task uses — see [the AI agent](/guides/agents-and-models) |
| `model` | Model the agent runs |
| `interaction_mode` | `default` (Chat) or `plan` (plan before editing) |
| `reasoning_effort` | Thinking level (Codex and Claude Code only) |
| `auto_fix_ci` | Resume the task when CI fails on the tracked PR |
| `auto_fix_pr_comments` | Resume the task when new PR review feedback arrives |
| `auto_rebase` | Resume the task to resolve conflicts when the tracked branch needs a rebase |

<Tabs>
  <Tab title="Web">
    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.
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    aether project update a1b2c3d4 \
      --agent-type codex \
      --model gpt-5.5 \
      --interaction-mode plan \
      --auto-fix-ci true \
      --auto-fix-pr-comments false \
      --auto-rebase false
    ```

    Pass `--reasoning-effort none` to clear the thinking level. Only the flags you provide are changed.
  </Tab>
</Tabs>

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

| Setting | Values |
| - | - |
| Auto-review trigger | `disabled`, `on_pr_created`, `on_every_push` |
| Respond to review comments | on / off |
| Review on new comments | on / off |
| Review prompt | custom instructions sent to the reviewer |

See [Automation](/concepts/automation) for how PR reviews surface and how to trigger one manually.

## Listing Projects

<Tabs>
  <Tab title="Web">
    The dashboard shows your projects with their status and last activity.
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    aether project list
    ```
  </Tab>
</Tabs>

## Getting Project Details

```bash theme={"dark"}
aether project get a1b2c3d4
```

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:

```bash theme={"dark"}
aether project select
```

This opens an interactive selector. Once set, commands like `aether run` and `aether env list` target the selected project automatically.

## Archiving a Project

```bash theme={"dark"}
aether project archive a1b2c3d4 --force
```

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

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

```bash theme={"dark"}
# Equivalent when the prefix is unique
aether project get a1b2c3d4-e5f6-7890-abcd-ef1234567890
aether project get a1b2c3d4
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.