GuideExtended Installation

Extended Installation

The Getting Started guide covers the recommended user path: npm install -g agor-live. This page covers everything else for users and teams running Agor — optional companions, deployment alternatives, authentication options, and edge-case configurations.

Want to build, modify, or contribute to Agor? Head to the Development Guide — it covers docker compose up, the .agor.yml variant system (SQLite / Postgres / RBAC / docs), and developing Agor with Agor itself.

Requirements

  • Node.js ≥ 22.12 — see nodejs.org for installation.

That’s the only hard requirement. Everything below is either an alternative install method or an optional companion.

Optional: Zellij (for the web terminal)

Agor has a built-in web terminal that uses Zellij for persistent, multiplexed terminal sessions. The terminal is optional — Agor runs fine without it; if you don’t have Zellij, terminal buttons in the UI will show a friendly message instead.

If you want the terminal:

  1. Install Zellij from the official installation guide.
  2. Restart the Agor daemon (agor daemon restart).

The daemon detects Zellij at startup and logs whether it’s available.

Authentication

Agor supports Claude Code, Codex, Gemini, OpenCode, and GitHub Copilot. The onboarding wizard handles the simple case — paste an API key, done. This section covers the alternatives: subscription-based auth, server-side CLI login, workspace-wide fallbacks, and how Agor resolves them when several are present.

Credential resolution order

When a session starts, Agor looks for credentials in this order and uses the first one it finds:

  1. Per-user credentials — encrypted in the DB, scoped to the user. Set via the wizard or Settings → Agentic Tools → tool. For Claude Code this means either an ANTHROPIC_API_KEY (pay-as-you-go) or a CLAUDE_CODE_OAUTH_TOKEN (Pro/Max subscription, from claude setup-token); the SDK prefers the OAuth token when both are set.
  2. claude login credentials — ~/.claude/ on the daemon host.
  3. Workspace env vars — ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_AI_API_KEY. Visible to all users on the instance.

Mixing is fine: one user can run on a Max Pro token while teammates use per-user API keys.

Claude Max / Pro plan

If you have a Claude Max or Pro subscription, you can use it instead of an API key.

1. Install the Claude CLI locally (skip if already installed):

npm install -g @anthropic-ai/claude-code

2. Generate a session token:

claude setup-token

Copy the output.

3. Paste it into Agor: open User Settings → Agentic Tools → Claude Code and paste the token into the Claude Subscription Token field. All your Claude Code sessions will use the subscription.

CLI login on the daemon host (self-hosted)

If you can SSH into the machine running the daemon:

claude login

Credentials land in ~/.claude/ and Agor picks them up automatically. This is the lowest-config path for solo self-hosted setups.

Workspace env vars (global fallback)

For instances where everyone shares one set of credentials:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_AI_API_KEY="..."

Or via Settings → Environment Variables (admin only). These are visible to every user on the instance — pick this only if that’s intentional.

Per-user API keys (recommended for teams)

The wizard’s default. Each user pastes their own key in Settings → Agentic Tools. Keys are encrypted at rest, scoped per-user, and never exposed to other users on the instance. Get keys at:

Custom config location

By default Agor reads ~/.agor/config.yaml and stores the database at ~/.agor/agor.db.

Override the config path with the --config flag or the AGOR_CONFIG_PATH environment variable:

agor daemon start --config /etc/agor/config.yaml
# or
AGOR_CONFIG_PATH=/etc/agor/config.yaml agor daemon start

Heads-up: custom config paths are not yet threaded through every code path (e.g. database URL resolution). If you hit issues, please file an issue.

What’s next?

Getting StartedFeatures Overview
BSL 1.1 © 2026 Maxime Beauchemin