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.

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: 
agentrail config show
To update the base URL your CLI points at, use agentrail config set: 
agentrail config set --base-url http://127.0.0.1:3000
You can also update the provider mode in the same command: 
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: 
agentrail repo list
agentrail repo add
agentrail repo remove --repo owner/repo-name
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.

​
Provider modes

The --provider-mode flag controls how AgentRail interacts with external providers such as GitHub, CircleCI, and Linear.
ModeBehavior
realUses live provider credentials. Enables actual PR creation, CI polling, and review feedback.
disabledDisables provider calls. Useful for local development without live credentials.
Set the mode during init or update it later: 
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:
ModeBehavior
rules_onlyRoutes tasks using deterministic rules only. Never calls a model. Best when your issues already carry labels, project tags, or type metadata.
ai_assistUses 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:
PresetDescription
strictMost restrictive. Requires confirmation for any consequential action.
balancedDefault. Allows routine actions automatically; pauses for high-impact decisions.
advisorySuggests actions but defers to the user for every step.
external_sandboxFor 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:
PolicyBehavior
github-rulesFollows GitHub’s own branch protection and review signals. Default.
always-requireAlways requires at least one approval for AgentRail-created PRs before shipping.
never-requireShips once CI is green, regardless of review status. Explicit change requests still block ship.
Pass this flag during init: 
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.
AgentRail never reclaims awaiting_user runs. Those represent unresolved human action and must be resolved explicitly.
The default thresholds are:
Config keyDefaultMeaning
managedRuns.startingStaleAfterMs300000Reclaim a stuck launch after 5 minutes.
managedRuns.runningStaleAfterMs5400000Reclaim a running agent only after 90 minutes.
managedRuns.failureWindowMs3600000Count repeated runner failures within a 1-hour window.
managedRuns.maxInfrastructureFailures2Retry one abandoned run, then block for user action on the second recent infrastructure failure.
managedRuns.supervisorRestartWindowMs60000Window for supervisor restart-loop detection.
managedRuns.supervisorMaxRestarts5Pause 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: 
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
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.