> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therefrain.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# serve

> Start the Refrain API server for remote execution and Web Console.

## Synopsis

```bash theme={null}
npx @refrainai/cli serve
```

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.

<Note>
  The API server requires Team plan or higher for remote execution features.
</Note>

## Prerequisites

Before starting the server, ensure you have:

1. **PostgreSQL** — Database for runbooks, jobs, settings, and metering
2. **Redis** — Required for SSE real-time streaming and Pub/Sub
3. **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

<Steps>
  <Step title="Configure environment">
    Create a `.env` file with required variables:

    ```bash theme={null}
    DATABASE_URL="postgresql://user:pass@localhost:5432/refrain"
    REDIS_URL="redis://localhost:6379"
    BETTER_AUTH_SECRET="your-random-secret"
    ANTHROPIC_API_KEY="sk-ant-..."
    ```
  </Step>

  <Step title="Run database migrations">
    ```bash theme={null}
    npx @refrainai/cli db:migrate
    ```
  </Step>

  <Step title="Start the server">
    ```bash theme={null}
    npx @refrainai/cli serve
    ```
  </Step>
</Steps>

## 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                      |

See [SDK](/sdk/overview) for programmatic usage.