Deploy Guide

Take Authorail from local development to a production environment.

Architecture Overview

Authorail runs as two separate servers, each with a distinct role:

Server	Purpose	Audience
Admin Server	Policy management, audit logs, dashboard API	Human operators
Agent Server	Gateway for spend requests, policy enforcement	AI agents (MCP clients)

Separating the servers lets you apply different network rules, scaling, and access controls to each.

Admin Server

The admin server exposes the management API for creating policies, reviewing audit events, and configuring quotas.

uv run python -m authorail.admin_server

By default it listens on port 8000. Put it behind an authenticated reverse proxy (e.g. Caddy, nginx, or a cloud load balancer) so only authorized operators can reach it.

Agent Server (Gateway Mode)

The agent server handles incoming spend requests from AI agents. It evaluates each request against active policies and returns allow, deny, or approval-required decisions.

uv run python -m authorail.server

By default it listens on port 8001. This is the endpoint your MCP clients connect to in production.

Environment Variables

Configure both servers via environment variables or a .env file:

Variable	Required	Default	Description
DATABASE_URL	Yes	—	Database connection string (PostgreSQL recommended for production)
ADMIN_API_KEY	Yes	—	Secret key for admin API authentication
ORG_ID	No	default	Organization identifier for multi-tenant deployments
LOG_LEVEL	No	info	Logging verbosity: debug, info, warning, error
CORS_ORIGINS	No	*	Comma-separated list of allowed CORS origins
PORT	No	8000 / 8001	Override the default listening port

Production Database

For production, use PostgreSQL instead of SQLite:

DATABASE_URL=postgresql://user:password@host:5432/authorail

Run migrations after switching databases:

uv run alembic upgrade head

Deployment Options

Docker

docker build -t authorail .
docker run -d --env-file .env -p 8000:8000 authorail

Cloud Platforms

Authorail works with any platform that can run a Python process:

• Railway / Render — connect your repo and set environment variables in the dashboard.
• AWS ECS / GCP Cloud Run — containerize with the Dockerfile and deploy to your container orchestrator.
• VPS — run behind a process manager like systemd or supervisord.

Troubleshooting

Symptom	Likely Cause	Fix
Connection refused on port 8000	Admin server not running	Start with uv run python -m authorail.admin_server
401 Unauthorized on admin API	Wrong or missing API key	Check ADMIN_API_KEY matches your request header
no such table errors	Migrations not applied	Run uv run alembic upgrade head
Agent requests timing out	Agent server not reachable	Verify PORT and network/firewall rules
Stale policy changes	Caching in reverse proxy	Disable caching for API routes or reduce TTL

Next Steps

• Getting Started — initial setup and first workflow
• Pricing — compare plans for your team size
• Blog — learn about AI agent governance patterns