Local vs Cloud Execution

Understanding the differences between local and cloud execution modes in OpenSteer

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:

.env

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:

Boolean flag

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 configuration

CloudOptions:

• 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

Opensteer.from() - Local Only

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:

Session Creation

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:

Local CUA

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

Session Management

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

Action WebSocket

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

Use environment variables for mode selection

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.

Avoid local-only features in shared code

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

Commit .env.example but not .env

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.

Use cloud mode for CI/CD pipelines

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

Related

Launch Options

Complete API reference for launch() configuration

CUA Agents

Learn about Computer Use Agent mode