Skip to content
Back to search

vessel-browser

Built from the ground-up for agents, Vessel Browser is an open source AI browser for Linux/Mac/Windows that provides a durable state, MCP control, and BYOK with full autonomous browsing. Use with Hermes Agent, OpenClaw, or connect to your favorite API provider.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/unmodeled-tyler--vessel-browser/badge.svg)](/listings/unmodeled-tyler--vessel-browser)

HTML

<a href="/listings/unmodeled-tyler--vessel-browser"><img src="/api/listings/unmodeled-tyler--vessel-browser/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Want the complete AI toolkit from day one? [Start a 7-Day Free Trial of Vessel Premium — $5.99/mo](https://vesselpremium.quantaintellect.com/checkout).

Fastest Install Today

Linux AppImage from GitHub Releases:

1. Download the latest `Vessel-<version>-x64.AppImage` 2. Mark it executable: `chmod +x Vessel-*.AppImage` 3. Launch it: `./Vessel-*.AppImage` 4. Open Settings (`Ctrl+,`) to choose your AI provider and review advanced connection options

Install via npm

npm install -g @quanta-intellect/vessel-browser
vessel-browser

Or run it directly without installing:

npx @quanta-intellect/vessel-browser

Source Install

curl -fsSL https://raw.githubusercontent.com/unmodeled-tyler/vessel-browser/main/scripts/install.sh | bash

Development From Source

Vessel development uses Node.js 22. If you use `fnm`, run `fnm use` from the repo root to pick up `.node-version`.

fnm use
npm install
npm run dev

If you want extra local AI tracing in development, create an optional `src/main/telemetry/trace-logger.local.cjs` file. Vessel will load it only in local dev builds, and packaged production builds ignore it.

Why Vessel?

Most AI tools can answer questions about the web. Vessel is for actually working on the web: reading pages, following links, comparing information, filling forms, tracking changes, and keeping longer browsing sessions organized.

Vessel keeps that work visible. The AI uses a real browser, so you can see the pages it opens, the choices it makes, and the places where it needs your approval. You are never stuck watching a hidden automation run or guessing what happened after the fact.

