slug: quickstart

Quickstart

Get Open Agent Router running in three steps: install, start the backend, point your agent at it. Pick the mode that matches your machine.

1. Install

OAR ships in two modes that share the same backend — choose one.

Desktop mode (macOS / Linux / Windows)

Download the installer for your platform from the Download page. The desktop build bundles its own oar binary — no separate Node.js install required.

On first launch the app runs oar init --from-app to sync bundled resources into ~/.open-agent-router/, then starts the backend service. The app lives in your system tray:

  • Closing the window hides to tray — the backend keeps running.
  • Enable Auto-start in Settings (or via the tray menu) to launch OAR at login (launchd on macOS, equivalent autostart entries elsewhere).
  • Updates arrive through the R2 CDN channel and prompt you from the tray.

CLI mode (headless / servers / automation)

Install the standalone oar binary with the one-liner:

install — bash
$ bash <(curl -fsSL https://raw.githubusercontent.com/SnowAIGGirl/open-agent-router/master/scripts/install.sh)

Already installed? Run oar update to check for and apply the latest release.

2. Start the backend

Desktop mode — just open the app. The backend starts automatically and the Web UI opens at http://127.0.0.1:26969.

CLI mode — start the long-lived service:

start — bash
$ oar start
# Web UI + Admin API: http://127.0.0.1:26969
# Agent proxy: http://127.0.0.1:26969

Check that it's up:

status — bash
$ oar status
# pid: 41203 uptime: 12s port: 26969 listening: yes

Both the admin Web UI (/api/*) and the agent proxy share :26969. Change the port with the OAR_PROXY_PORT environment variable. Use oar stop to shut the backend down and oar restart to reload config.

First-run auto-scan

On first launch — desktop or CLI — OAR can scan your local agent config files (Hermes, Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI) and pre-create platform instances with their API keys. Review the discovered entries and confirm — no manual entry required. See the Supported Agents page for the full list of scan paths.

3. Point your agent at OAR

Configure your agent's base_url to a project route. For Claude Code:

claude code — base_url
$ # base_url
http://127.0.0.1:26969/project/your-project
# Configure once. Switch groups from the Web UI later.

That's it. The base_url never changes again — switching groups or models happens in OAR, not in the agent's config file.

Configure a route in the Web UI

  1. Open http://127.0.0.1:26969 (in desktop mode, just focus the app window).
  2. Platforms → Add account — pick a vendor preset (DeepSeek, OpenAI, Anthropic, Volcano Engine, SiliconFlow, MiniMax…) or enter a custom base_url + API key.
  3. Models → Sync — pull the live model list from /v1/models.
  4. Groups → New group — add the models you want pooled together (you can mix protocols and platforms).
  5. Agents → Edit — set the default group for each agent.
  6. Projects → New project route — bind a project name to an agent + group. The project's base_url becomes http://127.0.0.1:26969/project/<name>.

Verify

Send a test request through the proxy:

verify — bash
$ curl http://127.0.0.1:26969/project/your-project/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"claude-sonnet-4","messages":[{"role":"user","content":"ping"}]}'

Watch the request appear in Logs and the routing flow in Routing Topology.

Next, read the Core Concepts to understand platforms, models, groups, agents and projects.

Previous

Introduction

Next

AI Skill