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

# Configure AgentRail routing, providers, and run policy

> Learn how to view and update your AgentRail config, manage repos, choose provider and routing modes, and tune managed run reclaim defaults.

After you run `agentrail init`, all local configuration lives under `~/.agentrail/`. You can inspect and update that configuration at any time using the `agentrail config` and `agentrail repo` commands — no need to edit files by hand.

## View and update config

Run `agentrail config show` to print your current configuration to the terminal:

```bash theme={null}
agentrail config show
```

To update the base URL your CLI points at, use `agentrail config set`:

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

You can also update the provider mode in the same command:

```bash theme={null}
agentrail config set --base-url http://127.0.0.1:3000 --provider-mode real
```

## Manage repos

AgentRail tracks which repositories agents are allowed to work in. Use the `repo` subcommands to add, list, or remove repos:

```bash theme={null}
agentrail repo list
agentrail repo add
agentrail repo remove --repo owner/repo-name
```

<Note>
  Routing fails closed if no repo is configured for the incoming task. Always verify that `agentrail repo list` shows the expected repository before running agents against it.
</Note>

## Provider modes

The `--provider-mode` flag controls how AgentRail interacts with external providers such as GitHub, CircleCI, and Linear.

| Mode       | Behavior                                                                                     |
| ---------- | -------------------------------------------------------------------------------------------- |
| `real`     | Uses live provider credentials. Enables actual PR creation, CI polling, and review feedback. |
| `disabled` | Disables provider calls. Useful for local development without live credentials.              |

Set the mode during init or update it later:

```bash theme={null}
agentrail config set --base-url http://127.0.0.1:3000 --provider-mode disabled
```

## Routing modes

AgentRail supports two routing modes, chosen during `agentrail init` or updated in `~/.agentrail/config.json`:

| Mode         | Behavior                                                                                                                                      |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `rules_only` | Routes tasks using deterministic rules only. Never calls a model. Best when your issues already carry labels, project tags, or type metadata. |
| `ai_assist`  | Uses a local runner (Codex, Claude Code, or Cursor) to route tasks to the right agents when rules alone are ambiguous.                        |

In `ai_assist` mode, AgentRail uses a local runner timeout of 180 seconds by default. If your runner is slow, raise `routing.classifier.timeoutMs` in `config.json` up to 600 seconds. Tasks that time out fall to triage.

## Runner policy presets

When you create or update an agent with `agentrail agent create` or `agentrail agent update`, you can select a runner policy preset using `--runner-policy`. Each preset controls how aggressively the agent is allowed to take actions:

| Preset             | Description                                                                      |
| ------------------ | -------------------------------------------------------------------------------- |
| `strict`           | Most restrictive. Requires confirmation for any consequential action.            |
| `balanced`         | Default. Allows routine actions automatically; pauses for high-impact decisions. |
| `advisory`         | Suggests actions but defers to the user for every step.                          |
| `external_sandbox` | For agents running inside an isolated external sandbox environment.              |

## Code review policy

The GitHub code review policy controls whether AgentRail waits for a PR approval before shipping. Set it during `agentrail init` or when connecting GitHub:

| Policy           | Behavior                                                                                        |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `github-rules`   | Follows GitHub's own branch protection and review signals. Default.                             |
| `always-require` | Always requires at least one approval for AgentRail-created PRs before shipping.                |
| `never-require`  | Ships once CI is green, regardless of review status. Explicit change requests still block ship. |

Pass this flag during init:

```bash theme={null}
agentrail init --code-review-policy always-require
```

## Managed run reclaim defaults

AgentRail keeps a durable run record for each managed local agent so it can avoid launching two agents on the same task at once. If a runner process disappears while a run is still marked `starting` or `running`, AgentRail reclaims that record after a conservative timeout and allows the task to run again.

<Note>
  AgentRail never reclaims `awaiting_user` runs. Those represent unresolved human action and must be resolved explicitly.
</Note>

The default thresholds are:

| Config key                              |   Default | Meaning                                                                                          |
| --------------------------------------- | --------: | ------------------------------------------------------------------------------------------------ |
| `managedRuns.startingStaleAfterMs`      |  `300000` | Reclaim a stuck launch after 5 minutes.                                                          |
| `managedRuns.runningStaleAfterMs`       | `5400000` | Reclaim a running agent only after 90 minutes.                                                   |
| `managedRuns.failureWindowMs`           | `3600000` | Count repeated runner failures within a 1-hour window.                                           |
| `managedRuns.maxInfrastructureFailures` |       `2` | Retry one abandoned run, then block for user action on the second recent infrastructure failure. |
| `managedRuns.supervisorRestartWindowMs` |   `60000` | Window for supervisor restart-loop detection.                                                    |
| `managedRuns.supervisorMaxRestarts`     |       `5` | Pause automatic restarts after more than 5 exits within the restart window.                      |

### Override with environment variables

All timeout values use seconds when set via environment variables:

```bash theme={null}
AGENTRAIL_MANAGED_RUN_STARTING_STALE_SECONDS=300
AGENTRAIL_MANAGED_RUN_RUNNING_STALE_SECONDS=5400
AGENTRAIL_MANAGED_RUN_FAILURE_WINDOW_SECONDS=3600
AGENTRAIL_MANAGED_RUN_MAX_INFRA_FAILURES=2
AGENTRAIL_LOCAL_RUNNER_RESTART_WINDOW_SECONDS=60
AGENTRAIL_LOCAL_RUNNER_MAX_RESTARTS=5
```

<Warning>
  When repeated infrastructure failures hit `maxInfrastructureFailures`, AgentRail blocks the task for user action instead of looping silently. Resolve the blocker with `agentrail task resolve-blocker` before restarting.
</Warning>