For power users and developers, the same foundation also supports external agents, MCP clients, persistent sessions, checkpoints, and browser automation workflows.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 605 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. ![quanta-intellect-logo-transparent](https://cdn-uploads.huggingface.co/production/uploads/686c460ba3fc457ad14ab6f8/gB6J60f9Yeyb3Thop2dUa.png)
  3. <a href="https://snapcraft.io/vessel-browser">
  4. <img alt="Get it from the Snap Store" src=https://snapcraft.io/en/dark/install.svg />
  5. </a>
  6. <a href="https://www.producthunt.com/products/quanta-intellect?embed=true&amp;utm_source=badge-featured&amp;utm_medium=badge&amp;utm_campaign=badge-vessel-browser-from-quanta-intellect" target="_blank" rel="noopener noreferrer"><img alt="Vessel Browser from Quanta Intellect - The browser where agents drive and humans supervise | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1107491&amp;theme=dark&amp;t=1774779141692"></a>
  7. # Vessel: Your AI-Powered Browser
  8. </div>
  9. Vessel is a simple, clean web browser with an AI assistant built in. Browse the web normally, then ask Vessel to help research, navigate pages, summarize what you are reading, fill forms, or keep track of longer tasks.
  10. Unlike invisible browser automation, Vessel shows you what the AI is doing in a real browser window. You can follow along, approve important actions, pause or redirect the work, and take over whenever you want.
  11. - **A familiar browser, with AI help nearby** — tabs, bookmarks, reader mode, downloads, and a sidebar assistant for web tasks
  12. - **Great for longer browsing sessions** — durable conversation threads, a cross-source run inbox, named sessions, checkpoints, notes, bookmarks, and page changes make interrupted work recoverable
  13. - **You stay in control** — review what the AI is doing, approve sensitive actions once or for a scoped run/domain, reject with steering, undo recent changes, and switch back to manual browsing at any time
  14. - **Open source and extensible** — built on Chromium, with advanced automation support for MCP clients and agent tools when you need it
  15. Linux is the most mature install target today. macOS release packaging is available from source.
  16. _Vessel is in active development. Treat it as early software, especially for sensitive browsing or account access._
  17. https://github.com/user-attachments/assets/0a72b48a-873a-4eb0-b8f2-23e34d8472c4
  18. ## Quick Start
  19. Want the complete AI toolkit from day one? [Start a 7-Day Free Trial of Vessel Premium — $5.99/mo](https://vesselpremium.quantaintellect.com/checkout).
  20. ### Fastest Install Today
  21. Linux AppImage from GitHub Releases:
  22. 1. Download the latest `Vessel-<version>-x64.AppImage`
  23. 2. Mark it executable: `chmod +x Vessel-*.AppImage`
  24. 3. Launch it: `./Vessel-*.AppImage`
  25. 4. Open Settings (`Ctrl+,`) to choose your AI provider and review advanced connection options
  26. ### Install via npm
  27. ```bash
  28. npm install -g @quanta-intellect/vessel-browser
  29. vessel-browser
  30. ```
  31. Or run it directly without installing:
  32. ```bash
  33. npx @quanta-intellect/vessel-browser
  34. ```
  35. ### Source Install
  36. ```bash
  37. curl -fsSL https://raw.githubusercontent.com/unmodeled-tyler/vessel-browser/main/scripts/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 58 on GitHub
  38. ```
  39. ### Development From Source
  40. Vessel development uses Node.js 22. If you use `fnm`, run `fnm use` from the repo root to pick up `.node-version`.
  41. ```bash
  42. fnm use
  43. npm install
  44. npm run dev
  45. ```
  46. If you want extra local AI tracing in development, create an optional `src/main/telemetry/trace-logger.local.cjs` file. Vessel will load it only in local dev builds, and packaged production builds ignore it.
  47. ### Why Vessel?
  48. Most AI tools can answer questions about the web. Vessel is for actually working on the web: reading pages, following links, comparing information, filling forms, tracking changes, and keeping longer browsing sessions organized.
  49. <img width="1280" height="800" alt="Vessel Browser supervisor sidebar showing agent workflow controls" src="https://github.com/user-attachments/assets/8e208ee1-cb89-4318-87a2-9561a7d9aecf" />
  50. <img width="1280" height="800" alt="Vessel Browser command bar and agent-driven page interaction" src="https://github.com/user-attachments/assets/da7b28ea-6c5f-4aa7-909e-0a255c80d508" />
  51. <img width="1280" height="800" alt="Vessel Browser persistent session and checkpoint interface" src="https://github.com/user-attachments/assets/3b3d2033-5a59-4806-bbc1-359efb7b43a9" />
  52. <img width="1280" height="800" alt="Vessel Browser integrated chat assistant with browser tools" src="https://github.com/user-attachments/assets/b1c08d6c-bcdf-4c9a-8429-a71a23a61903" />
  53. Vessel keeps that work visible. The AI uses a real browser, so you can see the pages it opens, the choices it makes, and the places where it needs your approval. You are never stuck watching a hidden automation run or guessing what happened after the fact.
  54. For power users and developers, the same foundation also supports external agents, MCP clients, persistent sessions, checkpoints, and browser automation workflows.
  55. ## Features
  56. - **AI-assisted browsing** — ask Vessel to help with research, page reading, navigation, form work, and multi-step web tasks
  57. - **Human-visible browser UI** — pages render like a normal browser so AI activity stays legible instead of disappearing into a hidden run
  58. - **Command Bar** (`Ctrl+L`) — a secondary operator surface for harness-driven workflows and future runtime commands
  59. - **Supervisor Sidebar** (`Ctrl+Shift+L`) — live supervision across ten tabs, including a durable Run Inbox, conversation Threads, approvals, checkpoints, changes, and Research
  60. - **Chat Assistant** — built-in conversational AI in the sidebar Chat tab; supports Anthropic, OpenAI, Ollama, llama.cpp, Mistral, xAI, Google Gemini, OpenRouter, and any OpenAI-compatible endpoint; reads the current page automatically; has full access to the same browser tools as external agents; multi-turn session history; configure provider, model, and API key in Settings
  61. - **Skills** (Premium) — reusable browser skills in the sidebar Skills tab; import, view, run, or delete skills the built-in agent can use for research, shopping, and site-specific workflows
  62. - **Research Desk** (Beta) — a dedicated sidebar Research tab for structured research reports; start with a topic, complete an in-tab briefing, let Vessel draft research objectives, approve the plan, then dispatch browser sub-agents to collect source-backed claims and synthesize a markdown-exportable report. Starting the brief is free; plan approval, sub-agent execution, and report export require Vessel Premium.
  63. - **Dev Tools Panel** (`F12`) — inspect console output, network requests, and MCP/agent activity in a resizable panel at the bottom of the window; export logs by category and date range as JSON
  64. - **Browser Basics For Long Runs** — pinned tabs stay compact at the front of the tab strip and are protected from accidental close; tab groups can be color-coded and collapsed; audible tabs show audio indicators with mute controls; open additional browser windows with `Ctrl+N`; print the active page with `Ctrl+P` or save it directly as PDF with `Ctrl+Shift+P`
  65. - **Action Undo / Rollback** — restore the browser to the session snapshot captured immediately before the last successful mutating agent action; available from the Supervisor tab and through the `undo_last_action` tool
  66. - **Durable Run Inbox** — Chat, MCP, scheduled, and Research work share one persisted lifecycle with status filters, parent/child research runs, redacted inputs, outputs, errors, and tab context
  67. - **Persistent Conversation Threads** — group multiple independent chats inside named threads; each chat gets an AI-generated title after its first completed exchange and can be reopened or retitled, while threads can be renamed, archived, or deleted; archived threads follow the configured history period
  68. - **Scoped Approval Policies** — approve once, approve for a run, approve for a domain, or reject and steer; explicit denies take precedence and expired scoped rules are ignored
  69. - **Agent-Meaningful Bookmarks** — bookmarks carry structured context the agent can read and act on: `intent` (what the page is for), `expectedContent` (what to expect on the page), `keyFields` (important form fields), `agentHints` (arbitrary directives), and a stored `pageSchema`; humans can create and edit this metadata directly in the Bookmarks tab, and all fields are searchable
  70. - **Portable Bookmark Export** — export browser-compatible Netscape HTML for import into Chrome, Firefox, Safari, Edge, Brave, and other browsers; optionally include Vessel notes/agent metadata, or export a full-fidelity Vessel JSON archive
  71. - **Page Schema Inference** — Vessel automatically infers a typed schema for every page: `pageType` (article, product, form, search, checkout, login, dashboard), `primaryEntity` (structured fields for products and articles), `formFields` (with names, types, labels, selectors), and `actionButtons` (with inferred intents: submit, addToCart, login, etc.); schema is attached to every content extraction result
  72. - **Bookmarks for Agents** — save pages into folders, attach one-line folder summaries, and search bookmarks over MCP instead of dumping the entire library
  73. - **Named Session Persistence** — save cookies, localStorage, and current tab layout under a reusable name, then reload it after a restart
  74. - **Annotated Checkpoints** — capture and restore short-lived browser recovery points with names and editable notes, so humans and agents can mark why a checkpoint matters before risky flows
  75. - **Page Highlights** — agents can visually highlight text or elements on any page with labeled, color-coded markers that persist across navigation; highlight count and navigation controls appear in the sidebar; cleared explicitly or via tool call
  76. - **Agent Transcript Dock** — floating transcript overlay anchored to the browser chrome; configurable display modes (off, summary, full) set in Settings; shows live agent thinking and status updates without occupying sidebar space
  77. - **Workflow Flow Tracking** — agents can declare a named multi-step workflow at runtime using `flow_start`; progress is tracked step-by-step with `flow_advance` and visible in the sidebar throughout execution
  78. - **Structured Page Visibility Context** — extraction can report in-viewport elements, obscured controls, active overlays, and dormant consent/modal UI
  79. - **Popup Recovery Tools** — agents can explicitly dismiss common popups, newsletter gates, and consent walls instead of brute-forcing generic clicks
  80. - **Form Autofill Profiles** — save reusable personal or work profiles in Settings and fill common contact, address, and organization fields on the current page; Vessel matches fields using labels, names, placeholders, and autocomplete hints
  81. - **Page Diff / "What Changed?"** — Vessel remembers the last snapshot of a page and surfaces a `Changed` badge in the address bar when the title, headings, or main content differ on a later visit; expand it to see a compact summary of what changed since the last snapshot
  82. - **What Changed Timeline** (Premium) — the sidebar Changes tab keeps a per-page history of recent change bursts, showing when each update was detected and a compact summary of what changed
  83. - **Per-Tab Ad Blocking Controls** — tabs default to ad blocking on, but agents can selectively disable and re-enable blocking when a page misbehaves
  84. - **Domain Policy** — allowlist or blocklist domains globally in Settings; agents cannot navigate to blocked domains
  85. - **Agent Credential Vault** (Premium) — encrypted credential storage for agent-driven logins; credentials are filled directly into login forms via a "blind fill" pattern and are never sent to AI providers; user consent dialog before every use; TOTP 2FA support; domain-scoped access; append-only audit log
  86. - **Screenshot & Visual Analysis** (Premium) — take a full-page screenshot and pass the image directly to the AI for visual layout analysis; useful when text extraction fails on heavy or canvas-rendered pages
  87. - **Obsidian Memory Hooks** (Premium) — optional vault path for agent-written markdown notes, page captures, and research breadcrumbs
  88. - **Runtime Health Checks** — startup warnings for MCP port conflicts, unreadable settings, and user-data write failures
  89. - **Reader Mode** — extract article content into a clean, distraction-free view; toggle on and off from the address bar
  90. - **Focus Mode** (`Ctrl+Shift+F`) — hide all chrome, content fills the screen
  91. - **Resizable Panels** — drag the sidebar edge to resize; width persists across sessions
  92. - **Minimal Dark Theme** — warm dark grays, restrained accent color, and no pure black/white
  93. ### Reliability, History, and Approvals
  94. The Supervisor sidebar now keeps longer-running work understandable across Chat, external MCP agents, scheduled jobs, and Research:
  95. - Open **Runs** to filter work that needs attention, is active, failed, completed, or comes from any source. Each run has a chronological timeline with status changes, approvals, outputs, errors, and relevant tab context; records can be exported as Markdown or JSON or deleted from Vessel.
  96. - Open **Threads** to organize multiple chats under a named topic. Chats can be reopened or retitled independently, while their parent thread can be renamed, archived, or deleted. New chats receive a generated title after their first completed exchange.
  97. - Approval cards show the action, redacted arguments, domain, and whether undo is available. You can approve once, approve matching work for the current run or domain, reject, or reject with written steering. Persisted scoped rules remain visible in Supervisor and can be removed there.
  98. - If Vessel closes while a run is active or waiting for approval, that run is marked **interrupted** on the next launch instead of being left misleadingly active. Vessel does not claim to resume or retry the unfinished execution automatically.
  99. - Terminal run history and archived threads follow `historyRetentionDays` (`90` days by default; supported values are `7`, `30`, `90`, `180`, `365`, or `null` for no automatic expiry). Active runs and unarchived threads are preserved.
  100. Conversation history is encrypted through Electron's `safeStorage` API when encryption is available. If secure storage is unavailable, Vessel keeps conversations in memory for that session instead of writing plaintext chat history. Run records redact sensitive argument fields and limit stored output size before persistence or export.
  101. ## Positioning
  102. Most browsers treat automation as secondary and assume a human is the primary actor. Vessel is the opposite: it is the browser for the agent, with a visible interface that keeps the human in the loop.
  103. That means the product should optimize for:
  104. - persistent browser state across tasks and sessions
  105. - clear visibility into what the agent is doing right now
  106. - lightweight human intervention instead of constant manual driving
  107. - a browser runtime that can serve long-lived agent systems such as Hermes Agent or OpenClaw-style harnesses
  108. ## Stack
  109. | Layer | Technology |
  110. | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
  111. | Engine | Chromium (Electron 40) |
  112. | UI Framework | SolidJS |
  113. | Language | TypeScript |
  114. | Build | electron-vite + Vite |
  115. | AI Control | External agent harnesses (Hermes Agent, OpenClaw, MCP clients) + built-in chat (Anthropic, OpenAI, Ollama, llama.cpp, and any OAI-compatible endpoint) |
  116. | Content Extraction | @mozilla/readability |
  117. ## Architecture
  118. ```
  119. Main Process Renderer (SolidJS)
  120. ├── TabManager (WebContentsView[]) ├── TabBar, AddressBar
  121. ├── AgentRuntime (session + supervision) ├── CommandBar (secondary surface)
  122. ├── Run, conversation, and policy managers ├── AI Sidebar (Supervisor/Runs/Threads/Chat/...)
  123. ├── MCP server for external agents ├── DevTools Panel (Console/Network/Activity)
  124. ├── AI providers (Anthropic + OAI-compatible) ├── Agent Transcript Dock
  125. ├── Bookmarks, checkpoints, and page history └── Signal stores (runtime/runs/conversations/policies/...)
  126. └── IPC handlers ◄──contextBridge──► Preload API
  127. ```
  128. Each browser tab is a separate `WebContentsView` managed by the main process. The browser chrome (SolidJS) runs in its own view layered on top. All communication between renderer and main goes through typed IPC channels via `contextBridge`.
  129. The sidebar Skills tab renders skill forms entirely in the renderer and passes the rendered prompt to the built-in agent via the same `query()` path used by the Chat tab — no additional IPC surface is needed. The Changes tab reads the current page's diff timeline through IPC and unlocks persisted history for Premium users. The Research tab has a dedicated IPC surface for its state machine: briefing is available to everyone, while objective approval, parallel browser sub-agents, report synthesis, and markdown export are Premium-gated during the beta.
  130. ## Getting Started
  131. The installer:
  132. - clones or updates Vessel into `~/.local/share/vessel-browser`
  133. - installs dependencies and builds the app
  134. - creates a `vessel-browser` launcher in `~/.local/bin`
  135. - creates a `vessel-browser-launch` helper in `~/.local/bin`
  136. - creates a `vessel-browser-update` helper in `~/.local/bin`
  137. - creates a `vessel-browser-status` helper in `~/.local/bin`
  138. - creates a desktop entry for Linux app launchers
  139. - writes `~/.config/vessel/vessel-settings.json` with MCP port `3100`
  140. - writes `~/.config/vessel/mcp-stdio-snippet.json`
  141. - writes `~/.config/vessel/mcp-http-snippet.json`
  142. - installs a `vessel-browser-mcp` helper that can run as a stdio-to-HTTP proxy (`--stdio`) or print config snippets
  143. - prints the exact recommended stdio MCP snippet to paste into your harness config
  144. The packaged AppImage path:
  145. - does not require a local Node/Electron toolchain
  146. - uses the packaged Vessel app icon and metadata
  147. - is the recommended path for early adopters who just want to run Vessel
  148. Windows packaged releases:
  149. - use the `Vessel-<version>-x64-setup.exe` NSIS installer
  150. - can be installed over an existing Vessel install when upgrading
  151. - preserve Vessel app data during the normal upgrade path
  152. You do not need to uninstall Vessel before installing a newer Windows release. Uninstall first only if you are recovering from a broken install or intentionally removing local Vessel data.
  153. After install:
  154. ```bash
  155. vessel-browser
  156. ```
  157. ```bash
  158. # Use the pinned Node.js 22 runtime
  159. fnm use
  160. # Install dependencies
  161. npm install
  162. # If Electron download fails, use a mirror:
  163. ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" npm install
  164. # Development (with HMR)
  165. npm run dev
  166. # Production build
  167. npm run build
  168. # Smoke-test the MVP release path
  169. npm run smoke:test
  170. # Package an unpacked Linux app
  171. npm run dist:dir
  172. # Package a Linux AppImage
  173. npm run dist
  174. # Package an unpacked universal macOS app bundle (run on macOS)
  175. npm run dist:mac:dir
  176. # Package universal macOS DMG + ZIP artifacts (run on macOS)
  177. npm run dist:mac
  178. # Verify a universal macOS build contains Intel and Apple Silicon slices
  179. npm run verify:mac:universal
  180. # Package signed macOS DMG + ZIP artifacts (run on macOS with signing set up)
  181. npm run dist:mac:signed
  182. ```
  183. Notes:
  184. - `npm run dev` still launches the stock Electron binary, so Linux may continue showing the default Electron gear icon in development
  185. - packaged builds created with `npm run dist` / `npm run dist:dir` use the Vessel app icon
  186. - `npm run build:icon:mac` regenerates `resources/vessel-icon.icns` from `resources/vessel-icon.png` for macOS packaging
  187. - `npm run dist:mac` and `npm run dist:mac:dir` build universal macOS artifacts by default, so the same app runs natively on Intel and Apple Silicon Macs
  188. - `npm run dist:mac:x64` and `npm run dist:mac:arm64` are available when you need smaller architecture-specific test artifacts
  189. - `npm run verify:mac:universal` uses `lipo` to confirm the packaged app executable and Electron framework include both `x86_64` and `arm64` slices
  190. - `npm run dist:mac`, `npm run dist:mac:dir`, `npm run dist:mac:x64`, and `npm run dist:mac:arm64` intentionally disable auto-signing so local packaging works on any Mac without keychain setup
  191. - `npm run dist:mac:signed` and `npm run dist:mac:dir:signed` build universal artifacts and use normal `electron-builder` signing discovery; if your login keychain has duplicate Apple certs, clean those up or use a dedicated keychain before running the signed path
  192. - signed builds are still not notarized by this repo out of the box, so Gatekeeper warnings remain until notarization is added for release publishing
  193. - the tracked smoke test runs typecheck, build, the MCP stdio proxy regression check, and the Electron navigation regression harness
  194. - for headless CI, run the smoke test under `xvfb-run -a npm run smoke:test`
  195. - run `npm run test:navigation-regression` for the standalone navigation suite; it builds fresh test/preload bundles, opens focused test windows, and uses a temporary profile and loopback server
  196. - the navigation runner requires a completed-suite report as well as a zero exit, times out after three minutes, and removes its temporary files on normal completion or failure
  197. ### Setting up Vessel for Hermes Agent or OpenClaw
  198. Vessel is designed to act as the browser runtime that your external agent harness drives.
  199. 1. Launch Vessel
  200. 2. Open Settings (`Ctrl+,`) to confirm MCP status, copy the endpoint, or change the MCP port
  201. 3. Optional: set an Obsidian vault path, create autofill profiles, or adjust session preferences
  202. 4. Start Hermes Agent or OpenClaw and point it at Vessel — the easiest way is `vessel-browser-mcp --stdio` as the MCP command (auth is resolved automatically), or connect directly to `http://127.0.0.1:<mcpPort>/mcp` with the bearer token from `~/.config/vessel/mcp-auth.json`
  203. 5. Use the Supervisor panel in Vessel's sidebar to pause the agent, change approval mode, review pending approvals, checkpoint, undo the last mutating action, or restore the browser session while the harness runs
  204. 6. Open Runs to inspect or export activity from Chat, MCP, scheduled jobs, and Research; use Threads to reopen and organize durable conversations
  205. 7. Use the Bookmarks panel to organize saved pages into folders, edit agent-facing bookmark metadata, export bookmarks for other browsers, and expose saved pages back to the agent over MCP
  206. Notes:
  207. - Vessel exposes browser control to external agents through its local MCP server
  208. - The MCP endpoint supports both legacy clients and the modern `2026-07-28` protocol revision, including `server/discover`
  209. - The default MCP port is `3100`
  210. - Hermes Agent and OpenClaw should treat Vessel as the persistent, human-visible browser rather than launching their own separate browser session
  211. - Vessel supports a built-in Chat tab with configurable AI provider; open Settings (`Ctrl+,`) and enable Chat Assistant to set a provider and model
  212. - The sidebar Research tab is marked Beta; use it to turn a broad research topic into a brief, approve a multi-thread plan, run browser sub-agents, and export the final report as markdown. Briefing is free, while full execution and export require Premium.
  213. - `llama.cpp (Local)` is a first-class chat provider in Settings and targets `http://localhost:8080/v1` by default; Vessel auto-fetches the active model from `llama-server`
  214. - For `llama-server`, use `--ctx-size 16384` minimum and `32768` recommended for reliable Vessel agent loops; lower values often fail once prompt, tool schema, and tool history accumulate
  215. - Approval policy is controlled live from the sidebar Supervisor panel rather than a separate global settings screen
  216. - Settings now show MCP runtime status, active endpoint, startup warnings, and allow changing the MCP port with an immediate server restart
  217. - Settings also include reusable Form Autofill profiles for one-click filling of common contact and address forms on the active page
  218. - The address bar can also show a `Changed` badge when Vessel detects that a previously visited page has meaningfully changed since the last saved snapshot
  219. - Premium users can open the sidebar Changes tab for the full What Changed timeline for the active page
  220. - The Bookmarks tab can export browser-compatible HTML, HTML with Vessel notes, or a full Vessel JSON archive with agent metadata intact
  221. - Agents can selectively disable ad blocking for a problematic tab, reload, retry the flow, and turn blocking back on later
  222. - Agents can persist authenticated state with named sessions, for example `github-logged-in`, and reload that state in later runs
  223. - The intended control plane is an external harness driving Vessel through MCP
  224. - If you set an Obsidian vault path in Settings, harnesses can write markdown notes directly into that vault via Vessel memory MCP tools
  225. ### Using llama.cpp as the built-in chat provider
  226. Vessel can talk directly to a local `llama-server` through its OpenAI-compatible API.
  227. Example:
  228. ```bash
  229. llama-server -m /path/to/model.gguf --port 8080 --ctx-size 32768
  230. ```
  231. Then in Vessel:
  232. 1. Open Settings (`Ctrl+,`)
  233. 2. Enable Chat Assistant
  234. 3. Choose `llama.cpp (Local)` as the provider
  235. 4. Click refresh if needed; Vessel will auto-detect the active model from `http://localhost:8080/v1`
  236. Notes:
  237. - `--ctx-size 16384` is the minimum practical setting for Vessel agent loops
  238. - `--ctx-size 32768` is the recommended default for longer browsing sessions
  239. - Vessel will warn in Settings if it detects a `llama-server` context size below the recommended floor, or if it cannot detect the ctx size from the running server
  240. Initial memory tools:
  241. - `vessel_memory_note_create`
  242. - `vessel_memory_append`
  243. - `vessel_memory_list`
  244. - `vessel_memory_search`
  245. - `vessel_memory_page_capture`
  246. - `vessel_memory_link_bookmark`
  247. Bookmark and folder tools exposed today include:
  248. - `vessel_bookmark_list`
  249. - `vessel_bookmark_search`
  250. - `vessel_bookmark_open`
  251. - `vessel_bookmark_save`
  252. - `vessel_bookmark_remove`
  253. - `vessel_create_folder`
  254. - `vessel_folder_rename`
  255. - `vessel_folder_remove`
  256. Page interaction and recovery tools exposed today include:
  257. - `vessel_extract_content`
  258. - `vessel_read_page`
  259. - `vessel_scroll`
  260. - `vessel_dismiss_popup`
  261. - `vessel_set_ad_blocking`
  262. - `vessel_wait_for`
  263. - `vessel_screenshot` (Premium) — capture the full page as an image for visual AI analysis
  264. - `undo_last_action` — restore the browser to the snapshot captured before the last successful mutating agent action
  265. Page highlight tools:
  266. - `vessel_highlight` — visually mark text or an element on the page with a labeled, color-coded overlay; persists until cleared
  267. - `vessel_clear_highlights` — remove all highlights from the current page
  268. Workflow tracking tools:
  269. - `vessel_flow_start` — begin a named multi-step workflow and declare its steps upfront; progress appears in the sidebar throughout execution
  270. - `vessel_flow_advance` — mark the current step complete and advance to the next
  271. - `vessel_flow_status` — check current workflow progress
  272. - `vessel_flow_end` — clear the active workflow tracker
  273. Data extraction tools (Premium):
  274. - `vessel_extract_table` — extract a page table as structured JSON rows with column headers
  275. Named session tools exposed today include:
  276. - `vessel_save_session`
  277. - `vessel_load_session`
  278. - `vessel_list_sessions`
  279. - `vessel_delete_session`
  280. Session files are sensitive because they may contain login cookies and tokens. Vessel stores them under the app user-data directory with restrictive file permissions.
  281. Agent Credential Vault tools (Premium):
  282. - `vessel_vault_status` — check whether stored credentials exist for a domain (returns labels/usernames, never passwords)
  283. - `vessel_vault_login` — fill a login form using stored credentials (blind fill — credentials go directly into the page, never into the AI conversation)
  284. - `vessel_vault_totp` — generate and fill a TOTP 2FA code from a stored secret
  285. Session performance tools (Premium):
  286. - `vessel_metrics` — show per-tool call counts, average durations, error rates, and total session stats
  287. Vault security model:
  288. - Credentials are encrypted at rest using AES-256-GCM with a key protected by the OS keychain (Electron safeStorage)
  289. - Credential values are **never** sent to AI providers — they flow only through the main process to the content script
  290. - Every credential use triggers a user consent dialog ("Allow Once" / "Allow for Session" / "Deny")
  291. - All credential access is recorded in an append-only audit log
  292. - Credentials are domain-scoped — they can only be used on matching domains
  293. - Users manage credentials in Settings > Agent Credential Vault
  294. Notable extraction modes include:
  295. - `visible_only` — only currently visible, in-viewport, unobstructed interactive elements plus active overlays
  296. - `results_only` — likely primary search/result links only
  297. - `full` / `summary` / `interactives_only` / `forms_only` / `text_only`
  298. The extraction output can distinguish:
  299. - active blocking overlays
  300. - dormant consent/modal UI present in the DOM but not active for the current session or region
  301. Stdio proxy MCP config (recommended — resolves auth automatically):
  302. ```json
  303. {
  304. "mcpServers": {
  305. "vessel": {
  306. "command": "vessel-browser-mcp",
  307. "args": ["--stdio"]
  308. }
  309. }
  310. }
  311. ```
  312. The stdio proxy reads the bearer token from `~/.config/vessel/mcp-auth.json` at connection time and preserves both legacy and `2026-07-28` protocol negotiation, so no manual token management is needed.
  313. Vessel must already be running when your MCP client connects, and `~/.config/vessel/mcp-auth.json` must exist from install or first launch.
  314. Generic HTTP MCP config (requires copying the token manually):
  315. ```json
  316. {
  317. "mcpServers": {
  318. "vessel": {
  319. "type": "http",
  320. "url": "http://127.0.0.1:3100/mcp",
  321. "headers": {
  322. "Authorization": "Bearer <token from ~/.config/vessel/mcp-auth.json>"
  323. }
  324. }
  325. }
  326. }
  327. ```
  328. Hermes Agent `config.yaml` MCP config:
  329. ```yaml
  330. mcp_servers:
  331. vessel:
  332. url: "http://127.0.0.1:3100/mcp"
  333. headers:
  334. Authorization: "Bearer <token from ~/.config/vessel/mcp-auth.json>"
  335. timeout: 180
  336. connect_timeout: 30
  337. ```
  338. ## Configuration
  339. The installer writes three snippets to:
  340. - `~/.config/vessel/mcp-stdio-snippet.json`
  341. - `~/.config/vessel/mcp-http-snippet.json`
  342. - `~/.config/vessel/mcp-hermes-snippet.yaml`
  343. It also installs a helper command:
  344. ```bash
  345. vessel-browser-mcp
  346. ```
  347. Helper examples:
  348. ```bash
  349. # Run as stdio-to-HTTP proxy (for MCP client integration)
  350. vessel-browser-mcp --stdio
  351. # Recommended stdio MCP snippet
  352. vessel-browser-mcp
  353. # Generic JSON snippet with Authorization header
  354. vessel-browser-mcp --format json
  355. # Hermes-ready YAML snippet with Authorization header
  356. vessel-browser-mcp --format hermes
  357. # Raw MCP endpoint URL
  358. vessel-browser-mcp --format url
  359. # Raw MCP bearer token
  360. vessel-browser-mcp --format token
  361. ```
  362. Source install update helpers:
  363. ```bash
  364. # Check whether a source-install update is available
  365. vessel-browser-update --check
  366. # Fetch, rebuild, and update the local source install
  367. vessel-browser-update
  368. ```
  369. Status helper:
  370. ```bash
  371. # Human-readable local install + MCP status
  372. vessel-browser-status
  373. # Machine-readable status for harnesses
  374. vessel-browser-status --json
  375. ```
  376. Smart launch helper:
  377. ```bash
  378. # Launch Vessel using the best available local install
  379. vessel-browser-launch
  380. # Show the chosen launch path without starting anything
  381. vessel-browser-launch --dry-run
  382. ```
  383. `vessel-browser-launch` prefers a healthy source install and falls back to the newest local AppImage when the source install is likely blocked by Electron sandbox permissions.
  384. ## Keyboard Shortcuts
  385. | Shortcut | Action |
  386. | ------------------- | ----------------------- |
  387. | `Ctrl+L` | AI Command Bar |
  388. | `Ctrl+Shift+L` | Toggle AI Sidebar |
  389. | `Ctrl+Shift+F` | Toggle Focus Mode |
  390. | `F12` | Toggle Dev Tools Panel |
  391. | `Ctrl+N` | New Window |
  392. | `Ctrl+T` | New Tab |
  393. | `Ctrl+W` | Close Tab |
  394. | `Ctrl+Shift+T` | Reopen Closed Tab |
  395. | `Ctrl+Shift+N` | New Private Window |
  396. | `Ctrl+F` | Find in Page |
  397. | `Ctrl++` / `Ctrl+=` | Zoom In |
  398. | `Ctrl+-` | Zoom Out |
  399. | `Ctrl+0` | Reset Zoom |
  400. | `Ctrl+P` | Print Active Page |
  401. | `Ctrl+Shift+P` | Save Active Page as PDF |
  402. | `Ctrl+,` | Settings |
  403. ## Project Structure
  404. ```
  405. src/
  406. ├── main/ # Electron main process
  407. │ ├── ai/ # Agent tools, query flow, and AI provider implementations
  408. │ ├── tabs/ # Tab + TabManager (WebContentsView)
  409. │ ├── agent/ # Agent runtime, checkpoints, supervision, flow tracking
  410. │ ├── conversations/ # Secure conversation thread and chat storage
  411. │ ├── runs/ # Durable cross-source run records, timelines, export redaction
  412. │ ├── policy/ # Action classification and scoped approval policies
  413. │ ├── persistence/ # Debounced JSON and secure-storage persistence helpers
  414. │ ├── content/ # Readability extraction, reader mode, screenshot, page snapshots/diff
  415. │ ├── config/ # Settings persistence
  416. │ ├── autofill/ # Autofill profile persistence and form-field matching
  417. │ ├── ipc/ # IPC handler registry
  418. │ ├── vault/ # Agent Credential Vault (encrypted storage, consent, audit)
  419. │ ├── mcp/ # MCP server for external agent control
  420. │ ├── devtools/ # CDP session management for Dev Tools panel
  421. │ ├── highlights/ # Page highlight capture, injection, and persistence
  422. │ ├── health/ # Runtime health monitoring (MCP, settings, ports)
  423. │ ├── premium/ # Subscription management, feature gating, Stripe integration
  424. │ ├── bookmarks/ # Bookmark and folder persistence
  425. │ ├── history/ # Browse history
  426. │ ├── memory/ # Obsidian vault hooks
  427. │ ├── network/ # Ad blocking, URL safety, link validation, downloads
  428. │ ├── sessions/ # Named session save/load/delete
  429. │ ├── startup/ # App initialization, menu, shortcuts, renderer bootstrap
  430. │ ├── telemetry/ # PostHog analytics (opt-in)
  431. │ ├── tools/ # Tool definitions, input coercion, pruning
  432. │ ├── window.ts # Window layout manager
  433. │ └── index.ts # App entry point
  434. ├── preload/ # contextBridge scripts
  435. │ ├── index.ts # Chrome UI preload
  436. │ └── content-script.ts # Web page preload (readability)
  437. ├── renderer/ # SolidJS browser UI
  438. │ └── src/
  439. │ ├── components/
  440. │ │ ├── chrome/ # TitleBar, TabBar, AddressBar, AgentTranscriptDock
  441. │ │ ├── ai/ # CommandBar, Sidebar (Supervisor/Runs/Threads/Bookmarks/Checkpoints/Chat/Skills/History/Changes/Research)
  442. │ │ ├── devtools/ # DevTools panel (Console, Network, Activity)
  443. │ │ └── shared/ # Settings panel
  444. │ ├── stores/ # SolidJS stores (runtime, runs, conversations, policies, tabs, AI, etc.)
  445. │ ├── styles/ # Theme, global CSS
  446. │ └── lib/ # Keybindings, markdown, skills registry
  447. └── shared/ # Types + IPC channel constants
  448. ```
  449. ## Design Principles
  450. - **Agent first** — the browser is the agent's operating surface, not just a human tool with automation bolted on
  451. - **Human visible** — the UI should make agent behavior easy to follow, audit, and steer
  452. - **Persistent by default** — browser state should survive long-running workflows and repeated sessions
  453. - **Content first** — chrome is 110px, everything else is your page
  454. - **Easy on the eyes** — warm dark grays, muted text, no visual noise
  455. - **Linux-native** — frameless window, system font fallbacks, XDG conventions
  456. ## License
  457. MIT
  458. _Developed by Tyler Williams in Portland, Oregon (2026)_

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.