Cloud Integration - OpenSteer

Overview

OpenSteer cloud mode provides managed browser infrastructure with the same API surface as local mode. Enable cloud execution with simple configuration - no code changes required.

Configuration

Environment Variables

The simplest way to enable cloud mode:

OPENSTEER_MODE=cloud
OPENSTEER_API_KEY=ork_your_key

Additional Options

OPENSTEER_MODE=cloud
OPENSTEER_API_KEY=ork_your_key
OPENSTEER_BASE_URL=https://api.opensteer.com  # Override default
OPENSTEER_AUTH_SCHEME=api-key                  # or 'bearer'
OPENSTEER_REMOTE_ANNOUNCE=always               # always, off, tty

Using .env Files

OpenSteer automatically loads .env files from your project root:

# .env
OPENSTEER_MODE=cloud
OPENSTEER_API_KEY=ork_your_key

Loading order:

.env.<NODE_ENV>.local
.env.local (skipped when NODE_ENV=test)
.env.<NODE_ENV>
.env

Existing process.env values are never overwritten.

Disable auto-loading with OPENSTEER_DISABLE_DOTENV_AUTOLOAD=true

Programmatic Configuration

Force cloud mode in code:

import { Opensteer } from 'opensteer'

const opensteer = new Opensteer({
  cloud: {
    apiKey: process.env.OPENSTEER_API_KEY,
    baseUrl: 'https://api.opensteer.com',
    authScheme: 'api-key',  // or 'bearer'
    announce: 'always'      // or 'off', 'tty'
  }
})

The cloud constructor option overrides OPENSTEER_MODE environment variable.

Authentication Schemes

API Key (Default)

const opensteer = new Opensteer({
  cloud: {
    apiKey: 'ork_your_key',
    authScheme: 'api-key'
  }
})

Bearer Token

const opensteer = new Opensteer({
  cloud: {
    apiKey: 'your_bearer_token',
    authScheme: 'bearer'
  }
})

Session Management

Creating Sessions

Sessions are created automatically when you launch:

const opensteer = new Opensteer({
  cloud: { apiKey: process.env.OPENSTEER_API_KEY }
})

await opensteer.launch()

Getting Session Information

Retrieve session ID and URL after launch:

await opensteer.launch()

const sessionId = opensteer.getCloudSessionId()
const sessionUrl = opensteer.getCloudSessionUrl()

console.log('Session ID:', sessionId)
console.log('Session URL:', sessionUrl)

Use the session URL to view browser sessions in the cloud dashboard.

Closing Sessions

Sessions are automatically closed when you call close():

try {
  await opensteer.launch()
  // ... automation steps
} finally {
  await opensteer.close()  // Closes cloud session
}

Announcement Policies

Control when cloud session URLs are announced:

Always (Default)

Always print session URLs:

const opensteer = new Opensteer({
  cloud: {
    apiKey: process.env.OPENSTEER_API_KEY,
    announce: 'always'
  }
})

TTY Only

Only print when running in a terminal:

const opensteer = new Opensteer({
  cloud: {
    apiKey: process.env.OPENSTEER_API_KEY,
    announce: 'tty'
  }
})

Off

Never print session URLs:

const opensteer = new Opensteer({
  cloud: {
    apiKey: process.env.OPENSTEER_API_KEY,
    announce: 'off'
  }
})

Cloud API Contract

Control API Endpoints

POST /sessions
Content-Type: application/json

{
  "cloudSessionContractVersion": "v3",
  "sourceType": "local-cloud",
  "clientSessionHint": "string",
  "localRunId": "string"
}

WebSocket Endpoints

/ws/action/:sessionId - Action execution
/ws/cdp/:sessionId - Chrome DevTools Protocol

Runtime Internal Endpoints

POST /internal/sessions
GET /internal/sessions/:sessionId
DELETE /internal/sessions/:sessionId
POST /internal/sessions/:sessionId/access

Local vs Cloud Feature Comparison

Browser Automation

✓

Fully supported in both local and cloud modes

Data Extraction

✓

Fully supported in both local and cloud modes

CUA Agent

✓

Fully supported in both local and cloud modes

Opensteer.from(page)

Local only

Not supported in cloud mode - requires local page reference

uploadFile()

Local only

Not supported in cloud mode - requires local filesystem access

exportCookies()

Local only

Not supported in cloud mode - requires local filesystem access

importCookies()

Local only

Not supported in cloud mode - requires local filesystem access

Complete Example

import { Opensteer } from 'opensteer'

async function run() {
  const opensteer = new Opensteer({
    name: 'cloud-scraper',
    cloud: {
      apiKey: process.env.OPENSTEER_API_KEY,
      announce: 'always'
    }
  })

  try {
    await opensteer.launch()
    
    // Get session info
    const sessionId = opensteer.getCloudSessionId()
    const sessionUrl = opensteer.getCloudSessionUrl()
    console.log('Cloud session:', sessionId)
    console.log('View at:', sessionUrl)

    // Automation works the same as local mode
    await opensteer.goto('https://example.com')
    
    await opensteer.snapshot({ mode: 'extraction' })
    
    const data = await opensteer.extract({
      description: 'page content',
      schema: {
        title: '',
        description: ''
      }
    })
    
    console.log('Extracted:', data)
  } finally {
    await opensteer.close()
  }
}

