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 your workspaces. With a default project selected, only that project’s workspaces are listed; otherwise all your workspaces are listed and a PROJECT column is added.
Without a default project the columns are ID, STATUS, PROJECT, HARDWARE, UPDATED.

​
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 print its WebSocket transport path. This is how you start a stopped (idle, stopped, or suspended) workspace.
Pass --json to return the full connection response, including the preview token.

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

​
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 a preview domain is configured.

​
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.
Preview URLs follow the format below, where the prefix is the workspace’s first 8 characters and the token is a 32-character lowercase alphanumeric preview token:
A preview domain must be configured via aether config set preview_domain <domain> or the AETHER_PREVIEW_DOMAIN environment variable. Without it, ports prints only port numbers and preview-url fails.