ghostfox
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GHOSTFOX_HOME | Yes | Path to the unpacked Ghostfox engine directory, e.g. /opt/ghostfox. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| identity_generateA | Generate a new coherent browser identity, returned as TOML. |
| page_openA | Navigate to a URL in an existing session. Returns a page_id (string) that must be passed to all subsequent page tools. Waits for the page to load. If the page has iframes or shadow DOM, use page_a11y instead of guessing CSS selectors. Example: page_open(session_id, 'https://example.com') returns a page_id like 'abc123'. |
| page_clickA | Click an element by CSS selector. For form controls (buttons, inputs), uses a JS click; for links and other elements, dispatches real mouse events at coordinates. Prefer page_click_ref when you have a page_a11y ref — it scrolls into view first and is more reliable on web-component UIs. Returns 'ok' on success. |
| page_screenshotA | Capture a PNG screenshot of a page (viewport by default, full page with full_page=true). Saved under the session recordings dir; returns the file path. Feeds the live view when enabled. |
| captcha_solveA | Solve a CAPTCHA through the configured provider (env GHOSTFOX_CAPTCHA_PROVIDER=2captcha + GHOSTFOX_CAPTCHA_KEY). Turnstile/hcaptcha: pass sitekey + pageurl; image captchas: pass image_base64. Stealth-first: prefer not being challenged at all. |
| session_createA | Create a new browsing session: launches the engine with a fresh coherent identity. Returns session_id. |
| page_a11yA | Semantic snapshot of the page: every visible interactive element with a stable ref, role (button/link/textbox/...), accessible name and CURRENT value — pierces shadow DOM, so web-component UIs (Reddit, modern frameworks) are fully visible. Use this instead of guessing CSS selectors. |
| page_click_refA | Click an element by its ref from page_a11y. Scrolls it into view first. No selectors needed. |
| session_evidenceB | Get recorded evidence for a session: event log, snapshot files, identity used. Recordings live under ~/.ghostfox/recordings/. |
| page_typeA | Type text character-by-character into an element by CSS selector (human-like key events). Prefer page_type_ref when you have a page_a11y ref — it handles rich editors (Lexical/Draft/ProseMirror) and returns a verified receipt. Use this only when you only have a CSS selector and don't need rich editor support. Returns 'ok' on success. |
| page_pressA | Press a named key (Enter, Tab, Escape, ArrowDown, ...) — e.g. Enter to submit a search box. |
| page_evalA | Evaluate a JavaScript expression in the page's main frame and return its JSON value. Read-only introspection is safest; treat results of mutations with care. |
| page_wait_forA | Wait until a CSS selector becomes visible on the page (replaces manual sleeps). Returns true if found, false on timeout. |
| page_snapshotA | Extract the visible text content of a page as plain text (token-friendly). Returns: url, title, and content (all visible text, no HTML). For semantic element data with refs and values, use page_a11y instead — it gives you interactive elements with roles and names. Use this when you just need to READ page content without needing to interact with elements. |
| page_fillA | Set an input's value directly (form fill). Works where key-event typing hits engine bugs; fires input/change events like real edits. |
| page_type_refA | Type text into the element a page_a11y ref points at (inputs and rich editors). Returns landed chars as a receipt. |
| page_upload_fileA | Upload a file to an input[type=file] by CSS selector. The file must exist on the machine running the engine. |
| page_read_refA | Read the FULL value of an element by its page_a11y ref — no truncation. Use when the snapshot's 200-char preview isn't enough (body text, long input fields). |
| identity_auditA | Audit an identity TOML for coherence violations (contradictory signals a detector would flag). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 19 tools
Most tools are clearly separated by resource and action, and pairs like page_click/page_click_ref are explicitly distinguished via selector-based vs. a11y-ref-based interaction. A couple of input-setting tools (page_type vs page_fill) could be misselected without close reading, but the descriptions resolve this.
The dominant pattern is resource-prefixed actions (page_open, session_create, identity_generate, captcha_solve), which is predictable and readable. Deviations like page_a11y, page_snapshot, and session_evidence are noun-style but follow the same prefix convention, so only minor inconsistency exists.
19 tools is slightly above the ideal 3-15 range but justified by the need for selector-based and ref-based variants plus identity, session, page, and captcha coverage. No tool feels redundant enough to cut outright, though the set is substantial.
The core browsing loop—create session, open page, read, interact, wait, screenshot, collect evidence—is well covered, and identity/captcha workflows are included. Missing session/page teardown (e.g., session_close, page_close) and navigation controls are minor gaps but not blocking for most automation tasks.