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

# Core Concepts

> Understand the building blocks of Aether

# Core Concepts

Aether is built around four key concepts: **Projects**, **Workspaces**, **Tasks**, and the **Agent**.

## Project

A project is the top-level container for your application. It holds:

* Source code and configuration
* Environment variables
* GitHub repository link (optional)
* One or more workspaces

Every project has a unique ID. You can reference projects by their full UUID or a short prefix (first 8 characters).

```bash theme={null}
aether project list
aether project get abc12345
```

## Workspace

A workspace is a cloud VM instance attached to a project. Each workspace provides:

* Full Linux environment (Ubuntu 22.04)
* Persistent storage volume
* Terminal access via WebSocket or SSH
* File system operations
* Port discovery and preview URLs
* AI agent runtime

### Workspace States

```mermaid theme={null}
stateDiagram-v2
    stopped --> starting
    starting --> running
    starting --> error
    running --> stopping
    stopping --> stopped
    stopping --> stop_failed
```

| State         | Description                                     |
| ------------- | ----------------------------------------------- |
| `stopped`     | VM is not running, volume is preserved          |
| `starting`    | VM is being created or resumed                  |
| `running`     | VM is active and accepting connections          |
| `stopping`    | VM is shutting down gracefully                  |
| `error`       | VM failed to start or encountered a fatal error |
| `stop_failed` | VM failed to stop cleanly                       |

Workspaces auto-stop after a configurable idle timeout (default: 10 minutes).

## Task

A task represents a unit of work for the AI agent. When you send a prompt, a task is created and assigned to a running workspace.

### Task Lifecycle

1. **Created** — Task is queued with your prompt
2. **Running** — Agent is actively working (streaming output)
3. **Waiting** — Agent asked a question and is waiting for your response
4. **Completed** — Agent finished successfully
5. **Failed** — Agent encountered an error
6. **Aborted** — You cancelled the task

Tasks produce a stream of events: text output, tool invocations, thinking steps, and results.

```bash theme={null}
# Create a task and watch output
aether run "fix the login bug"

# Or manage tasks individually
aether task create --prompt "add dark mode"
aether task watch <id>
aether task respond <id> --message "use Tailwind dark: variant"
aether task abort <id>
```

## Agent

The AI agent is the core of Aether. It runs inside each workspace and has access to:

### Code Tools

* Read, write, and edit files
* Execute bash commands
* Search with glob and grep
* Web search and fetch

### Browser Tools (Playwright)

* Navigate to URLs
* Take screenshots and accessibility snapshots
* Click elements, type text, fill forms
* Evaluate JavaScript
* Wait for conditions

## Hardware Configuration

Each workspace runs on configurable hardware. You can customize:

| Parameter        | Description                          |
| ---------------- | ------------------------------------ |
| `cpu_kind`       | CPU type (`shared` or `performance`) |
| `cpus`           | Number of CPU cores (1-8)            |
| `memory_mb`      | Memory in MB (256-16384)             |
| `volume_size_gb` | Persistent storage in GB             |
| `gpu_kind`       | Optional GPU type                    |

Hardware can be set per-workspace or as a default in user settings.