Synopsis
Starts the HTTP API server that powers the Web Console and enables remote runbook execution. The server provides REST endpoints, SSE streaming, job scheduling via Inngest, and real-time updates via Redis Pub/Sub.
The API server requires Team plan or higher for remote execution features.
Prerequisites
Before starting the server, ensure you have:
- PostgreSQL — Database for runbooks, jobs, settings, and metering
- Redis — Required for SSE real-time streaming and Pub/Sub
- Inngest (optional) — Job queue for scheduled and background execution
Environment variables
Required
| Variable | Description |
|---|
DATABASE_URL | PostgreSQL connection string |
REDIS_URL | Redis connection string |
BETTER_AUTH_SECRET | Secret for authentication (session signing) |
Optional
| Variable | Default | Description |
|---|
PORT | 3000 | Server port |
INNGEST_EVENT_KEY | - | Inngest event key for job queue |
INNGEST_SIGNING_KEY | - | Inngest signing key |
REFRAIN_API_KEY | - | Default API key |
AI provider credentials
The server uses the same AI provider environment variables as the CLI:
| Variable | Description |
|---|
ANTHROPIC_API_KEY | Anthropic API key |
OPENAI_API_KEY | OpenAI API key |
GOOGLE_GENERATIVE_AI_API_KEY | Gemini API key |
AZURE_RESOURCE_NAME | Azure OpenAI resource name |
AZURE_API_KEY | Azure OpenAI API key |
AWS_REGION | AWS region for Bedrock |
AWS_ACCESS_KEY_ID | AWS access key for Bedrock |
AWS_SECRET_ACCESS_KEY | AWS secret key for Bedrock |
GOOGLE_VERTEX_PROJECT | Google Cloud project for Vertex |
GOOGLE_VERTEX_LOCATION | Google Cloud region for Vertex |
Setup
Configure environment
Create a .env file with required variables:DATABASE_URL="postgresql://user:pass@localhost:5432/refrain"
REDIS_URL="redis://localhost:6379"
BETTER_AUTH_SECRET="your-random-secret"
ANTHROPIC_API_KEY="sk-ant-..."
Run database migrations
npx @refrainai/cli db:migrate
API endpoints
The server exposes REST endpoints for managing runbooks, jobs, and settings. All endpoints require authentication via API key or session.
| Endpoint | Method | Description |
|---|
/api/runbooks | GET | List runbooks |
/api/runbooks | POST | Create a runbook |
/api/runbooks/:id | GET | Get runbook details |
/api/jobs | POST | Create a job (execute/generate/self-heal) |
/api/jobs | GET | List jobs |
/api/jobs/:id | GET | Get job details |
/api/jobs/:id/stream | GET | SSE stream for real-time updates |
/api/jobs/:id/approve | POST | Approve a waiting job |
/api/jobs/:id/reject | POST | Reject a waiting job |
/api/jobs/:id/cancel | POST | Cancel a running job |
