Skip to main content

​
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

aether workspace <subcommand> [flags]

​
Subcommands

SubcommandDescription
listList 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

StateDescription
stoppedWorkspace is not running
startingWorkspace is booting up
runningWorkspace is active and accepting connections
stoppingWorkspace is shutting down
errorWorkspace encountered an error during state transition
stop_failedWorkspace failed to stop cleanly
suspendingWorkspace is being suspended
suspendedWorkspace is suspended
recoveringWorkspace is recovering

​
aether workspace list

List all workspaces in the current project. 
aether workspace list [flags]
FlagDescription
--statusFilter by workspace state
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

aether workspace list --status running

​
aether workspace get

Get details for a specific workspace. 
aether workspace get <id>

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. 
aether workspace stop <id> [flags]
FlagDescription
--no-waitReturn immediately without waiting for the workspace to reach stopped state

​
aether workspace create

Create a workspace for the selected project. 
aether workspace create [flags]
FlagDescription
--keep-activeKeep-active setting (true or false)
--hardware-presetHardware preset
--cpu-kindCPU kind
--cpusCPU count
--memory-mbMemory in MB
--volume-size-gbVolume size in GB
--gpu-kindGPU kind, or none to clear

​
aether workspace update

Update workspace hardware or keep-active settings. 
aether workspace update <id> [flags]
The hardware and keep-active flags are the same as workspace create. 
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. 
aether workspace delete <id> [flags]
FlagDescription
--forceSkip confirmation prompt
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. 
aether workspace ssh [workspace]

# Interactive picker
aether workspace ssh

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

# 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. 
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. 
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. 
aether workspace port kill ws_a1b2c3d4 3000

​
aether workspace preview-url

Print the preview URL for a workspace port. 
aether workspace preview-url ws_a1b2c3d4 3000