Skip to main content

​
Core Concepts

Aether is built around five key concepts: Projects, Workspaces, Tasks, the Agent, and Hardware Configurations.

​
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

StateDescription
stoppedVM is not running, volume is preserved
startingVM is being created or resumed
runningVM is active and accepting connections
stoppingVM is shutting down gracefully
errorVM failed to start or encountered a fatal error
stop_failedVM 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

​
Infrastructure Tools

  • Provision databases and services
  • Query and migrate databases
  • Check service status and logs

​
Configuration

Aether supports multiple AI providers through BYOK (Bring Your Own Key):
ProviderModel
AnthropicClaude (via Agent SDK)
OpenAICodex
OpenRouterAny supported model
CodebuffCustom routing

​
Hardware Configuration

Each workspace runs on configurable hardware. You can customize:
ParameterDescription
cpu_kindCPU type (shared or performance)
cpusNumber of CPU cores (1-8)
memory_mbMemory in MB (256-16384)
volume_size_gbPersistent storage in GB
gpu_kindOptional GPU type
Hardware can be set per-workspace or as a default in user settings.