Skip to content
Hoody Documentation
Download Page (.md)

Instance Management

Section titled “Instance Management”

The Instance Management endpoints let you start, stop, and restart browser instances. Each instance is uniquely identified by a browser_id (0-based index), and multiple instances can run concurrently with different configurations. Use these endpoints to manage the full lifecycle of an isolated browser session, including custom fingerprints, proxies, extensions, and DevTools remote debugging.

GET /start

Section titled “GET /start”

Creates a new browser instance, or returns metadata for an existing one when the same browser_id is reused. This is the primary endpoint for explicitly creating browser instances.

The response includes the webSocketDebuggerUrl field, which provides the Chrome DevTools WebSocket endpoint for remote debugging (only populated when useRemoteDebuggingPort: true).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
browser_idquerystringYesUnique identifier for the browser instance (0-based index)
chromiumVersionquerystringNoChromium/Chrome version selection. Only applies when browser=chromium. Supports full version (136.0.7103.113), major version (136), or channel tag (stable, beta, dev, canary)
fingerprintIdquerystringNoBase fingerprint profile id. The server loads storage/config/fingerprints/<fingerprintId>.json and applies its context and launch defaults, then applies request overrides
useRemoteDebuggingPortquerybooleanNo (default: true)Launch Chromium with --remote-debugging-port and populate webSocketDebuggerUrl in metadata
remoteDebuggingPortqueryintegerNoFixed DevTools port. Only used when useRemoteDebuggingPort=true; otherwise a free port is chosen
remoteDebuggingAddressquerystringNoInterface address for DevTools. Defaults to 127.0.0.1. Use 0.0.0.0 only in trusted environments
extensionsquerystringNoComma-separated list (or JSON array string) of absolute extension directory paths. Requires showBrowser=true
extensionsDirquerystringNoDirectory containing extension subfolders. Each subfolder is treated as an extension. Requires showBrowser=true
extensionsStoreIdsquerystringNoComma-separated list (or JSON array string) of Chrome Web Store extension IDs to download and load. Requires showBrowser=true and browser=chromium
proxyServerquerystringNoProxy server URL. Supports http://, https://, socks5://, or socks5h://
proxyUsernamequerystringNoProxy username
proxyPasswordquerystringNoProxy password
proxyBypassquerystringNoComma-separated list of hosts that should bypass the proxy
enableQuicquerybooleanNo (default: false)Enable QUIC/HTTP3 transport. QUIC is blocked by default
enableDnsOverHttpsquerybooleanNo (default: true)Enable DNS-over-HTTPS for browser DNS resolution
dnsOverHttpsUrlquerystringNo (default: "https://cloudflare-dns.com/dns-query")DoH resolver URL (HTTPS only)
displayqueryinteger | stringNoX display number or identifier for headful mode. Required when showBrowser=true and no DISPLAY env var is set
showBrowserquerybooleanNo (default: true)Whether to run the browser headful (visible)
sessionNamequerystringNoCustom session name for identifying this browser instance
timezoneIdquerystringNoIANA timezone identifier for browser geolocation
localequerystringNoBCP 47 language tag for browser locale
userAgentquerystringNoUser agent string to apply to the browser context
viewportquerystringNoViewport configuration as JSON string. Example: {"width":1920,"height":1080,"deviceScaleFactor":1}
geolocationquerystringNoGeolocation configuration as JSON string. Example: {"latitude":40.7128,"longitude":-74.0060,"accuracy":100}
stealthquerybooleanNo (default: true)Launch Chromium in stealth mode using Patchright. Only applies to browser=chromium; ignored for Firefox
iframequerybooleanNo (default: true)Enable or disable the full-page display iframe on the root URL
iframe_urlquerystringNoExplicit URL for the display iframe. If omitted, the URL is auto-detected from the Host header subdomain pattern

Response

Section titled “Response”
{
  "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": "0.localhost",
  "browser_port": 9222,
  "sessionId": "b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "sessionName": "primary",
  "timezoneId": "America/New_York",
  "locale": "en-US",
  "geolocation": {
    "latitude": 40.7128,
    "longitude": -74.006,
    "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://example.com:35791/devtools/browser/b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "devtoolsHttpUrl": "http://example.com:35791/json/version",
  "devtoolsFrontendUrl": "https://abc123-def456-http-9222.containers.hoody.icu",
  "extensions": [],
  "useRemoteDebuggingPort": true,
  "remoteDebuggingPort": 35791,
  "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"
    }
  ]
}

SDK Usage

Section titled “SDK Usage”
const instance = await client.browser.instances.start({
  browser_id: "0",
  chromiumVersion: "136",
  timezoneId: "America/New_York",
  locale: "en-US",
  stealth: true,
});

GET /stop

Section titled “GET /stop”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
browser_idquerystringYesUnique identifier for the browser instance (0-based index)

