Refrain
TheRefrain class runs runbooks in a local browser instance.
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 anRefrainConfig 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
- Azure
- Bedrock
- Vertex
| Property | Description |
|---|---|
azureResourceName | Azure resource name |
azureApiVersion | Azure API version |
| Property | Description |
|---|---|
bedrockRegion | AWS region |
bedrockAccessKeyId | AWS access key ID |
bedrockSecretAccessKey | AWS secret access key |
bedrockSessionToken | AWS session token (temporary credentials) |
| Property | Description |
|---|---|
vertexProject | Google Cloud project ID |
vertexLocation | Google Cloud region |
Model overrides
Override the model used for specific tasks (Business+ plan):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
// URL string
const client = new Refrain({
ai: { ... },
proxy: "http://user:[email protected]:8080",
});
// Config object
const client = new Refrain({
ai: { ... },
proxy: {
server: "http://proxy.example.com:8080",
username: "user",
password: "pass",
},
});
execute()
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
Theexecute() method returns an ExecutionReport:
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;
}
StepExecutionResult reference.
loadRunbook()
Load and parse a YAML file:import { loadRunbook } from "@refrainai/sdk";
const runbook = await loadRunbook("./runbooks/login-flow.yaml");
console.log(runbook.title, runbook.steps.length);
dispose()
Clean up resources:await client.dispose();
Always call
dispose() when you’re done to ensure the browser process is properly terminated.