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
WebKit2GTK	4.1	Tauri 2.x rendering engine
System libs	--	See below

System libraries (Debian/Ubuntu)

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

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

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:

{
  "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

# 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 -- all env vars, config files, and per-project settings.
• Provider reference -- Claude, Codex, Ollama, Aider setup.
• btmsg reference -- inter-agent messaging.
• bttask reference -- kanban task board.