run().catch((err) => {
  console.error(err)
  process.exit(1)
})

Error Handling

Fail-Fast Behavior

Cloud mode is fail-fast and does not automatically fall back to local mode.

try {
  const opensteer = new Opensteer({
    cloud: { apiKey: 'invalid_key' }
  })
  await opensteer.launch()
} catch (error) {
  // Cloud authentication or connection failed
  console.error('Cloud mode failed:', error)
  // Does NOT fall back to local
}

Checking Cloud Status

const opensteer = new Opensteer({
  cloud: { apiKey: process.env.OPENSTEER_API_KEY }
})

try {
  await opensteer.launch()
  
  if (opensteer.getCloudSessionId()) {
    console.log('Running in cloud mode')
  }
} catch (error) {
  console.error('Failed to launch:', error)
}

Best Practices

Use environment variables for API keys

// Good - never commit API keys
const opensteer = new Opensteer({
  cloud: { apiKey: process.env.OPENSTEER_API_KEY }
})

// Bad - hardcoded credentials
const opensteer = new Opensteer({
  cloud: { apiKey: 'ork_your_key' }
})

Store session URLs for debugging

await opensteer.launch()

const sessionUrl = opensteer.getCloudSessionUrl()

// Log for debugging
console.log('Session URL:', sessionUrl)

// Or store in database for audit trail
await db.sessions.create({
  url: sessionUrl,
  timestamp: new Date()
})

Use same code for local and cloud

// Automatically switches based on OPENSTEER_MODE env
const opensteer = new Opensteer({ name: 'scraper' })

try {
  await opensteer.launch()
  // ... same automation code works in both modes
} finally {
  await opensteer.close()
}

Set appropriate announcement policy

// Development - always show URLs
const opensteer = new Opensteer({
  cloud: {
    apiKey: process.env.OPENSTEER_API_KEY,
    announce: 'always'
  }
})

// Production - suppress URLs in logs
const opensteer = new Opensteer({
  cloud: {
    apiKey: process.env.OPENSTEER_API_KEY,
    announce: 'off'
  }
})

Transitioning from Local to Cloud

1. Update Configuration

Add cloud credentials to .env:

# Before (local mode)
# No special config needed

# After (cloud mode)
OPENSTEER_MODE=cloud
OPENSTEER_API_KEY=ork_your_key

2. Remove Unsupported Features

Replace local-only methods:

// Before (local mode)
await opensteer.uploadFile({ description: 'file input', paths: ['./file.pdf'] })
await opensteer.exportCookies('./cookies.json')

// After (cloud mode)
// Use alternative approaches or handle in application layer

3. Test Thoroughly

Verify all automation works in cloud:

const opensteer = new Opensteer({
  cloud: { apiKey: process.env.OPENSTEER_API_KEY }
})

try {
  await opensteer.launch()
  
  // Run full test suite
  await runTests(opensteer)
  
  console.log('Cloud mode working correctly')
} finally {
  await opensteer.close()
}

Next Steps

Browser Automation

Learn core automation features

Data Extraction

Extract structured data in cloud mode

CUA Agent

Use Computer Use Agents in the cloud

AI Agents

Integrate with AI agent workflows

Get Started

Core Concepts

Guides

Documentation Index

​Overview

​Configuration

​Environment Variables

​Additional Options

​Using .env Files

​Programmatic Configuration

​Authentication Schemes

​API Key (Default)

​Bearer Token

​Session Management

​Creating Sessions

​Getting Session Information

​Closing Sessions

​Announcement Policies

​Always (Default)

​TTY Only

​Off

​Cloud API Contract

​Control API Endpoints

​WebSocket Endpoints

​Runtime Internal Endpoints

​Local vs Cloud Feature Comparison

​Complete Example

​Error Handling

​Fail-Fast Behavior

​Checking Cloud Status

​Best Practices

​Transitioning from Local to Cloud

​1. Update Configuration

​2. Remove Unsupported Features

​3. Test Thoroughly

​Next Steps

Browser Automation

Data Extraction

CUA Agent

AI Agents

Build docs developers (and LLMs) love

Overview

Configuration

Environment Variables

Additional Options

Using .env Files

Programmatic Configuration

Authentication Schemes

API Key (Default)

Bearer Token

Session Management

Creating Sessions

Getting Session Information

Closing Sessions

Announcement Policies

Always (Default)

TTY Only

Off

Cloud API Contract

Control API Endpoints

WebSocket Endpoints

Runtime Internal Endpoints

Local vs Cloud Feature Comparison

Complete Example

Error Handling

Fail-Fast Behavior

Checking Cloud Status

Best Practices

Transitioning from Local to Cloud

1. Update Configuration

2. Remove Unsupported Features

3. Test Thoroughly

Next Steps