Skip to main content
Manage cloud workspaces. Each workspace is a full Linux VM with persistent storage where the agent runs your code. See workspaces for the concept. Aliases: workspaces, ws

Usage

Subcommands

There is no create or start subcommand. Workspaces are created automatically at the size selected for a task, and connect starts or resumes a stopped workspace.
Most <id> arguments accept the first 8 characters of the workspace UUID instead of the full ID. An ambiguous prefix fails loudly and asks for a longer one.

Display States

The CLI shows a workspace’s current display state in the STATUS column and in get.

aether workspace list

List one page of your workspaces, most recently updated first. With a default project selected, only that project’s workspaces are listed; otherwise the workspaces of the organization the command acts in (see --org) are listed and a PROJECT column is added. When more workspaces follow, the output ends with a Next cursor: line; pass it to --cursor to read the next page.
Without a default project the columns are ID, STATUS, PROJECT, HARDWARE, UPDATED. With --json, the output is the page itself: {"items": [...], "next_cursor": "..."}, where next_cursor is null on the last page.

aether workspace get

Show details for one workspace.
Prints the ID, display state, project, hardware, keep-active flag, git ref, and timestamps. If the workspace is in error, the error message is shown.

aether workspace connect

Start or resume a workspace and wait until it is running. This is how you start a stopped (idle, stopped, or suspended) workspace. While the workspace starts, each step it waits on is printed to stderr.
Pass --json to return the workspace’s ID, its task’s ID, the live protocol, and the preview URL template.

aether workspace update

Update a workspace’s VM size or keep-active setting. Only the flags you pass are changed; at least one is required.

aether workspace stop

Stop a running workspace. The workspace keeps its persistent storage and can be resumed with connect. By default the command waits until the workspace reaches a stopped state.

aether workspace delete

Delete a workspace and its persistent storage.
Deleting a workspace destroys its volume and all files. This action is irreversible.

aether workspace ssh

Open an interactive raw-mode terminal session in a workspace over the WebSocket connection. Requires an interactive terminal (TTY) and handles window resizing. If no workspace is given, the command uses the project’s single running workspace.
Type exit or press Ctrl+D to disconnect. The command also exits zero when the server closes the connection normally (close code 1000). Any other close ends it non-zero with the close’s name (for example going_away); it does not reconnect, since a new connection would open a fresh shell.

aether workspace ports

List the active preview ports for a workspace. The command connects to the workspace, waits for a port snapshot, and prints a preview URL for each port when the workspace’s ports can be reached.

aether workspace port kill

Kill an active preview port (1–65535).

aether workspace preview-url

Print the preview URL for a workspace port.
Pass --authed to run the repository’s preview auth hook. A URL result is printed directly. A local_storage result prints an explanation to stderr and the complete JSON result to stdout so a script can apply it client-side.
The API answers each workspace’s preview URL template, and the CLI fills in the port. It accepts a template only under the configured preview domain (aether config set preview_domain <domain> or the AETHER_PREVIEW_DOMAIN environment variable), over https, or http when that domain is localhost. When the workspace’s ports cannot be reached, ports prints only port numbers and preview-url fails.