slug: configuration

Configuration

OAR keeps everything in a single data directory. The backend reads its config from this directory plus a handful of environment variables and a settings table in SQLite. This page covers each layer, from filesystem layout to runtime settings.

Data directory

All persistent state lives under ~/.open-agent-router/. The directory is created on first run by oar init (or oar init --from-app in the desktop app).

~/.open-agent-router/
├── bin/oar                          # The oar binary (copied here by init/install)
├── ui-dist/                         # Web UI static files
├── assets/                          # Vendor icons and other assets
├── vendor-icons/                    # SVG icons for vendor presets
├── manifest.json                    # Version + MD5 hashes of bundled resources
├── oar.db                           # SQLite database (node:sqlite, zero-dependency)
├── logs/
│   ├── proxy-YYYY-MM-DD.log         # Daily rolling JSONL logs
│   └── proxy-YYYY-MM-DD.log
├── captures/                        # Capture records (JSON files)
└── launchd plist (macOS)            # com.open-agent-router.plist

Path	Purpose
`bin/oar`	The `oar` binary itself. Updated atomically by `oar update`.
`ui-dist/`	Static files for the admin Web UI served at `/`.
`assets/`, `vendor-icons/`	Vendor icons and assets used by the Web UI.
`manifest.json`	Lists every bundled resource with its MD5 hash. The desktop app hash-compares this on every launch to sync only what changed.
`oar.db`	The single SQLite database — accounts, models, groups, agents, projects, settings and activity all live here.
`logs/`	Daily-rolling JSONL proxy logs. See Logs & Monitoring.
`captures/`	Capture session JSON files. See Capture.
`com.open-agent-router.plist`	launchd entry used by auto-start on macOS. Removed by `oar service uninstall`.

Zero-dependency database

oar.db is opened with Node's built-in node:sqlite module. There is no better-sqlite3 to compile and no native addon to ship — the database layer has zero external dependencies.

Environment variables

Environment variables control process-level behaviour. The desktop (Tauri) shell sets the resource paths automatically; in CLI mode you usually only need OAR_PROXY_PORT.

Variable	Default	Description
`OAR_PROXY_PORT`	`26969`	Port for both the admin API (`/api/*`) and the agent proxy.
`OAR_RESOURCES_DIR`	—	Bundled resources root. Set by the Tauri shell.
`OAR_ASSETS_DIR`	—	Path to the assets directory. Set by the Tauri shell.
`OAR_UI_DIST_DIR`	—	Path to the UI dist directory. Set by the Tauri shell.
`OAR_RESTART_WAIT`	—	Wait in milliseconds before starting. Used internally by `oar restart`.
`NODE_ENV`	—	Set to `production` by the Tauri shell.

Changing the port

Export OAR_PROXY_PORT before oar start, then update each agent's base_url to match. The admin Web UI and the agent proxy share the same port — there is no separate admin port.

Port configuration

The backend binds to 127.0.0.1:26969 by default and serves both roles on that port:

Admin API — /api/* (used by the Web UI and the oar CLI commands)
Agent proxy — /agent/*, /group/*, /project/* (used by your agents' base_urls)

To run on a different port:

custom port — bash

$ export OAR_PROXY_PORT=8080

oar start

# Web UI + Admin API: http://127.0.0.1:8080

# Agent proxy: http://127.0.0.1:8080

The port is bound to the loopback interface only — OAR is not reachable from the network unless you tunnel it yourself.

Settings

Settings are stored in the settings table inside oar.db and are read at runtime by the backend and the Web UI. Manage them with oar settings:

Command	Description
`oar settings list`	List all settings and their current values
`oar settings set <key> <value>`	Update a setting

settings — bash

$ oar settings list

# autoLaunch true

# locale en

# modelCooldownSeconds 60

# keepDock true

oar settings set modelCooldownSeconds 120

# modelCooldownSeconds = 120

Available settings

Key	Default	Description
`autoLaunch`	`true`	Auto-start the service on boot. Set to `false` to disable.
`locale`	`en`	UI language. One of `en`, `zh-CN`, `ko`.
`modelCooldownSeconds`	—	Default cooldown (seconds) applied to models inside a group after repeated upstream failures.
`keepDock`	`true`	macOS only. When `false`, hiding the window also removes the Dock icon — the app presence collapses to the tray.

Settings vs. environment variables

Environment variables tune the process (port, resource paths). Settings tune the service (auto-launch, locale, cooldown). Use environment variables at launch time; use oar settings set any time — most take effect immediately without a restart.

Config file scanning

On first launch, OAR can scan your local agent config files and pre-create platform instances with their API keys. Scan results are presented for confirmation before anything is written to SQLite — you stay in control.

The full list of scan paths (Hermes, Claude Code, Claude Desktop, Codex, OpenCode, OpenClaw, Gemini CLI) is on the Supported Agents page.

Continue to Logs & Monitoring for log format, capture and activity, or jump to the CLI Reference for the full command surface.

CLI Reference

Logs & Monitoring