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.

AgentRail integrates with Cursor by launching it from an AgentRail-managed worktree or by letting agentrail server start open it. A Cursor rule keeps the agent focused on repository work and prevents it from calling lifecycle endpoints that belong to AgentRail.

​
How it works

Cursor should be launched by AgentRail or opened from an AgentRail-created worktree. AgentRail owns task assignment, CI observation, and lifecycle state. Cursor’s job is to edit code in the provided worktree, validate the change, and commit locally.
1

Initialize AgentRail

Run the interactive setup to create local config and your first agent profile.
agentrail init
For non-interactive environments:
agentrail init --mode server --repo /path/to/target-repo --yes
2

Create an agent profile

If agentrail init did not already create an agent:
agentrail agent create
3

Start the server

agentrail server start
agentrail server start reads agent env files from ~/.agentrail/agents/ and keeps configured agents awake.
4

Open Cursor from the worktree

Open the target repository that AgentRail has prepared. You can open it from the AgentRail-created worktree directly in Cursor, or let the server supervisor open it for you.
5

Verify with doctor

agentrail doctor
Confirm the API is reachable, credentials are valid, and assigned work is visible before starting any coding work.

​
Cursor rules

Add the following rule to your .cursorrules file or to Cursor’s Rules for AI setting. This keeps Cursor focused on the repository and prevents it from calling routes that AgentRail owns. 
This repository is worked through AgentRail. AgentRail has already assigned the
task and owns lifecycle state. If you need to inspect the current assignment,
use `agentrail run current` or `agentrail run actions`. Do not call broad
AgentRail task, CI, review, ship, rollback, provider, or operator endpoints.
Edit code in the provided worktree, validate the change, commit locally, write
the handoff file, and report with `agentrail agent report`.
Place this rule in .cursorrules at the root of the target repository so it applies automatically whenever Cursor opens that repo.

​
Run-scoped commands

Inside the AgentRail-managed context, Cursor may use only these run-scoped commands to inspect its current assignment: 
# Inspect the current assignment
agentrail run current

# Inspect available actions for this run
agentrail run actions
Do not configure Cursor to call broad AgentRail task, CI, review, ship, rollback, provider, or operator endpoints. Those routes are for external harnesses and are not part of the child agent contract.

​
Reporting completion

When Cursor finishes its work, it reports back to AgentRail: 
agentrail agent report \
  --status completed \
  --summary "short completion summary" \
  --handoff-file "$AGENTRAIL_HANDOFF_PATH"

​
What AgentRail owns

Cursor edits files, validates changes, and commits locally. AgentRail owns everything else:
  • Task assignment and lifecycle state
  • CI and review observation
  • Provider PR creation, shipping, and rollback
  • Relaunching Cursor only when CI or review feedback requires further code changes