Instance Management

The instance management endpoints let you create, stop, and restart browser instances. Each instance is identified by a 0-based browser_id and can be configured independently with custom user agent, viewport, geolocation, locale, and proxy settings. Multiple instances can run concurrently inside the same container.

Use these endpoints to provision isolated browser sessions for automation, scraping, or testing workloads, and to recycle them when configuration changes are required.

---

GET /start

Create a new browser instance, or return metadata for an existing one identified by browser_id. The response includes the Chrome DevTools WebSocket endpoint (webSocketDebuggerUrl) when launched with useRemoteDebuggingPort: true.

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index).
chromiumVersion	query	string	No	Chromium/Chrome version selection. Full version (e.g. 136.0.7103.113), major version (e.g. 136), or channel tag (stable, beta, dev, canary). The server blocks until the browser is downloaded into BROWSERS_DIR. Only applies when browser=chromium.
fingerprintId	query	string	No	Base fingerprint profile id. Loads storage/config/fingerprints/<fingerprintId>.json and applies its context and launch defaults, then applies any request overrides.
useRemoteDebuggingPort	query	boolean	No	If true, launches Chromium with --remote-debugging-port and populates webSocketDebuggerUrl in metadata responses. Default: true.
remoteDebuggingPort	query	integer	No	Fixed DevTools port (only used when useRemoteDebuggingPort=true). If omitted, a free port is chosen.
remoteDebuggingAddress	query	string	No	Interface address for DevTools. Defaults to 127.0.0.1. Use 0.0.0.0 only in trusted environments.
extensions	query	string	No	Comma-separated list (or JSON array string) of absolute extension directory paths to load. Requires showBrowser=true.
extensionsDir	query	string	No	Directory containing extension subfolders to load. Requires showBrowser=true.
extensionsStoreIds	query	string	No	Comma-separated list (or JSON array string) of Chrome Web Store extension IDs to download and load. Requires showBrowser=true and browser=chromium.
proxyServer	query	string	No	Proxy server URL. Supports http://, https://, socks5://, or socks5h://. Example: socks5://127.0.0.1:9050.
proxyUsername	query	string	No	Proxy username (if required).
proxyPassword	query	string	No	Proxy password (if required).
proxyBypass	query	string	No	Comma-separated list of hosts that should bypass the proxy.
enableQuic	query	boolean	No	Enable QUIC/HTTP3 transport. Defaults to false (QUIC blocked). Default: false.
enableDnsOverHttps	query	boolean	No	Enable DNS-over-HTTPS for browser DNS resolution. Default: true.
dnsOverHttpsUrl	query	string	No	DoH resolver URL (HTTPS only). Default: "https://cloudflare-dns.com/dns-query".
display	query	integer | string	No	X display number or identifier for headful mode. Required when showBrowser=true and no DISPLAY environment variable is set on the server.
showBrowser	query	boolean	No	Whether to run the browser headful (visible). Default: true.
sessionName	query	string	No	Custom session name for identifying this browser instance.
timezoneId	query	string	No	IANA timezone identifier for browser geolocation.
locale	query	string	No	BCP 47 language tag for browser locale.
userAgent	query	string	No	User agent string to apply to the browser context.
viewport	query	string	No	Viewport configuration as JSON string. Example: {"width":1920,"height":1080,"deviceScaleFactor":1}. Pass null to disable fixed-viewport emulation.
noViewport	query	boolean	No	Set to true to disable fixed-viewport emulation (alias for viewport=null). Cannot be combined with a fixed viewport object. Default: false.
geolocation	query	string	No	Geolocation configuration as JSON string. Example: {"latitude":40.7128,"longitude":-74.0060,"accuracy":100}.
stealth	query	boolean	No	Launch Chromium in stealth mode using Patchright (anti-detection patches). Only applies to browser=chromium. Ignored for Firefox. Default: true.
iframe	query	boolean	No	Enable or disable the full-page display iframe on the root URL. When enabled (default), navigating to / serves an HTML page with an iframe pointing to the Hoody display URL. Default: true.
iframe_url	query	string	No	Explicit URL for the display iframe. If not provided, the URL is auto-detected from the Host header subdomain pattern.
maximize_new_windows	query	boolean	No	When true, the hoody-display client opens new top-level app windows maximized. Default: true.

