Skip to content

QUICKSTART.md

Latest commit

 

History

History
284 lines (196 loc) · 9.48 KB

QUICKSTART.md

File metadata and controls

284 lines (196 loc) · 9.48 KB

Quick Start Guide

Fast Path (macOS / Linux)

Prerequisites: Docker Desktop running, Python 3.10+, an LLM API key.

git clone https://github.com/openlegion-ai/openlegion.git && cd openlegion
./install.sh         # checks dependencies, creates venv, installs everything
openlegion start     # inline setup on first run, then launch agents

That's it. On first run, openlegion start detects missing credentials and walks you through a quick setup (API key, model selection) right in the terminal — or you can skip and configure via the dashboard. The installer makes openlegion available globally — no need to activate a virtual environment.

Note: If openlegion: command not found after install, your ~/.local/bin may not be on PATH. The installer will print the exact command to fix this.

You can also use make:

make install         # same as ./install.sh
make start           # openlegion start (includes inline setup on first run)
make test            # run the test suite

Fast Path (Windows)

Prerequisites: Docker Desktop running, Python 3.10+, an LLM API key.

git clone https://github.com/openlegion-ai/openlegion.git
cd openlegion
powershell -ExecutionPolicy Bypass -File install.ps1
openlegion start     # inline setup on first run, then launch agents

PowerShell blocks the script? Run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser After install, restart your terminal if openlegion isn't recognized.

Prerequisites

You need three things installed before running OpenLegion:

1. Python 3.10+

macOS 
brew install python@3
python3 --version   # verify: 3.10 or higher

Or download from python.org/downloads.

Linux 
# Ubuntu / Debian
sudo apt update && sudo apt install python3 python3-pip python3-venv git

# Fedora / RHEL
sudo dnf install python3 python3-pip git
python3 --version   # verify: 3.10 or higher

Distro ships 3.9 or older? Use pyenv to get 3.10+.

Windows
  1. Download Python 3.10+ from python.org/downloads
  2. Run installer — check "Add python.exe to PATH"
  3. Verify in PowerShell: python --version

On Windows, use python and pip (not python3 / pip3).

2. Docker

Docker must be installed and running before setup.

macOS
  1. Download Docker Desktop for Mac
  2. Drag to Applications and launch
  3. Skip the sign-in — no account needed
  4. Wait for the whale icon in the menu bar to settle
docker info   # verify: should print server info
Linux 
# Ubuntu / Debian
sudo apt update && sudo apt install docker.io
sudo systemctl start docker && sudo systemctl enable docker
sudo usermod -aG docker $USER   # then log out and back in
docker info   # verify
Windows
  1. Download Docker Desktop for Windows
  2. Install — enable WSL 2 backend when prompted
  3. Restart if prompted
  4. Launch Docker Desktop — skip the sign-in
  5. Wait for "Docker Desktop is running"
docker info   # verify in PowerShell

3. LLM API Key

You need one key. Pick a provider:

Provider Best for Get a key
Anthropic Agentic tasks, browser automation, tool use console.anthropic.com
Moonshot / Kimi Agentic tasks, long context, tool use platform.moonshot.cn
DeepSeek Cost-effective reasoning platform.deepseek.com
OpenAI General purpose platform.openai.com/api-keys
Groq Fast inference, free tier console.groq.com

100+ providers supported via LiteLLM. Anthropic Claude or Moonshot Kimi recommended for agentic workloads.

Install (Manual)

If you prefer not to use the install scripts:

macOS / Linux 
git clone https://github.com/openlegion-ai/openlegion.git
cd openlegion
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

# Make openlegion available globally (no venv activation needed):
mkdir -p ~/.local/bin
ln -sf "$(pwd)/.venv/bin/openlegion" ~/.local/bin/openlegion

If ~/.local/bin isn't on your PATH, add it:

# bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
# zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
Windows (PowerShell) 
git clone https://github.com/openlegion-ai/openlegion.git
cd openlegion
python -m venv .venv
.venv\Scripts\pip install -e ".[dev]"

PowerShell blocks the script? Run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

After install, openlegion is available only inside the venv. Either activate it (".venv\Scripts\Activate.ps1") before use, or run openlegion as .venv\Scripts\openlegion.exe. To make it available globally, add the .venv\Scripts\ directory to your PATH.

First install downloads ~70 packages and takes 2-3 minutes. Subsequent installs use pip's cache and are much faster.

Verify: openlegion --help

Setup and Start

openlegion start     # inline setup on first run, then launch agents + chat REPL

On first run (no credentials configured), openlegion start offers three paths:

  1. Quick setup here — pick a provider, paste your API key (validated), choose a model, then optionally create your first agent
  2. Open the dashboard — configure everything via the web UI at /dashboard
  3. Skip — start the runtime and use /addkey later in the REPL

Two Docker images build automatically on first run: the agent image (~1 min) and browser service image (Camoufox + KasmVNC, ~3 min). Config files (config/mesh.yaml, config/agents.yaml, config/permissions.json) are created automatically during setup.

Using the REPL

@researcher Research the latest developments in AI agent frameworks.
/costs              # per-agent LLM spend
/agents             # list running agents
/broadcast Hello!   # message all agents
/quit               # exit REPL and stop runtime (foreground mode; use openlegion stop for background mode)

After Setup

openlegion start -d             # run in background
openlegion chat researcher      # connect from another terminal
openlegion stop                 # shut down

Use /add in the REPL to add more agents to a running system.

Telegram / Discord (optional)

Add channel tokens to .env:

OPENLEGION_SYSTEM_TELEGRAM_BOT_TOKEN=123456:ABC...
OPENLEGION_SYSTEM_DISCORD_BOT_TOKEN=MTIz...

The OPENLEGION_SYSTEM_* form is the recommended host-level tier. The OPENLEGION_CRED_* form and bare env vars (e.g., TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN) also work.

On next openlegion start, a pairing code appears — send /start <code> to your Telegram bot (or DM /start <code> to your Discord bot) to link.

Docker Sandbox (maximum security)

By default, agents run in standard Docker containers — secure for most use cases. For stronger isolation, Docker Sandbox runs each agent in its own microVM with a dedicated kernel:

# Check if your Docker supports sandboxes
docker sandbox version

# Start with microVM isolation
openlegion start --sandbox

Requirements: Docker Desktop 4.58+ (macOS or Windows). If docker sandbox version returns an error, update Docker Desktop.

Why use it? Standard containers share the host kernel — a kernel exploit could theoretically escape. Sandbox microVMs give each agent its own kernel via Apple Virtualization.framework (macOS) or Hyper-V (Windows), making escape significantly harder. Use --sandbox when running untrusted code or when compliance requires hypervisor-level isolation.

Troubleshooting

Problem Fix
command not found: openlegion Re-run ./install.sh or add ~/.local/bin to PATH: export PATH="$HOME/.local/bin:$PATH". On Windows, restart your terminal after install.
Docker is not running Open Docker Desktop (macOS/Windows) or sudo systemctl start docker (Linux)
permission denied on Docker Linux: sudo usermod -aG docker $USER then log out/in
python3: command not found Install Python 3.10+ (see above). On Windows, use python instead of python3.
pip install is slow First install downloads ~70 packages (2-3 min). This is normal. Subsequent installs are fast.
pip install permission error Activate the venv first — don't install globally.
Docker build is slow First build downloads base image + Camoufox (stealth Firefox) (~3 min for browser image, ~1 min for agent image). Rebuilds are fast.
Agent not responding openlegion status to check health. Verify API key has credits.
PowerShell blocks scripts Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser