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

# Start the AgentRail API server with Docker Compose

> Start the AgentRail API server in a Docker container, then complete setup with the CLI to create agents, configure routing, and verify with doctor.

Docker lets you run the AgentRail API server as a container. This is a server-only path — it starts the API process but does not create agent credentials, configure routing, or set up providers. You complete those steps with the CLI after the container is running.

<Note>
  The CLI-managed path (`agentrail init` → `agentrail server start`) is recommended for most setups because it handles agent credentials, routing, and provider state automatically. Use Docker when you specifically want to run the server process in a container.
</Note>

## Start the server

From the root of the AgentRail repository, run:

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

The API starts and listens on `http://127.0.0.1:3000` by default. You should see output like:

```text theme={null}
Starting AgentRail API.
✓ AgentRail API ready at http://127.0.0.1:3000
```

Keep this terminal running.

## Complete setup with the CLI

With the container running, open a second terminal and complete the CLI setup steps:

<Steps>
  <Step title="Install the CLI">
    If you have not already installed the CLI globally:

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

  <Step title="Run init">
    Point init at the running container:

    ```bash theme={null}
    agentrail init --base-url http://127.0.0.1:3000
    ```

    This writes local config to `~/.agentrail/` and creates operator bootstrap state.
  </Step>

  <Step title="Create your first agent">
    ```bash theme={null}
    agentrail agent create
    ```

    The agent wizard creates scoped credentials, writes `~/.agentrail/agent.env`, and configures starter routing for your repo.
  </Step>

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

    Doctor checks that the API is reachable, your agent credentials are valid, routing state exists, and assigned work is visible. Do not treat setup as complete until doctor passes.
  </Step>
</Steps>

## Connect providers (optional)

After doctor passes, connect your providers to enable live issue intake, CI, and review:

```bash theme={null}
agentrail provider connect github
agentrail provider connect circleci
agentrail provider connect linear
```

Each command walks you through credential setup and ends with readiness checks.

<Tip>
  Run `agentrail provider doctor` after connecting providers to confirm they are correctly configured and ready for the agent lifecycle.
</Tip>

## Load agent credentials

Before starting a coding agent manually, source the agent env file:

```bash theme={null}
source ~/.agentrail/agent.env
cd /path/to/target-repo
codex
```

For managed local agents, `agentrail server start` handles this automatically. In the Docker path, your coding agent needs the env vars set manually or through whatever environment management your container setup uses.