Request Body

This endpoint does not accept a request body.

SDK and Examples

cURL

curl -X GET "https://proj-abc123-cnt-xyz789-browser-1.us-east-1.containers.hoody.icu/start?browser_id=0&timezoneId=America/New_York&locale=en-US&viewport=%7B%22width%22%3A1920%2C%22height%22%3A1080%2C%22deviceScaleFactor%22%3A1%7D"

SDK

await client.browser.instances.start({
  browser_id: "0",
  timezoneId: "America/New_York",
  locale: "en-US",
  viewport: '{"width":1920,"height":1080,"deviceScaleFactor":1}'
});

Response 200

{
  "engine": "patchright",
  "stealth": true,
  "headless": false,
  "chromiumBuildId": "136.0.7103.113",
  "chromiumExecutablePath": "/hoody/storage/hoody-browser/chrome/chrome/linux-136.0.7103.113/chrome-linux64/chrome",
  "browserExecutablePath": "/hoody/storage/hoody-browser/chrome/chrome/linux-136.0.7103.113/chrome-linux64/chrome",
  "fingerprintId": "default",
  "display": ":0",
  "iframe_url": "https://proj-abc123-cnt-xyz789-browser-1.us-east-1.containers.hoody.icu/?maximize_new_windows=true",
  "browser_id": "0",
  "browser_host": "browser-1",
  "browser_port": 9222,
  "sessionId": "b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "sessionName": "default",
  "timezoneId": "America/New_York",
  "locale": "en-US",
  "geolocation": {
    "latitude": 40.7128,
    "longitude": -74.006,
    "accuracy": 100
  },
  "viewport": {
    "width": 1920,
    "height": 1080,
    "deviceScaleFactor": 1
  },
  "viewportSource": "creation",
  "userAgentString": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.7103.113 Safari/537.36",
  "browserName": "chromium",
  "browserFullVersion": "136.0.7103.113",
  "operatingSystemName": "Linux",
  "operatingSystemPlatform": "Linux x86_64",
  "operatingSystemVersion": "6.5.0",
  "renderingEngine": "Blink",
  "renderingEngineVersion": "136.0.7103.113",
  "webSocketDebuggerUrl": "wss://proj-abc123-cnt-xyz789-cdp-1.us-east-1.containers.hoody.icu/devtools/browser/b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "devtoolsHttpUrl": "https://proj-abc123-cnt-xyz789-cdp-1.us-east-1.containers.hoody.icu/json/version",
  "devtoolsFrontendUrl": "https://proj-abc123-cnt-xyz789-cdp-1.us-east-1.containers.hoody.icu",
  "extensions": [],
  "useRemoteDebuggingPort": true,
  "remoteDebuggingPort": 9222,
  "remoteDebuggingAddress": "0.0.0.0",
  "quicDisabled": true,
  "http3Disabled": true,
  "dnsOverHttpsEnabled": true,
  "dnsOverHttpsUrl": "https://cloudflare-dns.com/dns-query",
  "tabs": [
    {
      "id": 1,
      "url": "https://example.com"
    }
  ]
}

400

{
  "error": "Invalid browser_id",
  "code": "INVALID_BROWSER_ID",
  "details": {
    "parameter": "browser_id",
    "constraint": "must be a non-negative integer string"
  }
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Validation Error	One or more request parameters failed validation.	Check the error details for the specific parameter and constraint that failed.
INVALID_BROWSER_ID	Invalid Browser ID	The browser_id value is invalid.	Provide a valid browser_id.

409

{
  "error": "Existing instance was launched with stealth=false; cannot restart with stealth=true",
  "code": "INSTANCE_BACKEND_MISMATCH",
  "details": {
    "browser_id": "0",
    "currentStealth": false,
    "requestedStealth": true
  }
}

Error Code	Title	Description	Resolution
INSTANCE_BACKEND_MISMATCH	Instance Backend Mismatch	The existing instance was launched with a different stealth mode/backend.	Stop the running instance first, then start again with the new stealth mode.

500

{
  "error": "Failed to launch browser process",
  "code": "INSTANCE_CREATE_FAILED",
  "details": {
    "reason": "spawn /hoody/storage/hoody-browser/chrome/chrome/linux-136.0.7103.113/chrome-linux64/chrome ENOENT"
  }
}

{
  "error": "Chrome binary not found and no chromiumVersion provided to trigger download",
  "code": "CHROME_NOT_FOUND",
  "details": {
    "expectedPath": "/hoody/storage/hoody-browser/chrome/chrome/linux-136.0.7103.113/chrome-linux64/chrome"
  }
}

Error Code	Title	Description	Resolution
INSTANCE_CREATE_FAILED	Instance Creation Failed	The browser instance could not be created.	Check server logs for details. Ensure sufficient system resources are available.
CHROME_NOT_FOUND	Chrome Not Found	The Chrome/Chromium binary was not found at the expected path.	Ensure Chrome is installed or provide a valid chromiumVersion parameter to trigger download.

Note

When connecting via Puppeteer or Playwright, prefer chromium.connectOverCDP("https://...-cdp-1/") over connecting directly to the WebSocket URL. The reverse proxy resolves the live debugger URL on demand and cold-starts the instance if needed.

---

GET /stop

Stop an active browser instance and release its resources. The child process is terminated and the browser_id can be reused for a fresh instance.

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index).

