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

# aether workspace

> Manage cloud development workspaces

# aether workspace

Manage cloud workspaces. Each workspace is a full Linux VM with persistent storage where the agent runs your code.

**Aliases:** `workspaces`, `ws`

## Usage

```bash theme={null}
aether workspace <subcommand> [flags]
```

## Subcommands

| Subcommand                | Description                                            |
| ------------------------- | ------------------------------------------------------ |
| `list`                    | List workspaces in the current project                 |
| `get <id>`                | Get workspace details                                  |
| `start <id>`              | Start a stopped workspace                              |
| `stop <id>`               | Stop a running workspace                               |
| `delete <id>`             | Delete a workspace                                     |
| `connect <id>`            | Start or resume a workspace and print connection state |
| `ports <id>`              | List active preview ports                              |
| `port kill <id> <port>`   | Kill an active preview port                            |
| `preview-url <id> <port>` | Print a preview URL for a workspace port               |
| `ssh [workspace]`         | Open an interactive SSH session                        |

## Workspace States

| State         | Description                                            |
| ------------- | ------------------------------------------------------ |
| `stopped`     | Workspace is not running                               |
| `starting`    | Workspace is booting up                                |
| `running`     | Workspace is active and accepting connections          |
| `stopping`    | Workspace is shutting down                             |
| `error`       | Workspace encountered an error during state transition |
| `stop_failed` | Workspace failed to stop cleanly                       |
| `suspending`  | Workspace is being suspended                           |
| `suspended`   | Workspace is suspended                                 |
| `recovering`  | Workspace is recovering                                |

## aether workspace list

List all workspaces in the current project.

```bash theme={null}
aether workspace list [flags]
```

| Flag       | Description               |
| ---------- | ------------------------- |
| `--status` | Filter by workspace state |

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

```
ID              STATUS      CREATED          MACHINE
ws_a1b2c3d4     running     2025-01-15       shared-cpu-1x
ws_e5f6g7h8     stopped     2025-01-10       shared-cpu-2x
```

```bash theme={null}
aether workspace list --status running
```

## aether workspace get

Get details for a specific workspace.

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

```bash theme={null}
aether workspace get ws_a1b2c3d4
```

```
ID:        ws_a1b2c3d4
Status:    running
Machine:   shared-cpu-1x
Region:    us-east
Created:   2025-01-15T10:30:00Z
Preview:   https://ws-a1b2c3d4.runaether.dev
```

## aether workspace stop

Stop a running workspace. The workspace retains its persistent storage.

```bash theme={null}
aether workspace stop <id> [flags]
```

| Flag        | Description                                                                   |
| ----------- | ----------------------------------------------------------------------------- |
| `--no-wait` | Return immediately without waiting for the workspace to reach `stopped` state |

## aether workspace create

Create a workspace for the selected project.

```bash theme={null}
aether workspace create [flags]
```

| Flag                | Description                             |
| ------------------- | --------------------------------------- |
| `--keep-active`     | Keep-active setting (`true` or `false`) |
| `--hardware-preset` | Hardware preset                         |
| `--cpu-kind`        | CPU kind                                |
| `--cpus`            | CPU count                               |
| `--memory-mb`       | Memory in MB                            |
| `--volume-size-gb`  | Volume size in GB                       |
| `--gpu-kind`        | GPU kind, or `none` to clear            |

## aether workspace update

Update workspace hardware or keep-active settings.

```bash theme={null}
aether workspace update <id> [flags]
```

The hardware and keep-active flags are the same as `workspace create`.

```bash theme={null}
aether workspace stop ws_a1b2c3d4
```

```
Stopping workspace ws_a1b2c3d4...
Workspace stopped.
```

## aether workspace delete

Delete a workspace and its persistent storage. This action is irreversible.

```bash theme={null}
aether workspace delete <id> [flags]
```

| Flag      | Description              |
| --------- | ------------------------ |
| `--force` | Skip confirmation prompt |

```bash theme={null}
aether workspace delete ws_a1b2c3d4
```

```
Are you sure you want to delete workspace ws_a1b2c3d4? This will permanently remove all files. [y/N]
```

## aether workspace ssh

Open an interactive terminal session in a running workspace. If no workspace ID is given, an interactive picker is displayed.

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

```bash theme={null}
# Interactive picker
aether workspace ssh
```

```
? Select a workspace:
> ws_a1b2c3d4 (running)
  ws_e5f6g7h8 (running)
```

```bash theme={null}
# Connect directly
aether workspace ssh ws_a1b2c3d4
```

```
Connected to ws_a1b2c3d4
user@workspace:~$
```

Press `Ctrl+D` or type `exit` to disconnect.

## aether workspace connect

Start or resume a workspace and print the WebSocket transport path.

```bash theme={null}
aether workspace connect ws_a1b2c3d4
```

Use `--json` to return the full connection response, including operation state.

## aether workspace ports

List active preview ports for a workspace.

```bash theme={null}
aether workspace ports ws_a1b2c3d4
```

The command connects to the workspace WebSocket, waits for a port snapshot, and prints preview URLs using `preview_domain` from CLI config.

## aether workspace port kill

Kill an active preview port.

```bash theme={null}
aether workspace port kill ws_a1b2c3d4 3000
```

## aether workspace preview-url

Print the preview URL for a workspace port.

```bash theme={null}
aether workspace preview-url ws_a1b2c3d4 3000
```