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:

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

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

GitHub Codespaces

Community-maintained. Codespaces is supported on a best-effort basis and is not part of the regular test/release cycle. For day-to-day use, prefer the npm install path.

Agor has a devcontainer that boots a Codespace pre-configured with Node, pnpm, and the running daemon:

Useful for quick demos. See the Security guide for trust-boundary notes before sharing a Codespace with collaborators.

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:

Per-user API keys — encrypted in the DB, scoped to the user. Set via the wizard or Settings → Agentic Tools.
CLAUDE_CODE_OAUTH_TOKEN — per-user env var (e.g. from claude setup-token).
claude login credentials — ~/.claude/ on the daemon host.
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 → Env vars and add CLAUDE_CODE_OAUTH_TOKEN = your token. All your Claude Code sessions will use the subscription.

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:

Anthropic: console.anthropic.com/settings/keys
OpenAI: platform.openai.com/api-keys
Google AI: aistudio.google.com/app/apikey

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 Started — add your first repo and create a session.
Worktrees, Sessions & Trees, Boards & Zones — core primitives.
Development Guide — contributor workflow.

Getting Started Features Overview