Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Instance Management

Section titled “Instance Management”

The browser instance management endpoints let you create, restart, and stop isolated browser instances inside a Hoody container. Use /start to launch or fetch an instance by its browser_id, /restart to recycle an instance with new configuration, and /stop to terminate it and release resources. Each instance is identified by a 0-based browser_id and can run concurrently with other instances. Responses include Chrome DevTools metadata (such as webSocketDebuggerUrl) for remote debugging.

All three endpoints target the same browser service host. Replace {projectId}, {containerId}, and {server} with your project id, container id, and server node.

Create or retrieve instance

Section titled “Create or retrieve instance”

GET /start

Section titled “GET /start”

Creates a new browser instance or returns metadata for an existing one. 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 (when available with useRemoteDebuggingPort: true).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
browser_idquerystringYesUnique identifier for the browser instance (0-based index)
chromiumVersionquerystringNoChromium/Chrome version selection for the instance. Applies only when browser=chromium. Supported formats: full version 136.0.7103.113, major version 136, channel tag stable, beta, dev, canary. The server blocks until the required browser is downloaded into BROWSERS_DIR.
fingerprintIdquerystringNoBase fingerprint profile id. The server loads storage/config/fingerprints/<fingerprintId>.json and uses its context and launch defaults, then applies any request overrides.
useRemoteDebuggingPortquerybooleanNoIf true, the child process launches Chromium with --remote-debugging-port and populates webSocketDebuggerUrl in metadata responses. Default: true.
remoteDebuggingPortqueryintegerNoOptional fixed DevTools port (only used when useRemoteDebuggingPort=true). If omitted, 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 to load. Requires showBrowser=true (headful mode) and launches a persistent profile.
extensionsDirquerystringNoDirectory containing extension subfolders to load (each subfolder is treated as an extension). Requires showBrowser=true (headful mode).
extensionsStoreIdsquerystringNoComma-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.
proxyServerquerystringNoProxy server URL (http, https, socks5, socks5h). Example: socks5://127.0.0.1:9050.
proxyUsernamequerystringNoProxy username (if required)
proxyPasswordquerystringNoProxy password (if required)
proxyBypassquerystringNoComma-separated list of hosts that should bypass the proxy
enableQuicquerybooleanNoEnable QUIC/HTTP3 transport. Defaults to false (QUIC blocked). Default: false.
enableDnsOverHttpsquerybooleanNoEnable DNS-over-HTTPS for browser DNS resolution. Default: true.
dnsOverHttpsUrlquerystringNoDoH resolver URL (HTTPS only). Defaults to Cloudflare. Default: "https://cloudflare-dns.com/dns-query".
displayqueryinteger | stringNoX display number or identifier for headful mode. Required when showBrowser=true and no DISPLAY environment variable is set on the server.
showBrowserquerybooleanNoWhether to run the browser headful (visible). Default: true.
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}. Pass null to disable fixed-viewport emulation entirely — the page then follows the real browser window size.
noViewportquerybooleanNoSet to true to disable fixed-viewport emulation (alias for viewport=null). Cannot be combined with a fixed viewport object. Default: false.
geolocationquerystringNoGeolocation configuration as JSON string. Example: {"latitude":40.7128,"longitude":-74.0060,"accuracy":100}.
stealthquerybooleanNoLaunch Chromium in stealth mode using Patchright (anti-detection patches). Applies only to browser=chromium; ignored for Firefox. Default: true. Bare ?stealth is treated as true.
iframequerybooleanNoEnable 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_urlquerystringNoExplicit URL for the display iframe. If not provided, the URL is auto-detected from the Host header subdomain pattern.
maximize_new_windowsquerybooleanNoControl the maximize_new_windows flag stamped onto generated display URLs. When true, the hoody-display client opens new top-level app windows maximized. Default: true.

Request body

Section titled “Request body”

This endpoint takes no request body.

Response

Section titled “Response”
{
  "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://67e89abc123def456789abcd-890abcdef12345678901cdef-browser-display-1.node-us.containers.hoody.com",
  "browser_id": "0",
  "browser_host": "67e89abc123def456789abcd-890abcdef12345678901cdef-browser-1",
  "browser_port": 9222,
  "sessionId": "b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "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
  },
  "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": "ws://67e89abc123def456789abcd-890abcdef12345678901cdef-cdp-1.node-us.containers.hoody.com/devtools/browser/b6e7d6f4-8d1e-4f3a-9b2c-1d4e5f6g7h8i",
  "devtoolsHttpUrl": "http://67e89abc123def456789abcd-890abcdef12345678901cdef-cdp-1.node-us.containers.hoody.com/json/version",
  "devtoolsFrontendUrl": "https://67e89abc123def456789abcd-890abcdef12345678901cdef-cdp-1.node-us.containers.hoody.com",
  "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"
    }
  ]
}

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


await client.browser.instances.start({ browser_id: '0' });

Restart instance

Section titled “Restart instance”

GET /restart

