agent-orchestrator/docs/getting-started/quickstart.md

# Quickstart

Get Agents Orchestrator (agor) running locally in under 10 minutes.

## Prerequisites

| Dependency | Version | Notes |
|------------|---------|-------|
| Node.js | 20+ | npm included |
| Rust | 1.77+ | Install via [rustup](https://rustup.rs/) |
| WebKit2GTK | 4.1 | Tauri 2.x rendering engine |
| System libs | -- | See below |

### System libraries (Debian/Ubuntu)

```bash
sudo apt install \
  libwebkit2gtk-4.1-dev \
  libgtk-3-dev \
  libappindicator3-dev \
  librsvg2-dev \
  libssl-dev \
  libsoup-3.0-dev \
  javascriptcoregtk-4.1 \
  patchelf
```

### Optional dependencies

- **Claude Code CLI** -- Required for the Claude provider. Auto-detected at
  `~/.local/bin/claude`, `~/.claude/local/claude`, `/usr/local/bin/claude`, or
  `/usr/bin/claude`.
- **Deno** -- Preferred sidecar runtime (faster startup). Falls back to Node.js.
- **Ollama** -- Required for the Ollama provider. Must be running on
  `localhost:11434`.

## Clone and build

```bash
git clone git@github.com:DexterFromLab/agent-orchestrator.git
cd agent-orchestrator

npm install
npm run tauri dev
```

The dev server runs on port **9700**. Tauri opens a native window automatically.

### Production build

```bash
npm run tauri build
```

Output: `.deb` and AppImage in `src-tauri/target/release/bundle/`.

## Project configuration

Agor organizes work into **groups**, each containing one or more **projects**
(codebases) and optional **agents** (Tier 1 management roles).

Configuration lives in `~/.config/agor/groups.json`. On first launch, agor
creates a default file. You can also create it manually:

```json
{
  "version": 1,
  "groups": [
    {
      "id": "my-team",
      "name": "My Team",
      "projects": [
        {
          "id": "backend",
          "name": "Backend API",
          "identifier": "backend-api",
          "description": "REST API service",
          "icon": "B",
          "cwd": "/home/user/code/backend",
          "profile": "default",
          "enabled": true,
          "provider": "claude"
        },
        {
          "id": "frontend",
          "name": "Frontend App",
          "identifier": "frontend-app",
          "description": "Svelte web client",
          "icon": "F",
          "cwd": "/home/user/code/frontend",
          "profile": "default",
          "enabled": true,
          "provider": "claude",
          "model": "claude-sonnet-4-6"
        }
      ],
      "agents": [
        {
          "id": "mgr-1",
          "name": "Manager",
          "role": "manager",
          "enabled": true,
          "wakeIntervalMin": 3,
          "wakeStrategy": "smart",
          "wakeThreshold": 0.5
        }
      ]
    }
  ],
  "activeGroupId": "my-team"
}
```

### Key fields

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique identifier within the group |
| `cwd` | Yes | Absolute path to the project directory |
| `provider` | No | `claude` (default), `codex`, `ollama`, or `aider` |
| `model` | No | Model override; falls back to provider default |
| `profile` | No | Claude profile name from `~/.config/switcher/profiles/` |
| `useWorktrees` | No | Enable git worktree isolation per session |
| `sandboxEnabled` | No | Enable Landlock filesystem sandbox (Linux 5.13+) |
| `autonomousMode` | No | `restricted` (default) or `autonomous` |
| `anchorBudgetScale` | No | Anchor token budget: `small`, `medium`, `large`, `full` |
| `stallThresholdMin` | No | Minutes before idle agent is marked stalled (default 15) |

## Creating your first agent session

1. Launch agor (`npm run tauri dev` or the built binary).
2. The workspace shows your configured projects as cards in a grid.
3. Click a project card to focus it. The **Model** tab opens by default.
4. Type a prompt in the input area at the bottom and press Enter.
5. Agor spawns a sidecar process, connects to the provider, and streams
   responses in real time.

The agent session persists across tab switches. Closing the project card stops
the agent.

## Keyboard shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+B` | Toggle sidebar |
| `Ctrl+,` | Open settings |
| `Ctrl+Shift+F` | Full-text search overlay |
| `Ctrl+K` | Command palette |
| `Alt+1` -- `Alt+5` | Focus project 1--5 |
| `Escape` | Close sidebar / overlay / palette |

## Running tests

```bash
# All tests (vitest frontend + cargo backend)
npm run test:all

# Frontend only
npm run test

# Backend only
npm run test:cargo

# E2E tests (requires built binary)
npm run test:all:e2e
```

## Directory layout

```
agent-orchestrator/
  agor-core/          # Shared Rust crate (PTY, sidecar, supervisor, sandbox)
  agor-relay/         # Standalone relay binary (WebSocket server)
  src-tauri/          # Tauri app (Rust backend)
  src/                # Svelte 5 frontend
  sidecar/            # Provider runner scripts (compiled to .mjs)
  docs/               # Project documentation
  tests/e2e/          # WebDriverIO E2E tests
```

## Next steps

- [Configuration reference](../config/ref-settings.md) -- all env vars, config
  files, and per-project settings.
- [Provider reference](../providers/ref-providers.md) -- Claude, Codex, Ollama,
  Aider setup.
- [btmsg reference](../agents/ref-btmsg.md) -- inter-agent messaging.
- [bttask reference](../agents/ref-bttask.md) -- kanban task board.