Installation & Setup

Get Ashlr AO running and spawn your first AI coding agent in under 30 seconds.

Prerequisites

Before installing Ashlr AO, make sure you have the following:

Tip: Claude Code is the recommended backend. It supports plan mode, model selection, tool restriction, and stream-json output mode.

Install via pip

The fastest way to get started:

pip install ashlr-ao
ashlr

This installs the ashlr CLI command. Running it starts the server and opens the dashboard at http://127.0.0.1:5111.

CLI Options

ashlr                          # Start with defaults
ashlr --port 8080              # Custom port
ashlr --host 0.0.0.0           # Bind to all interfaces
ashlr --demo                   # Demo mode (no real agents)
ashlr --log-level DEBUG        # Verbose logging
ashlr --version                # Print version and exit

Install from Source

Clone the repository and use the included start script:

git clone https://github.com/ashlrai/ashlr-ao.git
cd ashlr-ao
./start.sh

The start.sh script creates a virtual environment, runs pip install -e ., verifies tmux and backends are available, and starts the server.

Install with Docker

For containerized deployments:

git clone https://github.com/ashlrai/ashlr-ao.git
cd ashlr-ao
docker compose up -d

See the Deployment guide for full Docker + HTTPS configuration with Caddy.

First Run

On first launch, Ashlr AO automatically:

  1. Creates the config directory at ~/.ashlr/
  2. Generates a default ashlr.yaml config file
  3. Creates the SQLite database at ~/.ashlr/ashlr.db
  4. Cleans up any orphaned tmux sessions from prior crashes
  5. Starts the aiohttp server on port 5111
  6. Opens the dashboard in your default browser

Spawning Your First Agent

From the Dashboard

  1. Open the dashboard at http://127.0.0.1:5111
  2. Press Cmd+N or click the + card to open the spawn dialog
  3. Choose a role (e.g., Backend Engineer)
  4. Select a backend (e.g., claude-code)
  5. Enter the working directory path to your project (e.g., ~/Projects/my-app)
  6. Type a task description (e.g., "Add input validation to the user registration endpoint")
  7. Click Spawn

The agent card appears in the grid immediately. Status updates from planning to working to idle as the agent progresses.

From the Command Bar

Press Cmd+K to open the command palette, then type a natural language command:

spawn backend agent on ~/Projects/my-app to add input validation

If you have the intelligence layer enabled (requires XAI_API_KEY), Ashlr parses natural language into structured commands automatically.

From the REST API

curl -X POST http://127.0.0.1:5111/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "role": "backend",
    "task": "Add input validation to the user registration endpoint",
    "working_dir": "~/Projects/my-app",
    "backend": "claude-code"
  }'

Quick Templates

The spawn dialog includes quick templates for common tasks:

Fleet Presets (Pro)

Spawn multiple agents at once with fleet presets:

Dashboard Overview

Agent Card Grid

The main view shows a grid of agent cards. Each card displays:

Click any card to open the deep view with full terminal output, activity feed, and scratchpad.

Interacting with Agents

When an agent needs input (status: waiting), the card highlights with an orange attention indicator. Click the card or press Cmd+Shift+A to open the attention queue. Interaction options include:

Filtering and Search

Use the toolbar above the card grid to filter agents by:

Keyboard Shortcuts

ShortcutAction
Cmd+KCommand palette
Cmd+NNew agent
Cmd+,Settings
Cmd+Shift+SToggle bulk select mode
Cmd+Shift+AAttention queue (waiting agents)
Cmd+Shift+FFocus mode (single project)
Cmd+/Global search
1–9Focus agent or select role
EscapeClose overlay / back to grid
Space (hold)Push-to-talk voice input

Enabling the Intelligence Layer

The intelligence layer provides LLM-powered agent summaries, natural language command parsing, and fleet analysis. It requires an xAI API key:

export XAI_API_KEY="your-xai-api-key"
ashlr

When enabled, Ashlr uses xAI Grok (via OpenAI-compatible API) to:

The intelligence layer includes a circuit breaker: after 5 consecutive failures, it enters a 60-second cooldown. When the LLM is unavailable, Ashlr falls back to regex-based parsing.

Adding Projects

Projects group agents by repository. To add a project:

curl -X POST http://127.0.0.1:5111/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "path": "~/Projects/my-app"
  }'

Or use the dashboard: open Settings (Cmd+,) and add projects from the Projects section. Ashlr auto-detects git remote URL, default branch, and other metadata.

Security note: Working directories are restricted to paths under ~/ or /tmp. Use symlinks if your repos are elsewhere.

Next Steps

Edit this page on GitHub