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.