Core Concepts

Understand the building blocks of Aether

Core Concepts

Aether is built around four key concepts: Projects, Workspaces, Tasks, and the Agent.

Project

A project is the top-level container for your application. It holds:

• Source code and configuration
• Environment variables
• GitHub repository link (optional)
• One or more workspaces

Every project has a unique ID. You can reference projects by their full UUID or a short prefix (first 8 characters).

aether project list
aether project get abc12345

Workspace

A workspace is a cloud VM instance attached to a project. Each workspace provides:

• Full Linux environment (Ubuntu 22.04)
• Persistent storage volume
• Terminal access via WebSocket or SSH
• File system operations
• Port discovery and preview URLs
• AI agent runtime

Workspace States

State	Description
stopped	VM is not running, volume is preserved
starting	VM is being created or resumed
running	VM is active and accepting connections
stopping	VM is shutting down gracefully
error	VM failed to start or encountered a fatal error
stop_failed	VM failed to stop cleanly

Workspaces auto-stop after a configurable idle timeout (default: 10 minutes).

Task

A task represents a unit of work for the AI agent. When you send a prompt, a task is created and assigned to a running workspace.

Task Lifecycle

1. Created — Task is queued with your prompt
2. Running — Agent is actively working (streaming output)
3. Waiting — Agent asked a question and is waiting for your response
4. Completed — Agent finished successfully
5. Failed — Agent encountered an error
6. Aborted — You cancelled the task

Tasks produce a stream of events: text output, tool invocations, thinking steps, and results.

# Create a task and watch output
aether run "fix the login bug"

# Or manage tasks individually
aether task create --prompt "add dark mode"
aether task watch <id>
aether task respond <id> --message "use Tailwind dark: variant"
aether task abort <id>

Agent

The AI agent is the core of Aether. It runs inside each workspace and has access to:

Code Tools

• Read, write, and edit files
• Execute bash commands
• Search with glob and grep
• Web search and fetch

Browser Tools (Playwright)

• Navigate to URLs
• Take screenshots and accessibility snapshots
• Click elements, type text, fill forms
• Evaluate JavaScript
• Wait for conditions

Hardware Configuration

Each workspace runs on configurable hardware. You can customize:

Parameter	Description
cpu_kind	CPU type (shared or performance)
cpus	Number of CPU cores (1-8)
memory_mb	Memory in MB (256-16384)
volume_size_gb	Persistent storage in GB
gpu_kind	Optional GPU type

Hardware can be set per-workspace or as a default in user settings.