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

# Workspaces

> The isolated cloud VM where the agent runs your code, its lifecycle states, hardware tiers, and toolchain.

A workspace is the cloud VM where Aether's agent runs your code. Every task is bound to exactly one workspace, and each workspace is a full Ubuntu Linux machine with persistent storage, a real terminal, and a real browser. Your source code, dependencies, and dev servers live here and persist across tasks — the workspace is not a stateless sandbox that resets between prompts.

## Display States

A workspace reports its current condition as a **display state**. These are the values you see in the web app, the CLI, and the API:

| State        | Meaning                                                                 |
| ------------ | ----------------------------------------------------------------------- |
| `idle`       | Provisioned but not currently running.                                  |
| `starting`   | Booting the VM.                                                         |
| `preparing`  | Booted; running setup and restoring services before the agent can work. |
| `ready`      | Running and able to serve work and preview traffic.                     |
| `stopping`   | Shutting the VM down.                                                   |
| `stopped`    | Powered off; can be restarted.                                          |
| `suspending` | Pausing the VM (snapshotting memory/disk).                              |
| `suspended`  | Paused; resumes faster than a cold start.                               |
| `destroying` | Tearing down the VM and its resources.                                  |
| `deleted`    | Removed.                                                                |
| `error`      | A lifecycle operation failed.                                           |

<Note>
  The CLI `aether workspace list --status` filter accepts any of these display states, and you can pass several comma-separated (for example `--status ready,error`).
</Note>

## Runtime Classes

Hardware is not free-form. You choose from four fixed **runtime classes**, each with a fixed CPU/memory/storage shape and a per-hour [credit](/concepts/billing-and-credits) rate.

| Class              | vCPU | CPU kind    | Memory | Volume | Credits/hour |
| ------------------ | ---- | ----------- | ------ | ------ | ------------ |
| `small`            | 8    | shared      | 2 GB   | 5 GB   | 5            |
| `medium` (default) | 8    | shared      | 4 GB   | 10 GB  | 10           |
| `large`            | 2    | performance | 8 GB   | 20 GB  | 20           |
| `xl`               | 4    | performance | 16 GB  | 20 GB  | 40           |

`performance` is an alias for `large`. The default runtime class is `medium`. Which classes you may use depends on your subscription tier — the Free tier is limited to `small` and `medium`, while paid tiers allow all four. See [pricing and tiers](/concepts/pricing-and-tiers).

Runtime class drives billing: a workspace consumes its class's credits/hour for the time it is active. At 10 credits/hour, one credit buys roughly 6 minutes of `medium` VM time.

## Idle Auto-Stop

Workspaces stop themselves when nothing is using them, so you do not pay for idle VM time. While a task is running, a background activity is in flight, or you have an interactive connection open (terminal, file browser, preview), the workspace is held active. When those release, the workspace signals idle and is suspended. An interactive disconnect (a closed browser tab, a brief network blip) keeps a short reconnect grace before the workspace is considered idle.

To keep a specific workspace from auto-stopping, opt it out:

```bash theme={null}
aether workspace update <workspace-id> --keep-active true
```

Set it back to `false` to re-enable auto-stop.

## Preinstalled Toolchain

The workspace base image is Ubuntu 22.04. It ships the agent CLIs ([Codex, Claude Code, Cursor](/concepts/agents-and-models)) plus a broad toolchain so the agent can build and test most projects without installing a runtime first:

* **Languages and runtimes:** Go 1.26.4, Rust (stable), Node.js 20 with pnpm, Bun 1.3.13, Python 3.11
* **Containers:** Docker CE and the Docker Compose plugin
* **Git tooling:** `git` and the GitHub CLI (`gh`)
* **Search and shell utilities:** `ripgrep`, `fd`, `bat`, `jq`, `tree`, `tmux`
* **Browser automation:** Playwright with Chromium
* **GUI / computer-use:** Xvfb, `xdotool`, `ffmpeg` (screen recording)

You run as the `coder` user with passwordless `sudo`. SSH listens on port 2222 and the agent service on port 3001.

To install anything else your project needs at startup, use [`.aether/environment.json`](/guides/environment-json).

## Related

<CardGroup cols={2}>
  <Card title="Warm Slots" icon="bolt" href="/concepts/warm-slots">
    Pre-provisioned snapshots that start workspaces faster.
  </Card>

  <Card title="Billing & Credits" icon="coins" href="/concepts/billing-and-credits">
    How VM runtime is metered in credits.
  </Card>

  <Card title="Agents & Models" icon="robot" href="/concepts/agents-and-models">
    The providers and models that run inside a workspace.
  </Card>

  <Card title="environment.json" icon="gear" href="/guides/environment-json">
    Configure setup commands and background services.
  </Card>
</CardGroup>