browser_create_context

Create a new isolated browser context with its own cookies, storage, and optional proxy configuration. Each context acts as an independent browser session. Use this to create multiple isolated browsing sessions, configure proxy/Tor connections, load browser profiles with saved fingerprints, and enable/disable LLM features. Returns a context_id to use with other browser tools.

Usage Example

CURL

POST `/api/execute/browser_create_context`

curl -X POST \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{}' \
http://localhost:8080/api/execute/browser_create_context

Python SDK

import asyncio
from owl_browser import OwlBrowser, RemoteConfig

# Async usage
async with OwlBrowser(config) as browser:
    context = await browser.create_context()
    context_id = context["context_id"]
    await browser.create_context()

Node.js SDK

import { OwlBrowser } from '@olib-ai/owl-browser-sdk';

// Async usage
const ctx = await browser.createContext();
const contextId = ctx.context_id;
await browser.createContext();

Parameters

Optional

  • profile_path string: Path to a browser profile JSON file (or upload file via multipart/form-data). If the file exists, loads fingerprints, cookies, and settings. If not, creates a new profile and saves it to this path. Encrypted profiles (from browser_download_profile) are automatically detected and decrypted.

  • os enum: windows, macos, linux. Filter profiles by operating system. If set, only profiles matching this OS will be used. Options: 'windows', 'macos', 'linux'

  • gpu string: Filter profiles by GPU vendor/model. If set, only profiles with matching GPU will be used. Examples: 'nvidia', 'amd', 'intel'

  • screen_size enum: 1920x1080, 2560x1440, 3440x1440, 3840x2160, +3 more. Screen resolution for the browser context. Format: 'WIDTHxHEIGHT'. If not set, a random screen size is selected from the monitor catalog.

  • timezone string: Override browser timezone. IANA timezone format (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo'). If not set, falls back to: 1) proxy-detected timezone (if proxy configured with spoof_timezone), 2) VM profile timezone, 3) system default. This parameter works without proxy configuration.

  • resource_blocking boolean: Enable or disable resource blocking (ads, trackers, analytics). When enabled, blocks requests to known ad networks, trackers, and analytics services. Default: true (enabled)

  • agent_signature boolean: Enable Web Bot Auth (RFC 9421) request signing for this context. When enabled, every outgoing HTTP request is signed with Ed25519 Signature, Signature-Input, and Signature-Agent headers. Requires OWL_WBA_ENABLED=true and OWL_WBA_CONTACTS set. Default: false

  • proxy_type enum: http, https, socks4, socks5, +2 more. Type of proxy server to use. Options: 'http', 'https', 'socks4', 'socks5', 'socks5h', 'gae'. Use 'socks5h' for remote DNS resolution (recommended for privacy). Use 'gae' for private app proxy

  • proxy_host string: Proxy server hostname or IP address (e.g., '127.0.0.1' or 'proxy.example.com')

  • proxy_port string: Proxy server port number (e.g., 8080 for HTTP proxy, 9050 for Tor)

  • proxy_username string: Username for proxy authentication. Only required if the proxy server requires credentials

  • proxy_password string: Password for proxy authentication. Only required if the proxy server requires credentials

  • proxy_stealth boolean: Enable stealth mode to prevent proxy/VPN detection. Blocks WebRTC leaks and other detection vectors. Default: true when proxy is configured

  • proxy_ca_cert_path string: Path to custom CA certificate file (.pem, .crt, .cer) for SSL interception proxies. Required when using Charles Proxy, mitmproxy, or similar HTTPS inspection tools

  • proxy_ca_key_path string: Path to CA private key file for GAE/private app proxy MITM. Required for generating per-domain certificates when using 'gae' proxy type

  • proxy_trust_custom_ca boolean: Trust the custom CA certificate for SSL interception. Enable when using Charles Proxy, mitmproxy, or similar tools that intercept HTTPS traffic. Default: false

  • is_tor boolean: Explicitly mark this proxy as a Tor connection. Enables circuit isolation so each context gets a unique exit node IP. Auto-detected if proxy is localhost:9050 or localhost:9150 with socks5/socks5h

  • tor_control_port string: Tor control port for circuit isolation. Used to send SIGNAL NEWNYM to get a new exit node. Default: auto-detect (tries 9051 then 9151). Set to -1 to disable circuit isolation

  • tor_control_password string: Password for Tor control port authentication. Leave empty to use cookie authentication (default) or no auth

  • llm_enabled boolean: Enable or disable LLM features for this context. When enabled, allows using AI-powered tools like browser_query_page, browser_summarize_page, and browser_nla. Default: true

  • llm_use_builtin boolean: Use the built-in llama-server for LLM inference. When true, uses the bundled local model. Set to false to use an external LLM provider. Default: true

  • llm_endpoint string: External LLM API endpoint URL (e.g., 'https://api.openai.com/v1' for OpenAI). Only used when llm_use_builtin is false

  • llm_model string: External LLM model name (e.g., 'gpt-4-vision-preview' for OpenAI). Only used when llm_use_builtin is false

  • llm_api_key string: API key for the external LLM provider. Required when using external LLM endpoint

Response

Returns a JSON object with the operation result.

{
  "success": true,
  "result": <value>
}