Request Body

This endpoint does not accept a request body.

SDK and Examples

cURL

curl -X GET "https://proj-abc123-cnt-xyz789-browser-1.us-east-1.containers.hoody.icu/stop?browser_id=0"

SDK

await client.browser.instances.stop({ browser_id: "0" });

Response 200

{
  "message": "Stopped",
  "meta": {
    "browser_id": "0",
    "sessionId": "b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
    "engine": "patchright",
    "stealth": true,
    "chromiumBuildId": "136.0.7103.113"
  }
}

404

{
  "error": "No browser instance found for browser_id=0",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "0"
  }
}

Error Code	Title	Description	Resolution
INSTANCE_NOT_FOUND	Instance Not Found	No browser instance exists for the specified browser_id.	Verify the browser_id value, or create a new instance using /start.

---

GET /restart

Stop and recreate a browser instance using the provided configuration. Accepts the same parameters as /start, plus additional options for browser engine selection, launch arguments, and user profile overrides.

Parameters

Name	In	Type	Required	Description
browser_id	query	string	Yes	Unique identifier for the browser instance (0-based index).
chromiumVersion	query	string	No	Chromium/Chrome version selection. Full version (e.g. 136.0.7103.113), major version (e.g. 136), or channel tag (stable, beta, dev, canary). The server blocks until the browser is downloaded into BROWSERS_DIR. Only applies when browser=chromium.
fingerprintId	query	string	No	Base fingerprint profile id. Loads storage/config/fingerprints/<fingerprintId>.json and applies its context and launch defaults, then applies any request overrides.
useRemoteDebuggingPort	query	boolean	No	If true, launches Chromium with --remote-debugging-port and populates webSocketDebuggerUrl in metadata responses. Default: true.
remoteDebuggingPort	query	integer	No	Fixed DevTools port (only used when useRemoteDebuggingPort=true). If omitted, a free port is chosen.
remoteDebuggingAddress	query	string	No	Interface address for DevTools. Defaults to 127.0.0.1. Use 0.0.0.0 only in trusted environments.
extensions	query	string	No	Comma-separated list (or JSON array string) of absolute extension directory paths to load. Requires showBrowser=true.
extensionsDir	query	string	No	Directory containing extension subfolders to load. Requires showBrowser=true.
extensionsStoreIds	query	string	No	Comma-separated list of Chrome Web Store extension IDs to download and load (Chromium only). Requires showBrowser=true and browser=chromium.
proxyServer	query	string	No	Proxy server URL (http, https, socks5, socks5h).
proxyUsername	query	string	No	Proxy username (if required).
proxyPassword	query	string	No	Proxy password (if required).
proxyBypass	query	string	No	Comma-separated list of hosts that should bypass the proxy.
enableQuic	query	boolean	No	Enable QUIC/HTTP3 transport. Defaults to false (QUIC blocked). Default: false.
enableDnsOverHttps	query	boolean	No	Enable DNS-over-HTTPS for browser DNS resolution. Default: true.
dnsOverHttpsUrl	query	string	No	DoH resolver URL (HTTPS only). Default: "https://cloudflare-dns.com/dns-query".
display	query	integer | string	No	X display number or identifier for headful mode. Required when showBrowser=true and no DISPLAY environment variable is set on the server.
showBrowser	query	boolean	No	Whether to run the browser headful (visible). Default: true.
sessionName	query	string	No	Custom session name for identifying this browser instance.
timezoneId	query	string	No	IANA timezone identifier for browser geolocation.
locale	query	string	No	BCP 47 language tag for browser locale.
userAgent	query	string	No	User agent string to apply to the browser context.
viewport	query	object	No	Viewport configuration as JSON string. Example: {"width":1920,"height":1080,"deviceScaleFactor":1}. Pass null to disable fixed-viewport emulation.
noViewport	query	boolean	No	Set to true to disable fixed-viewport emulation (alias for viewport=null). Cannot be combined with a fixed viewport object. Default: false.
geolocation	query	object	No	Geolocation configuration as JSON string. Example: {"latitude":40.7128,"longitude":-74.0060,"accuracy":100}.
launchArguments	query	array	No	Additional browser launch arguments (repeatable or JSON array).
browser	query	string	No	Browser engine to use (chromium or firefox). Default: "chromium".
firefoxVersion	query	string	No	Firefox version label (informational only). Playwright-managed Firefox builds are used by default. If omitted, a Playwright Firefox build is downloaded on demand.
firefoxExecutablePath	query	string	No	Absolute path to a custom Firefox executable (overrides download).
showDevtools	query	boolean	No	Whether to open DevTools on launch (Chromium only). Default: false.
userProfile	query	object	No	Optional user profile object (JSON string) for fingerprinting defaults.
stealth	query	boolean	No	Launch Chromium in stealth mode using Patchright (anti-detection patches). Only applies to browser=chromium. Ignored for Firefox. Default: true.
iframe	query	boolean	No	Enable or disable the full-page display iframe on the root URL. Default: true.
iframe_url	query	string	No	Explicit URL for the display iframe.
maximize_new_windows	query	boolean	No	When true, the hoody-display client opens new top-level app windows maximized. Default: true.

