Headless browser automation

Run browser profiles without a visible browser window. Use the local API, MCP or an RPA workflow; the TabGecko desktop application must remain running and signed in.

What runs headless?#

Use case	Configuration
Existing Chromium or Firefox profile	`POST /api/v1/profiles/{id}/start` · `headless: true`
Temporary browser session	`POST /api/v1/runtime/once` · `headless: true`
RPA workflow	`headless: true` in the workflow definition
MCP client	Uses the profile configuration and the same local browser runtime.

Headless describes the browser window, not a hosted cloud service or a separate headless desktop login. Install the required kernel first and keep the desktop account connected. Website login alone does not start the local API.

Use an existing profile#

Start an existing Chromium or Firefox profile with headless:true in the start body. This applies only to this session and preserves saved launch arguments. Check the installed schema first: older clients need an update before using this option.

POST /api/v1/profiles/{id}/start

{"headless":true}

Node.js CLI

node tabgecko.mjs request POST /api/v1/profiles/PROFILE_ID/start headless.json
node tabgecko.mjs request GET /api/v1/profiles/PROFILE_ID/runtime
node tabgecko.mjs stop PROFILE_ID

Save the JSON as headless.json and replace PROFILE_ID with the actual UUID. Starting and stopping require runtime:control. Keep automation enabled; automation:false cannot be combined with headless. The batch start endpoint also accepts headless:true.

Start a temporary headless session#

This request creates a temporary profile and starts its browser. It requires profiles:write and runtime:control as well as the corresponding account permissions. Use it only for disposable data: the session is cleaned up on expiry or after closing when auto_close is enabled.

POST /api/v1/runtime/once

{
  "profile": {
    "name": "Headless example",
    "engine": "chromium"
  },
  "headless": true,
  "duration_seconds": 300,
  "auto_close": true
}

Node.js CLI

node tabgecko.mjs request POST /api/v1/runtime/once temporary.json
node tabgecko.mjs request GET /api/v1/runtime/once
node tabgecko.mjs request DELETE /api/v1/runtime/once/SESSION_ID

Save the payload as temporary.json. Use the returned id as SESSION_ID, not profile_id. A temporary session is owned by its local API token; use that same token to inspect or end it.

RPA and MCP#

For an RPA workflow, set headless:true at the top level of the workflow definition and inspect its run result. A workflow accepted by the server is not necessarily completed. MCP profile starts accept body.headless:true without changing the saved profile. Discover the exact tools and schemas through tools/list instead of inventing parameters.

RPA workflow guide · Connect MCP

Check the result and limitations#

Check the runtime response and session endpoint. A start error, missing kernel or disconnected account is not a running headless session.
Page automation is available through supported browser APIs. Native operating-system dialogs and actions that require a visible window are not equivalent to page automation.
The local API listens on loopback. Remote clients need a supported local connection; opening this documentation does not expose a remote API.
For a visible session, stop the profile and start with headless:false. Saved launch arguments remain unchanged.

Troubleshoot connection and start errors