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

# Local Execution

> Execute runbooks locally using the Refrain class.

## Refrain

The `Refrain` class runs runbooks in a local browser instance.

```typescript theme={null}
import { Refrain } from "@refrainai/sdk";

const client = new Refrain({
  ai: {
    modelId: "claude-sonnet-4-6",
    provider: "anthropic",
    apiKey: process.env.ANTHROPIC_API_KEY!,
  },
});
```

## Configuration

The constructor accepts an `RefrainConfig` object:

| Property        | Required | Default | Description                        |
| --------------- | :------: | ------- | ---------------------------------- |
| `ai`            |    Yes   | —       | AI model configuration (see below) |
| `headless`      |    No    | `true`  | Launch browser in headless mode    |
| `loggerFactory` |    No    | noop    | Custom logging implementation      |
| `debug`         |    No    | `false` | Enable debug logging               |
| `apiKey`        |    No    | —       | API key for plan features          |
| `locale`        |    No    | `"en"`  | UI language: `"en"` or `"ja"`      |
| `stealth`       |    No    | —       | Bot detection evasion (Pro+)       |
| `proxy`         |    No    | —       | HTTP proxy URL or config object    |

### AI model configuration

| Property         | Required | Description                                                                                    |
| ---------------- | :------: | ---------------------------------------------------------------------------------------------- |
| `modelId`        |    Yes   | Model identifier (e.g., `"claude-sonnet-4-6"`, `"gpt-4o"`)                                     |
| `provider`       |    Yes   | `anthropic` \| `openai` \| `openai-compatible` \| `google` \| `azure` \| `bedrock` \| `vertex` |
| `apiKey`         |    No    | API key for the provider                                                                       |
| `baseURL`        |    No    | Custom endpoint (for `openai-compatible`)                                                      |
| `modelOverrides` |    No    | Per-purpose model IDs (see below)                                                              |

#### Provider-specific properties

<Tabs>
  <Tab title="Azure">
    | Property            | Description         |
    | ------------------- | ------------------- |
    | `azureResourceName` | Azure resource name |
    | `azureApiVersion`   | Azure API version   |
  </Tab>

  <Tab title="Bedrock">
    | Property                 | Description                               |
    | ------------------------ | ----------------------------------------- |
    | `bedrockRegion`          | AWS region                                |
    | `bedrockAccessKeyId`     | AWS access key ID                         |
    | `bedrockSecretAccessKey` | AWS secret access key                     |
    | `bedrockSessionToken`    | AWS session token (temporary credentials) |
  </Tab>

  <Tab title="Vertex">
    | Property         | Description             |
    | ---------------- | ----------------------- |
    | `vertexProject`  | Google Cloud project ID |
    | `vertexLocation` | Google Cloud region     |
  </Tab>
</Tabs>

#### Model overrides

Override the model used for specific tasks (Business+ plan):

```typescript theme={null}
const client = new Refrain({
  ai: {
    modelId: "claude-sonnet-4-6",
    provider: "anthropic",
    apiKey: "sk-ant-...",
    modelOverrides: {
      selector: "claude-haiku-4-5-20251001",    // Fast model for selector resolution
      extraction: "claude-haiku-4-5-20251001",  // Fast model for data extraction
      review: "claude-sonnet-4-6",              // Sonnet for review
      vision: "claude-sonnet-4-6",              // Vision-capable model
    },
  },
});
```

| Purpose             | Description                        |
| ------------------- | ---------------------------------- |
| `exploration`       | Runbook generation                 |
| `exploration-light` | Routine exploration steps          |
| `selector`          | High-frequency selector resolution |
| `extraction`        | High-frequency data extraction     |
| `review`            | Review, patch, suggestions         |
| `fallback`          | Agent Fallback                     |
| `vision`            | Vision Fallback (screenshot-based) |

### Proxy configuration

```typescript theme={null}
// URL string
const client = new Refrain({
  ai: { ... },
  proxy: "http://user:pass@proxy.example.com:8080",
});

// Config object
const client = new Refrain({
  ai: { ... },
  proxy: {
    server: "http://proxy.example.com:8080",
    username: "user",
    password: "pass",
  },
});
```

## execute()

```typescript theme={null}
const report = await client.execute(runbook, options);
```

### ExecuteOptions

| Property               | Required | Default    | Description                             |
| ---------------------- | :------: | ---------- | --------------------------------------- |
| `contextMarkdown`      |    Yes   | —          | Supplementary context markdown          |
| `variables`            |    No    | —          | Template variable values                |
| `secrets`              |    No    | —          | Secret variables (masked in logs)       |
| `stepDelay`            |    No    | YAML value | Delay between steps (ms)                |
| `executionStrategy`    |    No    | —          | Custom retry strategy                   |
| `enableSelectorCache`  |    No    | `false`    | Persist successful selector resolutions |
| `enableAgentFallback`  |    No    | `false`    | AI alternative path exploration         |
| `enableVisionFallback` |    No    | `false`    | Screenshot-based resolution             |
| `outputDir`            |    No    | —          | Directory for downloads and exports     |
| `screenshotDir`        |    No    | —          | Directory to save screenshots           |
| `debugLogPath`         |    No    | —          | Path for debug log (JSONL)              |
| `runbookPath`          |    No    | —          | Runbook file path (used as cache key)   |
| `mergeDownloads`       |    No    | `false`    | Merge downloaded CSV files              |
| `jobTimeoutMs`         |    No    | plan value | Job timeout in milliseconds             |
| `skills`               |    No    | —          | Skill plugin names                      |
| `dataStore`            |    No    | —          | Memory data collection store            |

### ExecutionReport

The `execute()` method returns an `ExecutionReport`:

```typescript theme={null}
interface ExecutionReport {
  runbookTitle: string;
  startUrl: string;
  totalSteps: number;
  executed: number;
  succeeded: number;
  failed: number;
  skipped: number;
  aborted: boolean;
  steps: StepExecutionResult[];
  totalDurationMs: number;
  memoryCollections?: Record<string, number>;
  downloadedFiles?: string[];
  videoPaths?: string[];
  aiMetrics?: AIMetricsSummary;
}
```

See [Types](/sdk/types) for the full `StepExecutionResult` reference.

## loadRunbook()

Load and parse a YAML file:

```typescript theme={null}
import { loadRunbook } from "@refrainai/sdk";

const runbook = await loadRunbook("./runbooks/login-flow.yaml");
console.log(runbook.title, runbook.steps.length);
```

## dispose()

Clean up resources:

```typescript theme={null}
await client.dispose();
```

<Tip>
  Always call `dispose()` when you're done to ensure the browser process is properly terminated.
</Tip>