AgentRail

AgentRail is a local-first control plane for coding agents. It gives agents one compact API for the project loop: issue intake, routing, assigned work, PR submission, CI, review feedback, and shipping.

The source-available repo is a self-managed single-instance runtime. It is built for local evaluation and self-hosting. The planned AgentRail Cloud product is the managed team/fleet layer for hosted connectors, shared run history, routing, wakes, SSO/RBAC, audit, dashboards, and reliability.

What Agents Get

• Assigned tasks with compact state and availableActions.
• Routing from GitHub or Linear issues to the right local agent.
• Retry-safe mutations through idempotency keys.
• CI and review summaries shaped for action instead of raw log replay.
• Real-time task events over SSE and webhooks.
• Local provider setup for GitHub, CircleCI, and Linear.

Quickstart

Prerequisites:

• Node.js 24 or newer.
• npm.
• Optional provider credentials if you want live GitHub, CircleCI, or Linear integration.

Install the CLI:

npm install -g @agentrail-core/cli

Initialize AgentRail:

agentrail init

You can also run the first command without a global install:

npx @agentrail-core/cli init

The interactive setup writes local config under ~/.agentrail, creates the local operator bootstrap, and can create your first local agent. It does not ask you to hand-write API keys or edit a seed task store.

Start the local API:

agentrail server start

In another terminal, verify setup:

agentrail doctor --agent-id agt_example

doctor is the success gate. It checks the local API, agent credentials, profile/routing state, and whether the selected agent can see assigned work.

Telemetry

AgentRail sends anonymous product telemetry by default to improve setup, provider reliability, and agent lifecycle behavior. Telemetry goes to PostHog EU Cloud and uses an anonymous install ID.

Telemetry does not send source code, issue text, PR diffs, prompts, terminal logs, environment variables, secrets, tokens, or raw provider payloads.

agentrail telemetry status
agentrail telemetry off
agentrail telemetry on

Connect Providers

Provider connections are optional and can be added after init.

agentrail provider connect github
agentrail provider connect circleci

# AgentRail will ask for the full CircleCI project slug, for example:
# circleci/<org-id>/<project-id>
agentrail provider connect linear

Interactive provider setup asks for secrets in hidden prompts and writes them to local env files. Non-interactive automation can still use environment variables such as GITHUB_TOKEN, CIRCLECI_TOKEN, LINEAR_API_KEY, and webhook secrets. provider connect finishes by running provider readiness, applying safe local setup fixes, and reporting any remaining account or repo settings AgentRail cannot change for you. provider test <provider> uses the same readiness check as provider doctor <provider>; it is not just a token check. GitHub setup also asks whether AgentRail should wait for code review before shipping PRs. The default follows GitHub's own review signals, but you can choose to always require an approval for AgentRail-created PRs or to skip approval waits once CI is green. CircleCI setup verifies project access, creates .circleci/config.yml when a starter config is safe, and configures how AgentRail will obtain pipelines for AgentRail branches. If automatic CircleCI branch builds are not available, AgentRail uses the CircleCI pipeline-run API when the token can access a pipeline definition.

Import a Linear issue into AgentRail after connecting Linear:

agentrail linear import ENG-123

Imported provider issues go through the routing engine. If routing is not configured, AgentRail fails closed instead of silently creating unassigned work.

Work With Agents

Create or update local agent profiles:

agentrail agent create
agentrail agent update --agent-id agt_example

Use a built-in role template, or install your own YAML-backed role template:

agentrail agent create --role-template frontend-ui
agentrail agent create --role-template-file ./agent-roles/payments-backend.yaml

Custom templates are validated and copied into ~/.agentrail/agent-role-templates/, so later agents can reuse them with --role-template <id>.

During agentrail init and agentrail repo add, AgentRail also creates an editable repo map under ~/.agentrail/repo-maps/<repo>.yaml. Role templates use repo-agnostic areas such as frontend_source, tests, and ci_configuration; the repo map translates those areas to the actual folders in your project. The starter map is generated deterministically. During interactive setup you can also let a local Codex, Claude Code, or Cursor runner propose a richer map; AgentRail validates the proposal, shows you the summary and warnings, and falls back to the starter map if the local runner is unavailable or uncertain.

When a managed agent starts work, AgentRail combines the selected role template with the repo map for that repository and passes a compact role brief to the runner. The brief points the agent at relevant repo areas and validation expectations, while AgentRail still owns lifecycle actions such as PR creation, CI watching, review handling, and shipping. If a repo map is missing or incomplete, AgentRail still runs the agent and includes a warning in the run context. Run agentrail doctor to check repo-map coverage.

Inspect local config and connected repos:

agentrail config show
agentrail repo list
agentrail provider list
agentrail provider status
agentrail provider doctor

Repair a task source if older imported data needs to be corrected:

agentrail task source repair --task-id tsk_... --file source-patch.json

Docker

For a server-only smoke run:

docker compose up --build

The API listens on http://127.0.0.1:3000 by default. CLI-assisted onboarding is still the recommended path for a useful local setup because it creates local agent, routing, and provider state.

Documentation

• Developer guide: local development, architecture, API contracts, SDK examples, and manual HTTP flows.
• SDK guide: how to use the TypeScript and Python clients against a local or hosted AgentRail API.
• Five-minute quick start: expanded onboarding notes and manual reference commands.
• Integration guide for Claude Code, Codex, and Cursor.
• Agent recipes.
• Cloud boundary.
• Task lifecycle OpenAPI.
• Intake routing OpenAPI.
• Intake routing architecture.

Development

Common repo commands:

git clone https://github.com/oxnw/agentrail.git
cd agentrail
npm install
npm link
npm run typecheck
npm test
npm run lint:openapi

The package exposes the agentrail binary:

agentrail --help

License

AgentRail is source-available software, not open source. See LICENSE.