Section titled “GET /restart”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
browser_idquerystringYesUnique identifier for the browser instance (0-based index)
chromiumVersionquerystringNoChromium/Chrome version selection for the instance. Applies only when browser=chromium. Supported formats: full version 136.0.7103.113, major version 136, channel tag stable, beta, dev, canary. The server blocks until the required browser is downloaded into BROWSERS_DIR.
fingerprintIdquerystringNoBase fingerprint profile id. The server loads storage/config/fingerprints/<fingerprintId>.json and uses its context and launch defaults, then applies any request overrides.
useRemoteDebuggingPortquerybooleanNoIf true, the child process launches Chromium with --remote-debugging-port and populates webSocketDebuggerUrl in metadata responses. Default: true.
remoteDebuggingPortqueryintegerNoOptional fixed DevTools port (only used when useRemoteDebuggingPort=true). If omitted, 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 to load. Requires showBrowser=true (headful mode) and launches a persistent profile.
extensionsDirquerystringNoDirectory containing extension subfolders to load (each subfolder is treated as an extension). Requires showBrowser=true (headful mode).
extensionsStoreIdsquerystringNoComma-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.
proxyServerquerystringNoProxy server URL (http, https, socks5, socks5h)
proxyUsernamequerystringNoProxy username (if required)
proxyPasswordquerystringNoProxy password (if required)
proxyBypassquerystringNoComma-separated list of hosts that should bypass the proxy
enableQuicquerybooleanNoEnable QUIC/HTTP3 transport. Defaults to false (QUIC blocked). Default: false.
enableDnsOverHttpsquerybooleanNoEnable DNS-over-HTTPS for browser DNS resolution. Default: true.
dnsOverHttpsUrlquerystringNoDoH resolver URL (HTTPS only). Defaults to Cloudflare. Default: "https://cloudflare-dns.com/dns-query".
displayqueryinteger | stringNoX display number or identifier for headful mode. Required when showBrowser=true and no DISPLAY environment variable is set on the server.
showBrowserquerybooleanNoWhether to run the browser headful (visible). Default: true.
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
viewportquerybrowser_ViewportNoViewport configuration as JSON string. Example: {"width":1920,"height":1080,"deviceScaleFactor":1}. Pass null to disable fixed-viewport emulation entirely — the page then follows the real browser window size.
noViewportquerybooleanNoSet to true to disable fixed-viewport emulation (alias for viewport=null). Cannot be combined with a fixed viewport object. Default: false.
geolocationquerybrowser_GeolocationNoGeolocation configuration as JSON string. Example: {"latitude":40.7128,"longitude":-74.0060,"accuracy":100}.
launchArgumentsqueryarrayNoAdditional browser launch arguments (repeatable or JSON array)
browserquerystringNoBrowser engine to use (chromium or firefox). Default: "chromium".
firefoxVersionquerystringNoFirefox version label (informational only). Playwright-managed Firefox builds are used by default. If omitted, a Playwright Firefox build is downloaded on demand.
firefoxExecutablePathquerystringNoAbsolute path to a custom Firefox executable (overrides download)
showDevtoolsquerybooleanNoWhether to open DevTools on launch (Chromium only). Default: false.
userProfilequeryobjectNoOptional user profile object (JSON string) for fingerprinting defaults
stealthquerybooleanNoLaunch Chromium in stealth mode using Patchright (anti-detection patches). Applies only to browser=chromium; ignored for Firefox. Default: true. Bare ?stealth is treated as true.
iframequerybooleanNoEnable or disable the full-page display iframe on the root URL. Default: true.
iframe_urlquerystringNoExplicit URL for the display iframe.
maximize_new_windowsquerybooleanNoControl the maximize_new_windows flag stamped onto the generated display URL. When true, the hoody-display client opens new top-level app windows maximized. Default: true.

Request body

Section titled “Request body”

This endpoint takes no request body.

Response

Section titled “Response”
{
  "message": "Restarted",
  "meta": {
    "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",
    "browser_id": "0",
    "browser_host": "67e89abc123def456789abcd-890abcdef12345678901cdef-browser-1",
    "browser_port": 9222,
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "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
    },
    "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": "ws://67e89abc123def456789abcd-890abcdef12345678901cdef-cdp-1.node-us.containers.hoody.com/devtools/browser/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "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"
      }
    ]
  }
}

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


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

Stop instance

Section titled “Stop instance”

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)

Request body

Section titled “Request body”

This endpoint takes no request body.

Response

Section titled “Response”
{
  "message": "Stopped",
  "meta": {
    "browser_id": "0",
    "engine": "patchright",
    "stealth": true,
    "headless": false,
    "chromiumBuildId": "136.0.7103.113",
    "browser_host": "67e89abc123def456789abcd-890abcdef12345678901cdef-browser-1",
    "browser_port": 9222,
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sessionName": "primary",
    "browserName": "chromium",
    "browserFullVersion": "136.0.7103.113",
    "tabs": [
      {
        "id": 1,
        "url": "about:blank"
      }
    ]
  }
}

SDK usage

Section titled “SDK usage”
import { HoodyClient } from 'hoody-sdk';


const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-browser-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });


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