Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/steerlabs/opensteer/llms.txt

Use this file to discover all available pages before exploring further.

OpenSteer provides a unified API that works seamlessly in both local and cloud execution modes. By default, OpenSteer runs in local mode, executing browser automation directly on your machine. Cloud mode allows you to offload execution to remote infrastructure.

​
Default: Local Mode

Without any configuration, OpenSteer runs in local mode: 
import { Opensteer } from 'opensteer';

const opensteer = new Opensteer({ name: 'my-app' });

// Runs locally on your machine
await opensteer.launch();
await opensteer.goto('https://example.com');
Local mode characteristics:
  • Browser runs on your machine
  • Full access to filesystem (cookies, file uploads)
  • Uses local Playwright browser binaries
  • No network latency for browser commands
  • Free (no cloud API costs)

​
Enabling Cloud Mode

Enable cloud mode using environment variables or constructor options.

​
Environment Variables

Set these environment variables to enable cloud mode: 
OPENSTEER_MODE=cloud
OPENSTEER_API_KEY=ork_your_key_here
OPENSTEER_AUTH_SCHEME=api-key

​
Constructor Configuration

You can also configure cloud mode directly in code: 
import { Opensteer } from 'opensteer';

const opensteer = new Opensteer({
  name: 'my-app',
  cloud: true  // Enables cloud mode with env vars
});
Constructor cloud options override the OPENSTEER_MODE environment variable.

​
Configuration Options

​
Environment Variables

​
OPENSTEER_MODE
string
default:"local"
Execution mode: local or cloud
​
OPENSTEER_API_KEY
string
required
Your OpenSteer API key (required for cloud mode)
​
OPENSTEER_BASE_URL
string
default:"https://api.opensteer.com"
Override the default cloud host URL
​
OPENSTEER_AUTH_SCHEME
string
default:"api-key"
Authentication scheme: api-key or bearer
​
OPENSTEER_REMOTE_ANNOUNCE
string
default:"always"
Cloud announcement policy: always, off, or tty
  • always: Always announce cloud session URLs
  • off: Never announce
  • tty: Only announce when running in a TTY
​
OPENSTEER_DISABLE_DOTENV_AUTOLOAD
boolean
default:"false"
Disable automatic .env file loading

​
Constructor Options

​
cloud
boolean | CloudOptions
Enable cloud mode or provide detailed cloud configurationCloudOptions:
  • apiKey (string): API key for authentication
  • baseUrl (string): Custom cloud host URL
  • authScheme (‘api-key’ | ‘bearer’): Authentication scheme
  • announce (‘always’ | ‘off’ | ‘tty’): Announcement policy

​
Environment File Loading

OpenSteer automatically loads .env files in the following order:
  1. .env.<NODE_ENV>.local (e.g., .env.production.local)
  2. .env.local (skipped when NODE_ENV=test)
  3. .env.<NODE_ENV> (e.g., .env.production)
  4. .env
Files are loaded from your storage.rootDir (default: process.cwd()). Existing process.env values are not overwritten. 
// Disable auto-loading if needed
process.env.OPENSTEER_DISABLE_DOTENV_AUTOLOAD = 'true';

​
Key Differences

​
Local-Only Features

These features are only available in local mode:

Opensteer.from(page)

Wrap an existing Playwright page instance

uploadFile()

Upload files from local filesystem

exportCookies()

Export cookies to local JSON file

importCookies()

Import cookies from local JSON file
import { chromium } from 'playwright';
import { Opensteer } from 'opensteer';

const browser = await chromium.launch();
const page = await browser.newPage();

// Wrap existing page (local only)
const opensteer = Opensteer.from(page, { name: 'my-app' });
Attempting to use these features in cloud mode will result in an error.

​
Cloud Session Management

In cloud mode, OpenSteer manages remote browser sessions: 
import { Opensteer } from 'opensteer';

const opensteer = new Opensteer({
  name: 'my-app',
  cloud: true
});

// Creates cloud session
await opensteer.launch();

// Get cloud session details
const sessionId = opensteer.getCloudSessionId();
const sessionUrl = opensteer.getCloudSessionUrl();

console.log('Cloud session:', sessionUrl);
Cloud sessions include cloudSessionUrl for deep linking to remote browser instances.

​
CUA Agent Support

Computer Use Agent (CUA) mode is supported in both local and cloud execution: 
const opensteer = new Opensteer({
  model: 'openai/computer-use-preview'
});

await opensteer.launch();
const agent = opensteer.agent({ mode: 'cua' });

const result = await agent.execute({
  instruction: 'Go to Hacker News and open the top story',
  maxSteps: 20
});

​
Cloud API Contract

Cloud mode uses a strict v3 contract with the following endpoints:

​
Control API

POST /sessions
GET /sessions/:sessionId
DELETE /sessions/:sessionId

​
Session Creation

POST /sessions requires: 
{
  "cloudSessionContractVersion": "v3",
  "sourceType": "local-cloud",
  "clientSessionHint": "string",
  "localRunId": "string"
}
Response includes: 
{
  "cloudSession": {
    "id": "session_123",
    "status": "active"
  },
  "cloudSessionUrl": "https://app.opensteer.com/sessions/session_123"
}

​
WebSocket Endpoints

ws://api.opensteer.com/ws/action/:sessionId

​
Fail-Fast Behavior

Cloud mode is fail-fast and does not automatically fall back to local mode if cloud connectivity fails.
If cloud mode is configured but unavailable: 
const opensteer = new Opensteer({ cloud: true });

try {
  await opensteer.launch();
} catch (error) {
  // Error: Unable to connect to cloud service
  // Does NOT fall back to local mode
  console.error('Cloud session failed:', error);
}
To implement fallback behavior manually: 
let opensteer;

try {
  opensteer = new Opensteer({ cloud: true });
  await opensteer.launch();
} catch (error) {
  console.warn('Cloud unavailable, using local mode');
  opensteer = new Opensteer({ cloud: false });
  await opensteer.launch();
}

​
Best Practices

Keep your code mode-agnostic by using environment variables:
const opensteer = new Opensteer({
  name: 'my-app',
  // Mode determined by OPENSTEER_MODE env var
});
This allows switching between local and cloud without code changes.
If your code may run in cloud mode, avoid these features:
// Avoid in shared code
await opensteer.uploadFile({ ... });      // Local only
await opensteer.exportCookies('...');     // Local only
const o = Opensteer.from(page);           // Local only
Provide an example file for team members:
.env.example
OPENSTEER_MODE=cloud
OPENSTEER_API_KEY=ork_your_key_here
OPENSTEER_AUTH_SCHEME=api-key
Add .env to .gitignore to protect secrets.
Cloud mode is ideal for continuous integration:
GitHub Actions
- name: Run OpenSteer tests
  env:
    OPENSTEER_MODE: cloud
    OPENSTEER_API_KEY: ${{ secrets.OPENSTEER_API_KEY }}
  run: npm test

Launch Options

Complete API reference for launch() configuration

CUA Agents

Learn about Computer Use Agent mode

Build docs developers (and LLMs) love

Get started for freeTalk to us