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:

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

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

Starting a Workspace

Web

Open a project and click Start Workspace. The UI shows a real-time status indicator as the workspace boots.

CLI

aether workspace start <workspace-id>

By default, the CLI polls until the workspace reaches running state. To return immediately:

aether workspace start <workspace-id> --no-wait

Stopping a Workspace

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

# 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

aether workspace get <workspace-id>

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

Deleting a Workspace

aether workspace delete <workspace-id>

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

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

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:

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.

SSH access requires the workspace to be in running state. If the workspace is stopped, start it first with aether workspace start.