Use Session - Orchestrator Documentation

Once your session is created, you can connect to it using VNC for visual access or Chrome DevTools Protocol (CDP) for programmatic automation. The connection details are provided directly in the session creation response.

Playwright Integration

Connect to your Orchestrator session using Playwright’s CDP connection:

const { chromium } = require('playwright');
require('dotenv').config();

async function automateWithPlaywright() {
  try {
    // Create session
    const sessionResponse = await fetch('https://api.orchestratorhq.com/api/sessions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.ORCH_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        session_name: 'Playwright Session',
        duration: '1h'
      })
    });

    const session = await sessionResponse.json();
    // Print session details
    console.log('Session Info:');
    console.log('  id:', session.id);
    console.log('  organization_id:', session.organization_id);
    console.log('  session_name:', session.session_name);
    console.log('  status:', session.status);
    console.log('  vnc_url:', session.vnc_url);
    console.log('  cdp_url:', session.cdp_url);
    console.log('  expires_at:', session.expires_at);

    // Use cdp_url from session creation response
    const cdpUrl = session.cdp_url || (session.access_urls && session.access_urls.cdp_url);
    if (!cdpUrl) {
      console.error('No cdp_url found in session response!');
      return;
    }

    // Connect to the browser using CDP (session is active when API responds)
    const browser = await chromium.connectOverCDP(cdpUrl);
    const context = browser.contexts()[0];
    const page = context.pages()[0];

    // Your automation code here
    await page.goto('https://example.com');
    console.log('Page title:', await page.title());
    
    // Take a screenshot
    await page.screenshot({ path: 'screenshot.png' });

    // Clean up
    await browser.close();

    // Stop the session
    await fetch(`https://api.orchestratorhq.com/api/sessions/${session.id}`, {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${process.env.ORCH_API_KEY}`
      }
    });

    console.log('Session stopped');

  } catch (error) {
    console.error('Error:', error);
  }
}

automateWithPlaywright();

Puppeteer Integration

Use Puppeteer to connect to your browser session:

const puppeteer = require('puppeteer-core');

async function automateWithPuppeteer() {
  try {
    // Create session
    const sessionResponse = await fetch('https://api.orchestratorhq.com/api/sessions', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer orch_your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        session_name: 'Puppeteer Session',
        duration: '30m'
      })
    });

    const session = await sessionResponse.json();
    // Print session details
    console.log('Session Info:');
    console.log('  id:', session.id);
    console.log('  organization_id:', session.organization_id);
    console.log('  session_name:', session.session_name);
    console.log('  status:', session.status);
    console.log('  vnc_url:', session.vnc_url);
    console.log('  cdp_url:', session.cdp_url);
    console.log('  expires_at:', session.expires_at);

    // Connect using browserWSEndpoint (session is active when API responds)
    const browser = await puppeteer.connect({
      browserWSEndpoint: session.cdp_url
    });

    const pages = await browser.pages();
    const page = pages[0];

    // Your automation code
    await page.goto('https://httpbin.org/user-agent');
    const content = await page.content();
    console.log('Page loaded successfully');

    // Take screenshot
    await page.screenshot({ path: 'puppeteer-screenshot.png' });

    await browser.disconnect();

    // Stop session
    await fetch(`https://api.orchestratorhq.com/api/sessions/${session.id}`, {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer orch_your_api_key_here'
      }
    });

  } catch (error) {
    console.error('Error:', error);
  }
}

automateWithPuppeteer();

Selenium Integration

Connect to your browser session using Selenium WebDriver:

import requests
import time
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.common.by import By

def automate_with_selenium():
    try:
        # Create session
        session_response = requests.post(
            'https://api.orchestratorhq.com/api/sessions',
            headers={
                'Authorization': 'Bearer orch_your_api_key_here',
                'Content-Type': 'application/json'
            },
            json={
                'session_name': 'Selenium Session',
                'duration': '45m'
            }
        )

        session = session_response.json()
        session_id = session['id']
        # Print session details
        print('Session Info:')
        print(f'  id: {session["id"]}')
        print(f'  organization_id: {session["organization_id"]}')
        print(f'  session_name: {session["session_name"]}')
        print(f'  status: {session["status"]}')
        print(f'  vnc_url: {session["vnc_url"]}')
        print(f'  cdp_url: {session["cdp_url"]}')
        print(f'  expires_at: {session["expires_at"]}')

        # Extract CDP URL and convert to Selenium format (session is active when API responds)
        cdp_url = session['cdp_url']
        # Convert ws://host:port/devtools/browser/id to http://host:port
        server_url = cdp_url.replace('ws://', 'http://').split('/devtools')[0]

        # Configure Chrome options for remote debugging
        chrome_options = Options()
        chrome_options.add_experimental_option("debuggerAddress", server_url.replace('http://', ''))

        # Connect to the remote browser
        driver = webdriver.Chrome(options=chrome_options)

        # Your automation code
        driver.get('https://example.com')
        print(f'Page title: {driver.title}')

        # Find and interact with elements
        # driver.find_element(By.TAG_NAME, 'h1')

        # Take screenshot
        driver.save_screenshot('selenium-screenshot.png')

        # Clean up
        driver.quit()

        # Stop session
        requests.delete(
            f'https://api.orchestratorhq.com/api/sessions/{session_id}',
            headers={'Authorization': 'Bearer orch_your_api_key_here'}
        )

        print('Session stopped')

    except Exception as error:
        print(f'Error: {error}')

if __name__ == '__main__':
    automate_with_selenium()

VNC Access

For visual debugging or manual interaction, you can connect to the session via VNC using the connection details from the session:

Web-based VNC

The easiest way to access VNC is through your browser using the session details page in the Orchestrator dashboard.

VNC Client Connection

You can also connect using any VNC client with the vnc_url and vnc_password from your session:

# Using vncviewer (Linux/macOS)
# Extract host and port from vnc_url: wss://browser-node-1.orchestratorhq.com:6080/websockify
vncviewer browser-node-1.orchestratorhq.com:6080

# When prompted, enter the vnc_password from the session response

Error Handling

Always handle potential errors when connecting to sessions:

async function safeSessionConnection(sessionId) {
  try {
    const sessionResponse = await fetch(`https://api.orchestratorhq.com/api/sessions/${sessionId}`, {
      headers: {
        'Authorization': 'Bearer orch_your_api_key_here'
      }
    });

    if (!sessionResponse.ok) {
      throw new Error(`HTTP ${sessionResponse.status}: ${sessionResponse.statusText}`);
    }

    const session = await sessionResponse.json();
    return session;

  } catch (error) {
    console.error('Failed to get session details:', error);
    throw error;
  }
}

Best Practices

Session Lifecycle

Always stop sessions when done to avoid unnecessary charges and free up resources.

Error Handling

Implement proper error handling for network issues and session state changes.

Connection Pooling

Reuse sessions for multiple operations instead of creating new ones for each task.

Monitoring

Monitor session status and handle transitions between states gracefully.

Next Steps

Manage Sessions

Learn how to monitor, extend, and stop your browser sessions

Integration Guides

Detailed guides for specific automation frameworks

Documentation

Integration Guides

API Reference

​Playwright Integration

​Puppeteer Integration

​Selenium Integration

​VNC Access

​Web-based VNC

​VNC Client Connection

​Error Handling

​Best Practices

Session Lifecycle

Error Handling

Connection Pooling

Monitoring

​Next Steps

Manage Sessions

Integration Guides

Playwright Integration

Puppeteer Integration

Selenium Integration

VNC Access

Web-based VNC

VNC Client Connection

Error Handling

Best Practices

Next Steps