> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-docs-website-deploy-hook.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create a browser session > Create a new browser session from within an action. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/kernel/openapi.documented.yml post /browsers openapi: 3.1.0 info: title: Kernel API description: Developer tools and cloud infrastructure for AI agents to use web browsers version: 0.1.0 servers: - url: https://api.onkernel.com description: API Server security: - bearerAuth: [] tags: - name: Browsers description: Create and manage browser sessions. - name: Browser Computer Controls description: Control mouse, keyboard, and screen on the browser instance. - name: Browser Playwright description: Execute Playwright code against the browser instance. - name: Browser Filesystem description: Read, write, and manage files on the browser instance. - name: Browser Processes description: Execute and manage processes on the browser instance. - name: Browser Replays description: Record and manage browser session video replays. - name: Browser Logs description: Stream logs from the browser instance. - name: Browser Telemetry description: Stream live telemetry events from a browser session. - name: Profiles description: Create, list, retrieve, and delete browser profiles. - name: Proxies description: Create and manage proxy configurations for routing browser traffic. - name: Extensions description: Create, list, retrieve, and delete browser extensions. - name: Browser Pools description: Create and manage browser pools for acquiring and releasing browsers. - name: Managed Auth description: >- Create and manage auth connections for automated credential capture and login. - name: Credentials description: Create and manage credentials for authentication. - name: Credential Providers description: Configure external credential providers like 1Password. - name: Apps description: List applications and versions. - name: Deployments description: Create and manage app deployments and stream deployment events. - name: Invocations description: Invoke actions and stream or query invocation status and events. - name: Organization description: Read and manage organization-level limits. - name: Projects description: Create and manage projects for resource isolation within an organization. - name: API Keys description: Create and manage API keys for organization and project-scoped access. - name: Audit Logs description: Read audit log records for the authenticated organization. paths: /browsers: post: tags: - Browsers summary: Create a browser session description: Create a new browser session from within an action. operationId: postBrowsers requestBody: content: application/json: schema: $ref: '#/components/schemas/BrowserRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Browser' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' '529': $ref: '#/components/responses/CapacityExhausted' security: - bearerAuth: [] x-codeSamples: - lang: JavaScript source: |- import Kernel from '@onkernel/sdk'; const client = new Kernel({ apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted }); const browser = await client.browsers.create(); console.log(browser.session_id); - lang: Python source: |- import os from kernel import Kernel client = Kernel( api_key=os.environ.get("KERNEL_API_KEY"), # This is the default and can be omitted ) browser = client.browsers.create() print(browser.session_id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tbrowser, err := client.Browsers.New(context.TODO(), kernel.BrowserNewParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browser.SessionID)\n}\n" components: schemas: BrowserRequest: type: object description: | Parameters for creating a browser session. properties: invocation_id: type: string description: action invocation ID example: rr33xuugxj9h0bkf1rdt2bet name: type: string description: > Optional human-readable name for the browser session, used to find it later in the dashboard. Must be unique among active sessions within the project. Can be changed later via PATCH /browsers/{id_or_name}. minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]{1,255}$ example: checkout-flow-1 tags: $ref: '#/components/schemas/Tags' description: > Optional user-defined key-value tags for the browser session, used to find and group sessions later. Can be changed later via PATCH /browsers/{id_or_name}. Up to 50 pairs. stealth: type: boolean description: >- If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms. example: true headless: type: boolean description: >- If true, launches the browser using a headless image (no VNC/GUI). Defaults to false. example: false gpu: type: boolean description: >- If true, enables GPU acceleration for the browser session. Requires Start-Up or Enterprise plan and headless=false. example: false timeout_seconds: type: integer description: >- The number of seconds of inactivity before the browser session is terminated. Activity includes CDP connections and live view connections. Defaults to 60 seconds. Minimum allowed is 10 seconds. Maximum allowed is 259200 (72 hours). We check for inactivity every 5 seconds, so the actual timeout behavior you will see is +/- 5 seconds around the specified value. minimum: 10 maximum: 259200 profile: $ref: '#/components/schemas/BrowserProfile' extensions: type: array description: >- List of browser extensions to load into the session. Provide each by id or name. maxItems: 20 items: $ref: '#/components/schemas/BrowserExtension' proxy_id: type: string description: >- Optional proxy to associate to the browser session. Must reference a proxy in the same project as the browser session. viewport: $ref: '#/components/schemas/BrowserViewport' kiosk_mode: type: boolean description: >- If true, launches the browser in kiosk mode to hide address bar and tabs in live view. example: true start_url: type: string description: >- Optional URL to open when the browser session is created. Navigation is best-effort, so navigation failures do not prevent the session from being created. example: https://example.com chrome_policy: type: object additionalProperties: true description: > Custom Chrome enterprise policy overrides applied to this browser session. Keys are Chrome enterprise policy names; values must match their expected types. Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See https://chromeenterprise.google/policies/ telemetry: $ref: '#/components/schemas/BrowserTelemetryRequestConfig' nullable: true description: > Telemetry configuration for the browser session. Set enabled to true to start capture using VM defaults, or provide browser category settings. If omitted, null, set to an empty object ({}), set to enabled: false without browser category settings, or all four categories are explicitly disabled, capture is not started. required: [] Browser: type: object properties: created_at: type: string format: date-time description: When the browser session was created. cdp_ws_url: type: string description: >- Websocket URL for Chrome DevTools Protocol connections to the browser session example: >- wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/cdp?jwt=eyJ0eXAi... webdriver_ws_url: type: string description: Websocket URL for WebDriver BiDi connections to the browser session example: >- wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/webdriver/session?jwt=eyJ0eXAi... browser_live_view_url: type: string description: >- Remote URL for live viewing the browser session. Only available for non-headless browsers. example: >- https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/live?jwt=eyJ0eXAi... base_url: type: string description: Metro-API HTTP base URL for this browser session. example: https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/kernel headless: type: boolean description: Whether the browser session is running in headless mode. example: false stealth: type: boolean description: Whether the browser session is running in stealth mode. example: false gpu: type: boolean description: >- Whether GPU acceleration is enabled for the browser session (only supported for headful sessions). example: false session_id: type: string description: Unique identifier for the browser session example: htzv5orfit78e1m2biiifpbv name: type: string description: >- Human-readable name of the browser session, if one was set at creation. example: checkout-flow-1 timeout_seconds: type: integer description: >- The number of seconds of inactivity before the browser session is terminated. profile: $ref: '#/components/schemas/Profile' proxy_id: type: string description: ID of the proxy associated with this browser session, if any. pool: $ref: '#/components/schemas/BrowserPoolRef' viewport: $ref: '#/components/schemas/BrowserViewport' kiosk_mode: type: boolean description: Whether the browser session is running in kiosk mode. example: false start_url: type: string description: >- URL the session was asked to navigate to on creation, if any. Recorded for debugging. Navigation is fire-and-forget — the URL is dispatched to the browser without waiting for it to load, and any errors (DNS failure, bad status, timeout) are silently dropped. Captures what was requested, not what the browser actually loaded. example: https://example.com chrome_policy: type: object additionalProperties: true description: > Custom Chrome enterprise policy overrides that were applied to this browser session, if any. Echoed back for verification. Keys are Chrome enterprise policy names. tags: $ref: '#/components/schemas/Tags' description: >- User-defined key-value tags that were set on this browser session, if any. Echoed back when present. deleted_at: type: string format: date-time description: >- When the browser session was soft-deleted. Only present for deleted sessions. usage: $ref: '#/components/schemas/BrowserUsage' telemetry: $ref: '#/components/schemas/BrowserTelemetryConfig' nullable: true description: Active telemetry configuration for the session, if any. required: - created_at - cdp_ws_url - webdriver_ws_url - session_id - stealth - headless - timeout_seconds Tags: type: object maxProperties: 50 description: User-defined key-value tags. propertyNames: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9 _.:/=+@-]+$ additionalProperties: type: string minLength: 0 maxLength: 256 pattern: ^[A-Za-z0-9 _.:/=+@-]*$ example: team: backend env: staging BrowserProfile: type: object description: > Profile selection for the browser session. Provide either id or name. If specified, the matching profile will be loaded into the browser session. Profiles must be created beforehand. properties: id: type: string description: Profile ID to load for this browser session name: type: string minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]{1,255}$ description: >- Profile name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens. save_changes: type: boolean description: >- If true, save changes made during the session back to the profile when the session ends. default: false oneOf: - required: - id - required: - name BrowserExtension: type: object description: > Extension selection for the browser session. Provide either id or name of an extension uploaded to Kernel. properties: id: type: string description: Extension ID to load for this browser session name: type: string minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]{1,255}$ description: >- Extension name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens. oneOf: - required: - id - required: - name BrowserViewport: type: object description: > Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). For GPU images, the default is 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60. For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10: 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep bandwidth reasonable). properties: width: type: integer description: Browser window width in pixels. Any positive integer is accepted. minimum: 1 example: 1280 height: type: integer description: Browser window height in pixels. Any positive integer is accepted. minimum: 1 example: 800 refresh_rate: type: integer description: >- Display refresh rate in Hz. Any positive integer is accepted; if omitted, automatically determined from width and height. minimum: 1 example: 60 required: - width - height BrowserTelemetryRequestConfig: type: object description: Telemetry request configuration for a browser session. properties: enabled: type: boolean description: >- Request shortcut for browser telemetry capture. True enables capture using the default category set unless browser category settings are provided. False stops capture on update and starts no capture on create. enabled=false cannot be combined with browser category settings. browser: $ref: '#/components/schemas/BrowserTelemetryCategoriesConfig' description: >- Per-category capture flags. Selection is opt-in: only the categories set to enabled=true are captured; anything omitted is off. If enabled is true and browser is omitted or empty, the default category set is used. A browser config that enables nothing stops capture on update and starts no capture on create. Profile: type: object description: Browser profile metadata. properties: id: type: string description: Unique identifier for the profile name: type: string nullable: true description: Optional, easier-to-reference name for the profile created_at: type: string format: date-time description: Timestamp when the profile was created updated_at: type: string format: date-time description: Timestamp when the profile was last updated last_used_at: type: string format: date-time description: Timestamp when the profile was last used required: - id - created_at BrowserPoolRef: type: object description: Browser pool this session was acquired from, if any. properties: id: type: string description: Browser pool ID name: type: string description: Browser pool name, if set required: - id BrowserUsage: type: object description: Session usage metrics. properties: uptime_ms: type: integer description: Time in milliseconds the session was actively running. required: - uptime_ms BrowserTelemetryConfig: type: object description: Active telemetry configuration for a browser session. properties: browser: $ref: '#/components/schemas/BrowserTelemetryCategoriesConfig' description: Per-category enable/disable flags. Error: type: object required: - code - message properties: code: type: string description: Application-specific error code (machine-readable) example: bad_request message: type: string description: Human-readable error description for debugging example: 'Missing required field: app_name' details: type: array description: Additional error details (for multiple errors) items: $ref: '#/components/schemas/ErrorDetail' inner_error: $ref: '#/components/schemas/ErrorDetail' BrowserTelemetryCategoriesConfig: type: object description: >- Per-category telemetry capture settings. Selection is opt-in: set a category to enabled=true to capture it; anything omitted is off. The default set (used by enabled=true with no per-category settings) is the lightweight operational signals: control, connection, system, captcha. The CDP categories (console, network, page, interaction) and screenshot are off by default and must be opted into. properties: console: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Console output (log, warn, error) and uncaught exceptions. CDP category; off by default. page: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Page lifecycle events including navigation, DOMContentLoaded, load, layout shifts, and LCP. CDP category; off by default. interaction: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- User interaction events including clicks, keydowns, and scroll-settled events. CDP category; off by default. network: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- HTTP request and response metadata including URL, method, status code, and timing. Request post data is forwarded as-is from CDP. Text response bodies are truncated at 8 KB for structured types (JSON, XML, form data) and 4 KB for other text types. Binary responses (images, fonts, media) are excluded. CDP category; off by default. control: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Agent-driven actions against the browser, such as inbound calls to the in-VM API. On by default. connection: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Client attach/detach lifecycle for the CDP proxy and live view. On by default. system: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Browser VM health, such as out-of-memory kills and managed-service crashes. On by default. screenshot: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Periodic base64-encoded viewport screenshots. High volume; off by default and must be opted into. captcha: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: Captcha solve attempt outcomes. On by default. ErrorDetail: type: object properties: code: type: string description: Lower-level error code providing more specific detail example: invalid_input message: type: string description: Further detail about the error example: Provided version string is not semver compliant BrowserTelemetryCategoryConfig: type: object description: Per-category telemetry configuration. properties: enabled: type: boolean description: >- Whether this category is captured. Selection is opt-in, so an omitted category is not captured. responses: BadRequest: description: Bad Request – invalid input content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized – missing or invalid authorization token content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden – insufficient permissions or plan content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Conflict – resource already exists content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Too Many Requests – rate limit exceeded headers: Retry-After: description: Seconds to wait before retrying schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' CapacityExhausted: description: Capacity exhausted, unable to fulfill request at this time content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer ````