Skip to Content
DocsExtended 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, including Homebrew, 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

That’s the only hard requirement for npm installs. The Homebrew formula installs a compatible Node runtime for you. Everything below is either an alternative install method or an optional companion.

Install paths

Use whichever install method fits your setup:

Most users should start here. It’s the most universal path, and it’s the one the rest of the docs assume.

Requires Node.js ≥ 22.12 (install ).

# Install Agor
npm install -g agor-live
 
# First run
agor init
agor daemon start
agor open

Homebrew is a convenience path for macOS/Linux users; npm remains the canonical cross-platform install path used throughout the docs.

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.

Agor does not require pgvector to install, upgrade, or run. Knowledge text search works without it.

If you want Knowledge semantic or hybrid search on PostgreSQL, install the pgvector package on the Postgres server and enable the extension in the Agor database:

CREATE EXTENSION IF NOT EXISTS vector;

Run that as a database owner or another role with permission to create extensions. After pgvector is enabled, configure Knowledge semantic search in Agor and run a Knowledge reindex; the daemon creates the vector storage table and index idempotently when the feature is enabled.

If pgvector is missing or the Agor DB user cannot enable it, semantic search returns a clear semantic_unavailable error and text search continues to work.

Authentication

Agor supports Claude Code, Codex, Gemini, OpenCode, GitHub Copilot, and Cursor. The onboarding wizard handles the simple case. Paste an API key, done.

Credential resolution policy

Workspace admins choose an explicit policy per tool:

  • Require personal. Personal configuration only.
  • Prefer personal. Personal configuration, then workspace configuration. This is the default.
  • Prefer workspace. Workspace configuration, then personal configuration.
  • Require workspace. Workspace configuration only.

Personal credentials are encrypted in the DB and set through User Settings → Agentic Tools. Workspace credentials are encrypted in the tenant-scoped DB and managed through Workspace Settings → Agentic Tools. Policy changes do not delete dormant personal credentials.

The complete provider connection always comes from one scope. Agor does not combine a credential from one scope with an endpoint from another, and does not fall back to config.yaml or daemon environment variables. Claude users explicitly choose a subscription token or API-key connection. Codex users explicitly choose an API key or declare that they authenticated the Codex CLI with codex login; native Codex login is never inferred merely because no key exists. Shared-machine Codex subscription authentication is rejected in hosted required_from_auth mode.

Upgrading from implicit CLI or environment authentication: Agor intentionally does not migrate or infer shared-machine native login state. Each affected user must select their authentication method in User Settings → Agentic Tools; Claude subscription users must save a claude setup-token token, while Codex subscription users explicitly declare their existing codex login. Until then, Agor reports the provider as unavailable instead of silently borrowing ambient credentials.

Agentic-tool configuration governance

Workspace administrators can define live, tool-specific presets under Workspace Settings → Agentic Tools. Configuration surfaces always ask for the tool first and then show only presets for that tool. When inline configuration is allowed, members may instead choose Define configuration here.

Administrators can require presets independently for each tool. Presets contain runtime behavior (model, permissions, and sandbox policy) but never provider credentials or MCP attachments. MCP servers are selected independently on sessions, schedules, and gateway channels. Referenced presets cannot be deleted. Editing a preset affects the next task started by every session, schedule, or gateway channel that references it; a running task keeps the configuration resolved when it started.

Each tool may have one workspace default preset. Users can choose that moving workspace default, a specific preset, or (when policy permits) an inline personal default. Creation forms also offer Use my default. Sessions and gateway channels resolve those defaults when saved, then store the concrete preset reference or inline configuration. Schedules preserve a symbolic user/workspace default and resolve it from the schedule creator immediately before every run, so later default changes apply to the next run. A schedule that names a specific preset continues to follow that preset directly.

Agor uses these credentials only to authenticate the agent runtime with the provider SDK/CLI. Stored secrets are encrypted at rest and are not written into the prompt transcript or intentionally sent to the model as text.

Mixing is fine: one user can run on a Claude subscription token while teammates use a workspace API key.

Claude subscription auth (claude setup-token)

Use this when you have Claude Pro, Max, Team, or Enterprise subscription access and want Agor to run Claude Code without an Anthropic Console API key. Run the command on the machine where Agor sessions execute. In strict Unix isolation, run it as the same Unix user that will own the sessions.

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

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

2. Generate a long-lived OAuth token:

claude setup-token

Copy the printed token.

3. Paste it into Agor: open User Settings → Agentic Tools → Claude Code and paste the token into Claude Subscription Token. Agor stores it as CLAUDE_CODE_OAUTH_TOKEN for your user.

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:

Choose raw API keys when you want explicit usage and billing through API-provider accounts. Workspace admins can provide a shared fallback without exposing it to members.

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?

Last updated on
Getting StartedFeature Map