> ## 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, runtime classes, 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 the task's turns — the workspace is not a stateless sandbox that resets between prompts. It suspends when idle and resumes where it left off, so you can return later and continue the same task. New tasks start immediately only when a [warm pool](/concepts/warm-slots) has a ready machine for that project and requested size; otherwise they cold-start at the requested size.

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

A task's VM size selects one of three 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` | 1 | performance | 4 GB | 20 GB | 5 |
| `medium` | 2 | performance | 8 GB | 20 GB | 10 |
| `large` | 4 | performance | 16 GB | 20 GB | 20 |
| Projects may set a default task size (see project settings); an explicit per-task size always wins. Every subscription tier can use all three classes. 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={"dark"}
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, and OpenCode](/concepts/agents-and-models), plus the legacy `cursor-agent`) and 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.4.2, Python 3.12 (3.11 also installed)
* **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)
* **Profiling and capture:** `aether-perf` (the perf 5.15 userspace; `/usr/bin/perf` refuses to run on the guest kernel), `bpftrace`, `tcpdump`, `tshark`

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). If you run Docker services, review the [task VM Docker gotchas](/guides/environment-json#docker-on-task-vms).

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


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