Instance Management

The Instance Management endpoints control the lifecycle of isolated browser instances. Each instance is uniquely identified by a browser_id (a 0-based index) and runs as an independent child process with its own configuration, profile, and DevTools endpoint.

Use these endpoints to start a new instance (or retrieve an existing one), stop a running instance, or restart one with an updated configuration.

Create or retrieve a browser instance

`GET /start`

Creates a new browser instance or returns metadata for an existing one identified by browser_id. The response includes the webSocketDebuggerUrl field for Chrome DevTools remote debugging when 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 for the instance. This option applies only when `browser=chromium`. Supported formats: full version (`136.0.7103.113`), major version (`136`, mapped to a known stable patch for the current OS), or channel tag (`stable`, `beta`, `dev`, `canary`). The server will block until the required browser is downloaded into `BROWSERS_DIR`.
`fingerprintId`	query	string	No	Base fingerprint profile id. The server will load `storage/config/fingerprints/<fingerprintId>.json` and use its `context` and `launch` defaults, then apply any request overrides.
`useRemoteDebuggingPort`	query	boolean	No	If `true`, the child process will launch Chromium with `--remote-debugging-port` and will populate `webSocketDebuggerUrl` in metadata responses. Default: `true`
`remoteDebuggingPort`	query	integer	No	Optional 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. Extensions require `showBrowser=true` (headful mode) and will launch a persistent profile.
`extensionsDir`	query	string	No	Directory containing extension subfolders to load (each subfolder is treated as an extension). Extensions require `showBrowser=true` (headful mode) and will launch a persistent profile.
`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 works only with `browser=chromium`.
`proxyServer`	query	string	No	Proxy server for browser traffic. 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). Use `enableQuic=true` to re-enable QUIC. Default: `false`
`enableDnsOverHttps`	query	boolean	No	Enable DNS-over-HTTPS for browser DNS resolution. Defaults to `true`. Default: `true`
`dnsOverHttpsUrl`	query	string	No	DoH resolver URL (HTTPS only). Defaults to Cloudflare: `https://cloudflare-dns.com/dns-query`. 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). Defaults to `true`. 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}`
`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. Defaults to `true`. Bare `?stealth` is treated as `true`. 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.
`noViewport`	query	boolean	No	Set to `true` to disable fixed-viewport emulation (alias for `viewport=null`). The page then resizes with the browser window instead of being pinned to an emulated resolution. Cannot be combined with a fixed `viewport` object.

This endpoint takes no request body.

SDK Usage

const instance = await client.browser.instances.start({
  browser_id: "0",
  showBrowser: false,
  timezoneId: "America/New_York",
  locale: "en-US",
  viewport: JSON.stringify({ width: 1920, height: 1080, deviceScaleFactor: 1 }),
});

Responses

{
  "engine": "playwright",
  "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": null,
  "browser_id": "0",
  "browser_host": "127.0.0.1",
  "browser_port": 9222,
  "sessionId": "s_8d3c2b1f4e5a",
  "sessionName": "primary",
  "timezoneId": "America/New_York",
  "locale": "en-US",
  "geolocation": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "accuracy": 100
  },
  "viewport": {
    "width": 1920,
    "height": 1080,
    "deviceScaleFactor": 1
  },
  "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",
  "operatingSystemVersion": "5.15.0",
  "renderingEngine": "Blink",
  "renderingEngineVersion": "136.0.7103.113",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "devtoolsHttpUrl": "http://127.0.0.1:9222/json/version",
  "devtoolsFrontendUrl": null,
  "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": "about:blank"
    }
  ]
}

{
  "error": "Invalid parameter value",
  "code": "VALIDATION_ERROR",
  "details": {
    "parameter": "viewport",
    "reason": "must be a valid JSON object"
  }
}

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

{
  "error": "Instance was launched with stealth=true; start requested with stealth=false",
  "code": "INSTANCE_BACKEND_MISMATCH",
  "details": {
    "browser_id": "0",
    "existing": { "stealth": true, "engine": "patchright" },
    "requested": { "stealth": false, "engine": "playwright" }
  }
}

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

{
  "error": "Failed to create browser instance",
  "code": "INSTANCE_CREATE_FAILED",
  "details": {
    "browser_id": "0",
    "reason": "insufficient system resources"
  }
}

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

Stop a browser instance

`GET /stop`

Stops an active browser instance for the provided browser_id. This terminates the child process and releases its resources.

Parameters

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

This endpoint takes no request body.

SDK Usage

const result = await client.browser.instances.stop({
  browser_id: "0",
});

Responses

{
  "message": "Stopped",
  "meta": {
    "browser_id": "0",
    "engine": "playwright",
    "headless": false
  }
}

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

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

Restart a browser instance

`GET /restart`

Stops and recreates a browser instance using the provided configuration. Accepts the same parameters as /start, plus Chromium-specific options (launchArguments, showDevtools, userProfile) and Firefox options (firefoxVersion, firefoxExecutablePath).

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 for the instance. This option applies only when `browser=chromium`. Supported formats: full version (`136.0.7103.113`), major version (`136`, mapped to a known stable patch for the current OS), or channel tag (`stable`, `beta`, `dev`, `canary`). The server will block until the required browser is downloaded into `BROWSERS_DIR`.
`fingerprintId`	query	string	No	Base fingerprint profile id. The server will load `storage/config/fingerprints/<fingerprintId>.json` and use its `context` and `launch` defaults, then apply any request overrides.
`useRemoteDebuggingPort`	query	boolean	No	If `true`, the child process will launch Chromium with `--remote-debugging-port` and will populate `webSocketDebuggerUrl` in metadata responses. Default: `true`
`remoteDebuggingPort`	query	integer	No	Optional 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. Extensions require `showBrowser=true` (headful mode) and will launch a persistent profile.
`extensionsDir`	query	string	No	Directory containing extension subfolders to load (each subfolder is treated as an extension). Extensions require `showBrowser=true` (headful mode) and will launch a persistent profile.
`extensionsStoreIds`	query	string	No	Chrome Web Store extension IDs to download and load (Chromium only). Requires `showBrowser=true` and works only with `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). Use `enableQuic=true` to re-enable QUIC. Default: `false`
`enableDnsOverHttps`	query	boolean	No	Enable DNS-over-HTTPS for browser DNS resolution. Defaults to `true`. Default: `true`
`dnsOverHttpsUrl`	query	string	No	DoH resolver URL (HTTPS only). Defaults to Cloudflare: `https://cloudflare-dns.com/dns-query`. 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). Defaults to `true`. 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}`
`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. Defaults to `true`. Bare `?stealth` is treated as `true`. 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.
`noViewport`	query	boolean	No	Set to `true` to disable fixed-viewport emulation (alias for `viewport=null`). The page then resizes with the browser window instead of being pinned to an emulated resolution. Cannot be combined with a fixed `viewport` object.

This endpoint takes no request body.

SDK Usage

const result = await client.browser.instances.restart({
  browser_id: "0",
  chromiumVersion: "stable",
  stealth: true,
  showBrowser: false,
  timezoneId: "America/New_York",
  locale: "en-US",
});

Responses

{
  "message": "Restarted",
  "meta": {
    "browser_id": "0",
    "engine": "playwright",
    "stealth": true,
    "headless": true,
    "chromiumBuildId": "136.0.7103.113"
  }
}

{
  "error": "Invalid parameter value",
  "code": "VALIDATION_ERROR",
  "details": {
    "parameter": "browser",
    "reason": "must be one of: chromium, firefox"
  }
}

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

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

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

{
  "error": "Instance was launched with stealth=true; restart requested with stealth=false",
  "code": "INSTANCE_BACKEND_MISMATCH",
  "details": {
    "browser_id": "0",
    "existing": { "stealth": true, "engine": "patchright" },
    "requested": { "stealth": false, "engine": "playwright" }
  }
}

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

{
  "error": "Failed to restart browser instance",
  "code": "RESTART_FAILED",
  "details": {
    "browser_id": "0",
    "reason": "child process exited unexpectedly"
  }
}

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