Response

Section titled “Response”
{
  "message": "Stopped",
  "meta": {
    "engine": "playwright",
    "stealth": true,
    "headless": false,
    "browser_id": "0",
    "browser_host": "0.localhost",
    "browser_port": 9222,
    "sessionId": "b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
    "sessionName": "primary"
  }
}

SDK Usage

Section titled “SDK Usage”
const result = await client.browser.instances.stop({
  browser_id: "0",
});

GET /restart

Section titled “GET /restart”

Stops and recreates a browser instance using the provided configuration. Accepts the same parameters as /start, plus additional options for Firefox, custom launch arguments, and DevTools port configuration.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
browser_idquerystringYesUnique identifier for the browser instance (0-based index)
chromiumVersionquerystringNoChromium/Chrome version selection. Only applies when browser=chromium. Supports full version (136.0.7103.113), major version (136), or channel tag (stable, beta, dev, canary)
fingerprintIdquerystringNoBase fingerprint profile id. The server loads storage/config/fingerprints/<fingerprintId>.json and applies its context and launch defaults, then applies request overrides
useRemoteDebuggingPortquerybooleanNo (default: true)Launch Chromium with --remote-debugging-port and populate webSocketDebuggerUrl in metadata
remoteDebuggingPortqueryintegerNoFixed DevTools port. Only used when useRemoteDebuggingPort=true; otherwise a free port is chosen
remoteDebuggingAddressquerystringNoInterface address for DevTools. Defaults to 127.0.0.1. Use 0.0.0.0 only in trusted environments
extensionsquerystringNoComma-separated list (or JSON array string) of absolute extension directory paths. Requires showBrowser=true
extensionsDirquerystringNoDirectory containing extension subfolders. Each subfolder is treated as an extension. Requires showBrowser=true
extensionsStoreIdsquerystringNoComma-separated list (or JSON array string) of Chrome Web Store extension IDs. Requires showBrowser=true and browser=chromium
proxyServerquerystringNoProxy server URL (http, https, socks5, socks5h)
proxyUsernamequerystringNoProxy username
proxyPasswordquerystringNoProxy password
proxyBypassquerystringNoComma-separated list of hosts that should bypass the proxy
enableQuicquerybooleanNo (default: false)Enable QUIC/HTTP3 transport. QUIC is blocked by default
enableDnsOverHttpsquerybooleanNo (default: true)Enable DNS-over-HTTPS for browser DNS resolution
dnsOverHttpsUrlquerystringNo (default: "https://cloudflare-dns.com/dns-query")DoH resolver URL (HTTPS only)
displayqueryinteger | stringNoX display number or identifier for headful mode. Required when showBrowser=true and no DISPLAY env var is set
showBrowserquerybooleanNo (default: true)Whether to run the browser headful (visible)
sessionNamequerystringNoCustom session name for identifying this browser instance
timezoneIdquerystringNoIANA timezone identifier for browser geolocation
localequerystringNoBCP 47 language tag for browser locale
userAgentquerystringNoUser agent string to apply to the browser context
viewportqueryobjectNoViewport configuration. Example: {"width":1920,"height":1080,"deviceScaleFactor":1}
geolocationqueryobjectNoGeolocation configuration. Example: {"latitude":40.7128,"longitude":-74.0060,"accuracy":100}
launchArgumentsqueryarrayNoAdditional browser launch arguments (repeatable or JSON array)
browserquerystringNo (default: "chromium")Browser engine to use (chromium or firefox)
firefoxVersionquerystringNoFirefox version label (informational only). Playwright-managed Firefox builds are used by default
firefoxExecutablePathquerystringNoAbsolute path to a custom Firefox executable (overrides download)
showDevtoolsquerybooleanNo (default: false)Whether to open DevTools on launch (Chromium only)
userProfilequeryobjectNoOptional user profile object (JSON string) for fingerprinting defaults
stealthquerybooleanNo (default: true)Launch Chromium in stealth mode using Patchright. Only applies to browser=chromium; ignored for Firefox
iframequerybooleanNo (default: true)Enable or disable the full-page display iframe on the root URL
iframe_urlquerystringNoExplicit URL for the display iframe

Response

Section titled “Response”
{
  "message": "Restarted",
  "meta": {
    "engine": "playwright",
    "stealth": true,
    "headless": false,
    "browser_id": "0",
    "browser_host": "0.localhost",
    "browser_port": 9222,
    "sessionId": "b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
    "sessionName": "primary"
  }
}

SDK Usage

Section titled “SDK Usage”
const instance = await client.browser.instances.restart({
  browser_id: "0",
  chromiumVersion: "136",
  browser: "chromium",
  stealth: true,
  timezoneId: "America/New_York",
  locale: "en-US",
});