Request Body

This endpoint does not accept a request body.

SDK and Examples

cURL

curl -X GET "https://proj-abc123-cnt-xyz789-browser-1.us-east-1.containers.hoody.icu/restart?browser_id=0&stealth=true&chromiumVersion=stable"

SDK

await client.browser.instances.restart({
  browser_id: "0",
  stealth: true,
  chromiumVersion: "stable"
});

Response 200

{
  "message": "Restarted",
  "meta": {
    "browser_id": "0",
    "sessionId": "b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
    "engine": "patchright",
    "stealth": true,
    "chromiumBuildId": "136.0.7103.113"
  }
}

400

{
  "error": "Invalid viewport JSON",
  "code": "VALIDATION_ERROR",
  "details": {
    "parameter": "viewport",
    "constraint": "must be a valid JSON object or null"
  }
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Validation Error	One or more request parameters failed validation.	Check the error details for the specific parameter and constraint that failed.

404

{
  "error": "No browser instance found for browser_id=0",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "browser_id": "0"
  }
}

Error Code	Title	Description	Resolution
INSTANCE_NOT_FOUND	Instance Not Found	No browser instance exists for the specified browser_id.	Verify the browser_id value, or create a new instance using /start.

409

{
  "error": "Existing instance was launched with stealth=false; cannot restart with stealth=true",
  "code": "INSTANCE_BACKEND_MISMATCH",
  "details": {
    "browser_id": "0",
    "currentStealth": false,
    "requestedStealth": true
  }
}

Error Code	Title	Description	Resolution
INSTANCE_BACKEND_MISMATCH	Instance Backend Mismatch	The existing instance was launched with a different stealth mode/backend.	Stop the running instance first, then start again with the new stealth mode.

500

{
  "error": "Browser process exited unexpectedly during restart",
  "code": "RESTART_FAILED",
  "details": {
    "browser_id": "0",
    "exitCode": 1
  }
}

Error Code	Title	Description	Resolution
RESTART_FAILED	Restart Failed	The browser instance could not be restarted.	Check server logs for details. The instance may need to be manually stopped and recreated.

Caution

Changing the stealth mode of an existing instance (e.g. from stealth=false to stealth=true) returns INSTANCE_BACKEND_MISMATCH. Stop the instance first, then start a new one with the desired configuration.