Getting Started

Get Authorail running locally and connect your first AI agent in under five minutes.

Prerequisites

Before you begin, make sure you have the following installed:

Python 3.12+ — python.org/downloads
uv — fast Python package manager (docs.astral.sh/uv)
Claude Code — Anthropic’s CLI agent (docs.anthropic.com)

Clone and Install

Clone the repository and install dependencies with uv:

git clone https://github.com/authorail/authorail.git
cd authorail
uv sync

This creates a virtual environment and installs all required packages.

Configure Environment

Copy the example environment file and fill in your values:

cp .env.example .env

Open .env and configure the required variables:

Variable	Description
`DATABASE_URL`	SQLite or PostgreSQL connection string, e.g. `sqlite:///./dev.db`
`ADMIN_API_KEY`	Secret key for admin API access — generate with `python -c "import secrets; print(secrets.token_urlsafe(32))"`

Run Migrations

Apply the database schema:

uv run alembic upgrade head

This creates all tables needed for policies, audit events, quotas, and more.

Connect to Claude Code

Add Authorail as an MCP server in your Claude Code configuration. Create or update ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "authorail": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/authorail",
        "run", "python", "-m", "authorail.server"
      ],
      "env": {
        "DATABASE_URL": "sqlite:///./dev.db",
        "ADMIN_API_KEY": "your-admin-api-key"
      }
    }
  }
}

Replace /path/to/authorail with the absolute path to your cloned repository.

First Workflow

Once connected, try a basic spend request through Claude Code:

Create a policy — define spending limits for your agent via the admin API.
Submit a request — ask Claude Code to make a purchase that falls under your policy.
Check the audit trail — review the decision log to see how Authorail enforced your rules.

# Example: create a policy via the admin API
curl -X POST http://localhost:8000/api/policies \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-sandbox",
    "max_amount": 10.00,
    "currency": "USD",
    "action": "allow"
  }'

Next Steps

Deploy Guide — take Authorail to production
Pricing — compare plans and features
Blog — read about AI agent governance patterns