Quickstart

Get up and running with Helios in under 5 minutes

Prerequisites

Python 3.12+

Helios requires Python 3.12 or later

Docker

Docker must be installed and running

Installation

uv (Recommended)

# Clone the repository
git clone https://github.com/TryBayes/helios.git
cd helios

# Install dependencies
uv sync

# Or install as a global CLI tool
uv tool install .

pip

# Clone the repository
git clone https://github.com/TryBayes/helios.git
cd helios

# Install dependencies
pip install -e .

Configure API Keys

Set your LLM provider API key:

Gemini (Default)

export GEMINI_API_KEY=your-api-key
# or
export GOOGLE_API_KEY=your-api-key

Anthropic

export ANTHROPIC_API_KEY=your-api-key

OpenAI

export OPENAI_API_KEY=your-api-key

AWS Bedrock

export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1

Run Your First Task

1. Run a simple task

   helios tasks/create-hello-file
   

   This runs a headless task that creates a file in a Docker container.

2. Watch the result

   The output shows the agent’s progress and verification result:

   Task: create-hello-file
   Model: gemini/gemini-2.5-computer-use-preview-10-2025
   
   [Agent] Creating file...
   [Tool] bash: echo "Hello World" > /home/hello.txt
   [Verify] Running test.sh...
   [Result] PASS (reward: 1.0)
   

Run a GUI Task

GUI tasks require the desktop Docker image:

1. Build the desktop image

   docker build -t cua-desktop -f docker/Dockerfile.desktop .
   
2. Run with the web viewer

   helios tasks/explore-desktop --watch
   
3. Open the viewer

   Navigate to http://localhost:8080 to watch the agent work in real-time.

The --watch flag starts a web server that streams the agent’s activity, including VNC view of the desktop, tool calls, and LLM responses.

Choose a Model

Specify a different model with the -m flag:

# Use Claude Sonnet
helios tasks/create-hello-file -m claude-sonnet-4-20250514

# Use OpenAI
helios tasks/create-hello-file -m openai/computer-use-preview

# Use Bedrock
helios tasks/create-hello-file -m bedrock/global.anthropic.claude-opus-4-5-20251101-v1:0

Run Multiple Tasks

Run a batch of tasks in parallel:

# Run all tasks in a directory with 4 concurrent containers
helios batch tasks/ -n 4

# With a specific model
helios batch tasks/ -n 4 -m claude-sonnet-4-20250514

Interactive Mode

Pause and inspect the agent during execution:

helios tasks/create-hello-file -i

Press p to pause/resume execution.

Next Steps

Core Concepts

Understand how Helios works

Create Your Own Task

Build a custom task from scratch

Configuration

Configure models, timeouts, and resources

PDFBench

Run the PDF form-filling benchmark