# Instance Management

**Page:** api/browser/instance-management

[Download Raw Markdown](./api/browser/instance-management.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## 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`

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`).


  The server **blocks** the request while the specified browser is downloaded into `BROWSERS_DIR` if the version is not already cached locally.


#### 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. Only applies when `browser=chromium`. Supports full version (`136.0.7103.113`), major version (`136`), or channel tag (`stable`, `beta`, `dev`, `canary`) |
| `fingerprintId` | query | string | No | Base fingerprint profile id. The server loads `storage/config/fingerprints/<fingerprintId>.json` and applies its `context` and `launch` defaults, then applies request overrides |
| `useRemoteDebuggingPort` | query | boolean | No (default: `true`) | Launch Chromium with `--remote-debugging-port` and populate `webSocketDebuggerUrl` in metadata |
| `remoteDebuggingPort` | query | integer | No | Fixed DevTools port. Only used when `useRemoteDebuggingPort=true`; otherwise 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. Requires `showBrowser=true` |
| `extensionsDir` | query | string | No | Directory containing extension subfolders. Each subfolder is treated as an extension. 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://` |
| `proxyUsername` | query | string | No | Proxy username |
| `proxyPassword` | query | string | No | Proxy password |
| `proxyBypass` | query | string | No | Comma-separated list of hosts that should bypass the proxy |
| `enableQuic` | query | boolean | No (default: `false`) | Enable QUIC/HTTP3 transport. QUIC is blocked by default |
| `enableDnsOverHttps` | query | boolean | No (default: `true`) | Enable DNS-over-HTTPS for browser DNS resolution |
| `dnsOverHttpsUrl` | query | string | No (default: `"https://cloudflare-dns.com/dns-query"`) | DoH resolver URL (HTTPS only) |
| `display` | query | integer \| string | No | X display number or identifier for headful mode. Required when `showBrowser=true` and no `DISPLAY` env var is set |
| `showBrowser` | query | boolean | No (default: `true`) | Whether to run the browser headful (visible) |
| `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 (default: `true`) | Launch Chromium in stealth mode using Patchright. Only applies to `browser=chromium`; ignored for Firefox |
| `iframe` | query | boolean | No (default: `true`) | Enable or disable the full-page display iframe on the root URL |
| `iframe_url` | query | string | No | Explicit URL for the display iframe. If omitted, the URL is auto-detected from the Host header subdomain pattern |

#### Response



```json
{
  "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"
    }
  ]
}
```


```json
{
  "error": "Invalid value for parameter `chromiumVersion`",
  "code": "VALIDATION_ERROR",
  "details": {
    "parameter": "chromiumVersion",
    "constraint": "must be a valid version string, major number, or channel tag"
  }
}
```

| 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` |


```json
{
  "error": "Existing instance was launched with stealth=false; cannot switch to stealth=true without restart",
  "code": "INSTANCE_BACKEND_MISMATCH",
  "details": {
    "browser_id": "0",
    "existingStealth": 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 |


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

| 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 |



#### SDK Usage

```ts
const instance = await client.browser.instances.start({
  browser_id: "0",
  chromiumVersion: "136",
  timezoneId: "America/New_York",
  locale: "en-US",
  stealth: true,
});
```

---

### `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) |

#### Response



```json
{
  "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"
  }
}
```


```json
{
  "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` |



#### SDK Usage

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

---

### `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.


  If the existing instance was launched with a different stealth backend, the call returns `409 INSTANCE_BACKEND_MISMATCH`. Stop the instance first, then start it again with the new stealth mode.


#### 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. Only applies when `browser=chromium`. Supports full version (`136.0.7103.113`), major version (`136`), or channel tag (`stable`, `beta`, `dev`, `canary`) |
| `fingerprintId` | query | string | No | Base fingerprint profile id. The server loads `storage/config/fingerprints/<fingerprintId>.json` and applies its `context` and `launch` defaults, then applies request overrides |
| `useRemoteDebuggingPort` | query | boolean | No (default: `true`) | Launch Chromium with `--remote-debugging-port` and populate `webSocketDebuggerUrl` in metadata |
| `remoteDebuggingPort` | query | integer | No | Fixed DevTools port. Only used when `useRemoteDebuggingPort=true`; otherwise 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. Requires `showBrowser=true` |
| `extensionsDir` | query | string | No | Directory containing extension subfolders. Each subfolder is treated as an extension. Requires `showBrowser=true` |
| `extensionsStoreIds` | query | string | No | Comma-separated list (or JSON array string) of Chrome Web Store extension IDs. Requires `showBrowser=true` and `browser=chromium` |
| `proxyServer` | query | string | No | Proxy server URL (http, https, socks5, socks5h) |
| `proxyUsername` | query | string | No | Proxy username |
| `proxyPassword` | query | string | No | Proxy password |
| `proxyBypass` | query | string | No | Comma-separated list of hosts that should bypass the proxy |
| `enableQuic` | query | boolean | No (default: `false`) | Enable QUIC/HTTP3 transport. QUIC is blocked by default |
| `enableDnsOverHttps` | query | boolean | No (default: `true`) | Enable DNS-over-HTTPS for browser DNS resolution |
| `dnsOverHttpsUrl` | query | string | No (default: `"https://cloudflare-dns.com/dns-query"`) | DoH resolver URL (HTTPS only) |
| `display` | query | integer \| string | No | X display number or identifier for headful mode. Required when `showBrowser=true` and no `DISPLAY` env var is set |
| `showBrowser` | query | boolean | No (default: `true`) | Whether to run the browser headful (visible) |
| `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. Example: `{"width":1920,"height":1080,"deviceScaleFactor":1}` |
| `geolocation` | query | object | No | Geolocation configuration. 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 (default: `"chromium"`) | Browser engine to use (`chromium` or `firefox`) |
| `firefoxVersion` | query | string | No | Firefox version label (informational only). Playwright-managed Firefox builds are used by default |
| `firefoxExecutablePath` | query | string | No | Absolute path to a custom Firefox executable (overrides download) |
| `showDevtools` | query | boolean | No (default: `false`) | Whether to open DevTools on launch (Chromium only) |
| `userProfile` | query | object | No | Optional user profile object (JSON string) for fingerprinting defaults |
| `stealth` | query | boolean | No (default: `true`) | Launch Chromium in stealth mode using Patchright. Only applies to `browser=chromium`; ignored for Firefox |
| `iframe` | query | boolean | No (default: `true`) | Enable or disable the full-page display iframe on the root URL |
| `iframe_url` | query | string | No | Explicit URL for the display iframe |

#### Response



```json
{
  "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"
  }
}
```


```json
{
  "error": "Invalid value for parameter `chromiumVersion`",
  "code": "VALIDATION_ERROR",
  "details": {
    "parameter": "chromiumVersion",
    "constraint": "must be a valid version string, major number, or channel tag"
  }
}
```

| 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 |


```json
{
  "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` |


```json
{
  "error": "Existing instance was launched with stealth=false; cannot switch to stealth=true without restart",
  "code": "INSTANCE_BACKEND_MISMATCH",
  "details": {
    "browser_id": "0",
    "existingStealth": 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 |


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

| 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 |



#### SDK Usage

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