Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentrail.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

AgentRail has two components you might install: the CLI (used for setup, server management, and agent operations) and the SDK (used when you are writing an agent harness or workflow runner in TypeScript or Python). This page covers all three install paths and the environment variables you can set to configure provider connections.

​
Prerequisites

  • Node.js 24 or newer — required for the CLI and the server runtime. Run node --version to confirm. Node.js 18 or newer is sufficient if you are using the SDK only (without the CLI or local server).
  • npm — comes with Node.js.

​
CLI installation

Installing globally lets you run agentrail commands directly from any directory: 
npm install -g @agentrail-core/cli
Verify the install: 
agentrail --help

​
npx (no global install)

If you prefer not to install globally or you are running in CI, prefix any command with npx @agentrail-core/cli: 
npx @agentrail-core/cli init
npx @agentrail-core/cli doctor

​
Docker

For a server-only run without CLI-managed config, use Docker Compose: 
docker compose up --build
The API listens on http://127.0.0.1:3000 by default.
Docker starts the AgentRail API server, but it does not run the interactive CLI setup. For a useful local setup with agent credentials, routing state, and provider connections, use the CLI-assisted path described in the quickstart instead.

​
SDK installation

The SDK is a client library for a running AgentRail API. Install it separately in your agent harness or application — it does not start the server or manage local config. 
npm install @agentrail-core/sdk
Requires Node.js 18 or newer.

​
Environment variables

You can configure AgentRail’s provider connections and server behavior through environment variables. These are useful for CI pipelines, non-interactive automation, or Docker-based deployments.
VariableDescription
GITHUB_TOKENPersonal access token for GitHub. Enables PR submission and GitHub Actions CI status.
CIRCLECI_TOKENAPI token for CircleCI. Enables CI status for tasks using CircleCI.
LINEAR_API_KEYAPI key for Linear. Enables issue import and sync.
AGENTRAIL_BASE_URLBase URL of the AgentRail API, used by agents and the SDK. Defaults to http://127.0.0.1:3000.
AGENTRAIL_API_KEYAgent API key for authenticating requests. Created during agentrail agent create.
For interactive setup, use agentrail provider connect <github|circleci|linear>. The connect command prompts for secrets in hidden inputs and writes them to local env files — you do not need to set environment variables manually.
Do not commit provider tokens or generated AgentRail API keys to source control. The agentrail provider connect flow stores them in local env files under ~/.agentrail.