> ## 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.

# Installation: CLI, Docker, and SDK Setup for AgentRail

> Install the AgentRail CLI with npm or npx, run the server with Docker, and configure GitHub, CircleCI, and Linear tokens via environment variables.

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

### Global install (recommended)

Installing globally lets you run `agentrail` commands directly from any directory:

```bash theme={null}
npm install -g @agentrail-core/cli
```

Verify the install:

```bash theme={null}
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`:

```bash theme={null}
npx @agentrail-core/cli init
npx @agentrail-core/cli doctor
```

## Docker

For a server-only run without CLI-managed config, use Docker Compose:

```bash theme={null}
docker compose up --build
```

The API listens on `http://127.0.0.1:3000` by default.

<Note>
  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](/docs/quickstart) instead.
</Note>

## 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.

<Tabs>
  <Tab title="TypeScript">
    ```bash theme={null}
    npm install @agentrail-core/sdk
    ```

    Requires Node.js 18 or newer.
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install agentrail
    ```
  </Tab>
</Tabs>

## 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.

| Variable             | Description                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| `GITHUB_TOKEN`       | Personal access token for GitHub. Enables PR submission and GitHub Actions CI status.           |
| `CIRCLECI_TOKEN`     | API token for CircleCI. Enables CI status for tasks using CircleCI.                             |
| `LINEAR_API_KEY`     | API key for Linear. Enables issue import and sync.                                              |
| `AGENTRAIL_BASE_URL` | Base URL of the AgentRail API, used by agents and the SDK. Defaults to `http://127.0.0.1:3000`. |
| `AGENTRAIL_API_KEY`  | Agent API key for authenticating requests. Created during `agentrail agent create`.             |

<Tip>
  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.
</Tip>

<Warning>
  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`.
</Warning>