Installation and deployment paths

Installation and deployment paths

Choose how you run agent-detective on a host or in your cluster. This page is the entry point; the detailed guides are linked below.

Reading order

Use the Configuration section in the sidebar after you pick an install path—load order and env are documented there.

Typical reading order: get started → CLI reference → this page → golden path → configuration hub.

Recommended for operators: follow get started, then deployment.md for systemd and nginx on a VM.

Choose a deployment style

npm CLI

When to use: Run on a host where you already have Node.js 24+ and your agent CLI (OpenCode, Claude, Cursor) installed and authenticated.

What you need: Node.js 24+, git, and the configured agent on PATH.

Install and scaffold

npm i -g agent-detective
agent-detective init
agent-detective doctor
agent-detective
agent-detective smoke   # server running in another terminal

Use npx agent-detective instead of a global install if you prefer. Commands: CLI reference. Production: deployment.md.

From source

When to use: You fork the repo, change packages/, or contribute to the monorepo.

What you need: Node.js 24+, pnpm 10+ (see root package.json packageManager), git.

Clone and build

git clone https://github.com/andezdev/agent-detective.git
cd agent-detective
pnpm install
pnpm run build
pnpm run build:app
pnpm start

Replace andezdev/agent-detective with your fork’s owner/name on GitHub if applicable.

Bare metal

When to use: Long-running service on a VM with nginx or similar.

What you need: See deployment.md for systemd unit, nginx reverse proxy, sizing, and health checks.

Kubernetes

This repository does not ship Helm charts. Run the app in your platform’s standard workload (container image you build, or a VM with Node + the npm CLI) using the same config/ + env model as in configuration.md and deployment.md.

Host capabilities

• Process: Node.js 24+ (npm CLI or from-source build).
• Configuration: JSON under config/ (configuration.md); scaffold with agent-detective init (copies default.json from the package). From source: copy config/local.example.json → config/local.json.
• Repositories: the local-repos plugin needs git and filesystem access to the repos you list in config (local paths or bind mounts you configure).
• Network: outbound to Jira (if you use the Jira plugin), to git remotes (for pr-pipeline), and to your AI provider as required by the agent CLI (e.g. OpenCode). Inbound: HTTP(S) to the app (webhooks, API).
• Agent CLIs: the host must be able to run the configured agent (e.g. opencode). See cursor-agent.md for the Cursor CLI, which is not installed via npm.

Configuration (all paths)

Caution

Use config/local.json (gitignored) or environment variables for secrets. Never commit API tokens or credentials to config/default.json.

1. Read the configuration hub for load order and top-level config shape.
2. Use configuration.md for the full env whitelist and plugin narratives.
3. Use config/local.json and/or the env whitelist for secrets in production.
4. For plugin option fields, use generated/plugin-options.md.

Detailed guides

Get started (~5 min) npm install, init, mock webhook smoke.

CLI reference init, doctor, smoke, validate-config.

Golden path Local smoke, then first real Jira webhook.

Deployment systemd, nginx, health checks.

Configuration Config files, env whitelist, plugin options.

Upgrading Releases and npm upgrade.

Jira E2E (deep dive) Tunnel, webhooks, troubleshooting.

Development Monorepo contributors.

See also

• configuration-hub.md — config load order and top-level keys
• upgrading.md — releases and upgrade runbook
• Root README.md — quick start
• extending-with-plugins.md — npm, path, or plugins/ directory for custom plugins
• publishing.md — publishing @agent-detective/* packages (maintainers)
• Release notes live in GitHub Releases; see docs/operator/upgrading.md.