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

> Manage cloud development environments

# Workspaces

A workspace is a cloud VM attached to a project. It provides a full Linux environment (Ubuntu 22.04) with persistent storage, terminal access, and the AI agent runtime.

## Workspace States

Workspaces follow a defined lifecycle:

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

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

<Note>
  Workspaces automatically stop after an idle timeout (default: 10 minutes with no active connections or tasks). This prevents unnecessary resource usage.
</Note>

## Connecting to a Workspace

<Tabs>
  <Tab title="Web">
    Open a project and connect to its workspace. The UI shows a real-time status indicator as the workspace boots or resumes.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    aether workspace connect <workspace-id>
    ```
  </Tab>
</Tabs>

## Stopping a Workspace

```bash theme={null}
aether workspace stop <workspace-id>
```

This gracefully shuts down the VM while preserving the persistent volume. All files and installed packages remain available on next start.

## Listing Workspaces

```bash theme={null}
# List all workspaces
aether workspace list

# Filter by status
aether workspace list --status running
```

Output:

```
ID          PROJECT     STATUS    HARDWARE       CREATED
ws-abc123   my-app      running   2cpu/2048mb    2025-03-15
ws-def456   api-svc     stopped   1cpu/1024mb    2025-03-10
```

## Getting Workspace Details

```bash theme={null}
aether workspace get <workspace-id>
```

Returns the full workspace object: state, hardware config, project association, IP addresses, and creation time.

## Deleting a Workspace

```bash theme={null}
aether workspace delete <workspace-id>
```

<Warning>
  Deleting a workspace destroys the VM and its persistent volume. All files, databases, and installed packages are permanently removed.
</Warning>

## Hardware Presets

Each workspace runs on configurable hardware. You can set these when creating a workspace or update them later.

| Parameter        | Description              | Range                     |
| ---------------- | ------------------------ | ------------------------- |
| `cpu_kind`       | CPU type                 | `shared` or `performance` |
| `cpus`           | Number of CPU cores      | 1 - 8                     |
| `memory_mb`      | Memory in megabytes      | 256 - 16384               |
| `volume_size_gb` | Persistent storage in GB | Configurable per plan     |
| `gpu_kind`       | Optional GPU type        | Depends on availability   |

```bash theme={null}
aether workspace create --project a1b2c3d4 \
  --cpus 2 \
  --memory 4096 \
  --volume-size 20
```

## SSH Access

You can SSH directly into a running workspace for manual debugging or exploration:

```bash theme={null}
aether workspace ssh
```

This connects to the workspace associated with your currently selected project. The SSH session provides a full terminal with the same environment the agent uses.

<Info>
  SSH access requires the workspace to be in `running` state. If the workspace is stopped, connect to it first with `aether workspace connect`.
</Info>