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 uses bearer token authentication. When you create an agent with agentrail agent create, the CLI generates a scoped API key and writes it — along with your base URL — to ~/.agentrail/agent.env. You load that file before starting your coding agent, and it handles authentication automatically.

​
Where your credentials live

After running agentrail init and agentrail agent create, your credentials are stored in ~/.agentrail/agent.env. The file looks like this: 
AGENTRAIL_BASE_URL=http://127.0.0.1:3000
AGENTRAIL_API_KEY=ar_live_...
AGENTRAIL_BASE_URL is the address of your local AgentRail API. AGENTRAIL_API_KEY is the bearer token your agent uses to authenticate.
The AGENTRAIL_API_KEY value starts with ar_live_. This is the secret token you pass as the bearer credential. Do not confuse it with the key identifier, which starts with akey_ and is returned separately. The akey_ value is an ID, not a secret.

​
Load credentials before starting an agent

Source the env file in the terminal where you launch your coding agent: 
source ~/.agentrail/agent.env
cd /path/to/target-repo
codex
For managed local agents, agentrail server start loads these files automatically. Manual loading is only needed when you launch an agent outside the server-owned supervisor.

​
Pass the token in HTTP requests

When calling the AgentRail API directly, pass the token in the Authorization header: 
Authorization: Bearer ar_live_...
Example with curl: 
curl -s "$AGENTRAIL_BASE_URL/tasks/mine?status=in_progress&limit=1" \
  -H "Authorization: Bearer $AGENTRAIL_API_KEY"

​
API key scopes

Each agent key is scoped to only the operations it needs. When you create an agent, the wizard selects appropriate scopes. If you need to change permissions later, use agentrail agent update: 
agentrail agent update --agent-id agt_...
The available scopes are:
OperationRequired scope
List or read taskstasks:read
Submit task worktasks:write
Read CI summariesci:read
Read review feedbackreviews:read
Ship or merge workship:write
Stream task eventsevents:read
Manage event subscriptionswebhooks:read, webhooks:write
Sync Linear commentsproviders:write
Create or rotate keysauth:admin
Read key usageusage:read
Do not assign auth:admin to worker agents. This scope lets the key create and rotate other API keys. Reserve it for setup scripts and operator tooling only.

​
Auth errors

Your request is missing a token or is using the wrong value. The most common cause is passing the key identifier (akey_...) instead of the secret bearer token (ar_live_...).Check that AGENTRAIL_API_KEY is set and starts with ar_live_:
echo $AGENTRAIL_API_KEY
If the env var is empty, re-source your agent env file:
source ~/.agentrail/agent.env
Your token is valid but lacks the scope required for the route you called. Create a new key that includes the required scope, or update the agent’s permissions with:
agentrail agent update --agent-id agt_...
Each route in the API reference lists the minimum required scope.
Run agentrail doctor after any auth change. Doctor verifies that your agent key can authenticate and that /tasks/mine returns assigned work.