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

# Self-host AgentRail on your local hardware or a VPS

> Run AgentRail on your own hardware or a VPS. Understand what self-hosting includes, what it doesn't, and which setup path to follow.

AgentRail is a local-first product. You can run the full lifecycle API on your own machine, a VPS, or any Linux server you control — without a hosted account. Self-hosting gives you full control over your data, credentials, and runtime environment.

## What self-hosting includes

When you self-host AgentRail using the source-available runtime, you get:

* The local API server (`agentrail server start`) that serves tasks, events, CI status, review feedback, and ship operations
* The full task lifecycle API and SDKs
* Local event streaming and webhook primitives
* Adapter interfaces for GitHub, CircleCI, and Linear using your own credentials
* CLI-managed setup for agents, routing rules, and provider state

## What self-hosting does not include

Self-hosting is a single-instance runtime. It is not the same as the planned AgentRail Cloud team control plane. The following capabilities are Cloud-only and are not part of the self-hosted runtime:

* **Managed provider connectors** — AgentRail Cloud operates credential storage, OAuth apps, webhook verification, retries, and backfills on your behalf. In self-hosted mode, you supply your own tokens and manage your own webhook exposure.
* **Durable shared run history** — Cloud persists routing decisions, run history, event cursors, and audit logs across your team. Self-hosted setups store state locally on the machine running the server.
* **SSO, RBAC, and SCIM** — Access control and identity federation are Cloud features.
* **Fleet routing and dashboards** — Multi-agent assignment, capacity management, and operational dashboards are Cloud features.
* **Support and compliance** — SLA coverage, SOC 2 evidence, incident response, and backup guarantees are Cloud features.

<Note>
  Deploying AgentRail on a VPS with Docker is self-hosting, not a Cloud-equivalent team control plane. See the AgentRail Cloud section below for details on what is and is not included.
</Note>

## Two setup paths

There are two ways to get AgentRail running on your own infrastructure:

<Tabs>
  <Tab title="CLI-managed setup (recommended)">
    The CLI-managed path is the recommended way to self-host AgentRail. It handles routing configuration, provider state, and agent credentials through interactive setup commands.

    <Steps>
      <Step title="Install the CLI">
        ```bash theme={null}
        npm install -g @agentrail-core/cli
        ```
      </Step>

      <Step title="Run init">
        ```bash theme={null}
        agentrail init
        ```

        This writes local config to `~/.agentrail/`, creates operator bootstrap state, and can create your first agent profile interactively. Choose your routing mode (`rules_only` or `ai_assist`) and GitHub review policy when prompted.
      </Step>

      <Step title="Start the server">
        Keep this running in one terminal:

        ```bash theme={null}
        agentrail server start
        ```

        The server starts the AgentRail API, begins provider delivery for configured polling or webhooks, and keeps managed agents awake.
      </Step>

      <Step title="Create your first agent">
        In a second terminal, if `agentrail init` did not already create one:

        ```bash theme={null}
        agentrail agent create
        ```

        This creates scoped agent credentials, writes `~/.agentrail/agent.env`, and sets up starter routing for your repo.
      </Step>

      <Step title="Verify with doctor">
        ```bash theme={null}
        agentrail doctor
        ```

        `doctor` checks that the API is reachable, agent credentials work, routing state exists, and assigned work is visible. Do not consider setup complete until doctor passes.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Docker (server only)">
    The Docker path starts only the AgentRail API server in a container. It is useful for environments where you want to run the server process in isolation, but it does not handle agent credentials, routing setup, or provider state automatically.

    After the container is running, you still need to run `agentrail init` and `agentrail agent create` in a separate terminal to complete setup.

    See the [Docker setup guide](/docs/self-hosting/docker) for full instructions.
  </Tab>
</Tabs>

## AgentRail Cloud

AgentRail Cloud is the planned managed team and fleet operations layer. It is not yet generally available. When Cloud launches, it will add managed provider connectors, durable shared run history, SSO/RBAC, fleet routing, dashboards, support, and compliance features on top of the same lifecycle API you use today.

Self-hosting the source-available runtime proves the full agent lifecycle and gives you sovereignty over your data. It is an intentional adoption path, not a limitation to work around.