Vessel Browser

Vessel: Your AI-Powered Browser

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.

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.

• A familiar browser, with AI help nearby — tabs, bookmarks, reader mode, downloads, and a sidebar assistant for web tasks
• 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
• 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
• Open source and extensible — built on Chromium, with advanced automation support for MCP clients and agent tools when you need it

Linux is the most mature install target today. macOS release packaging is available from source.

Vessel is in active development. Treat it as early software, especially for sensitive browsing or account access.

https://github.com/user-attachments/assets/0a72b48a-873a-4eb0-b8f2-23e34d8472c4

Quick Start

Want the complete AI toolkit from day one? Start a 7-Day Free Trial of Vessel Premium — $5.99/mo.

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.

Features

• AI-assisted browsing — ask Vessel to help with research, page reading, navigation, form work, and multi-step web tasks
• Human-visible browser UI — pages render like a normal browser so AI activity stays legible instead of disappearing into a hidden run
• Command Bar (Ctrl+L) — a secondary operator surface for harness-driven workflows and future runtime commands
• Supervisor Sidebar (Ctrl+Shift+L) — live supervision across ten tabs, including a durable Run Inbox, conversation Threads, approvals, checkpoints, changes, and Research
• 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
• 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
• 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.
• 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
• 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
• 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
• 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
• 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

Reliability, History, and Approvals

The Supervisor sidebar now keeps longer-running work understandable across Chat, external MCP agents, scheduled jobs, and Research:

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

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.

Positioning

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.

That means the product should optimize for:

• persistent browser state across tasks and sessions
• clear visibility into what the agent is doing right now
• lightweight human intervention instead of constant manual driving
• a browser runtime that can serve long-lived agent systems such as Hermes Agent or OpenClaw-style harnesses

Stack

Architecture

Main Process                                  Renderer (SolidJS)
├── TabManager (WebContentsView[])            ├── TabBar, AddressBar
├── AgentRuntime (session + supervision)      ├── CommandBar (secondary surface)
├── Run, conversation, and policy managers    ├── AI Sidebar (Supervisor/Runs/Threads/Chat/...)
├── MCP server for external agents            ├── DevTools Panel (Console/Network/Activity)
├── AI providers (Anthropic + OAI-compatible) ├── Agent Transcript Dock
├── Bookmarks, checkpoints, and page history  └── Signal stores (runtime/runs/conversations/policies/...)
└── IPC handlers ◄──contextBridge──► Preload API

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.

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.

Getting Started

The installer:

• clones or updates Vessel into ~/.local/share/vessel-browser
• installs dependencies and builds the app
• creates a vessel-browser launcher in ~/.local/bin
• creates a vessel-browser-launch helper in ~/.local/bin
• creates a vessel-browser-update helper in ~/.local/bin
• creates a vessel-browser-status helper in ~/.local/bin
• creates a desktop entry for Linux app launchers
• writes ~/.config/vessel/vessel-settings.json with MCP port 3100
• writes ~/.config/vessel/mcp-stdio-snippet.json
• writes ~/.config/vessel/mcp-http-snippet.json
• installs a vessel-browser-mcp helper that can run as a stdio-to-HTTP proxy (--stdio) or print config snippets
• prints the exact recommended stdio MCP snippet to paste into your harness config

The packaged AppImage path:

• does not require a local Node/Electron toolchain
• uses the packaged Vessel app icon and metadata
• is the recommended path for early adopters who just want to run Vessel

Windows packaged releases:

• use the Vessel-<version>-x64-setup.exe NSIS installer
• can be installed over an existing Vessel install when upgrading
• preserve Vessel app data during the normal upgrade path

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.

After install:

vessel-browser

# Use the pinned Node.js 22 runtime
fnm use

# Install dependencies
npm install

# If Electron download fails, use a mirror:
ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" npm install

# Development (with HMR)
npm run dev

# Production build
npm run build

# Smoke-test the MVP release path
npm run smoke:test

# Package an unpacked Linux app
npm run dist:dir

# Package a Linux AppImage
npm run dist

# Package an unpacked universal macOS app bundle (run on macOS)
npm run dist:mac:dir

# Package universal macOS DMG + ZIP artifacts (run on macOS)
npm run dist:mac

# Verify a universal macOS build contains Intel and Apple Silicon slices
npm run verify:mac:universal

# Package signed macOS DMG + ZIP artifacts (run on macOS with signing set up)
npm run dist:mac:signed

Notes:

• npm run dev still launches the stock Electron binary, so Linux may continue showing the default Electron gear icon in development
• packaged builds created with npm run dist / npm run dist:dir use the Vessel app icon
• npm run build:icon:mac regenerates resources/vessel-icon.icns from resources/vessel-icon.png for macOS packaging
• 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
• npm run dist:mac:x64 and npm run dist:mac:arm64 are available when you need smaller architecture-specific test artifacts
• npm run verify:mac:universal uses lipo to confirm the packaged app executable and Electron framework include both x86_64 and arm64 slices
• 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
• 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
• signed builds are still not notarized by this repo out of the box, so Gatekeeper warnings remain until notarization is added for release publishing
• the tracked smoke test runs typecheck, build, the MCP stdio proxy regression check, and the Electron navigation regression harness
• for headless CI, run the smoke test under xvfb-run -a npm run smoke:test
• 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
• 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

Setting up Vessel for Hermes Agent or OpenClaw

Vessel is designed to act as the browser runtime that your external agent harness drives.

1. Launch Vessel
2. Open Settings (Ctrl+,) to confirm MCP status, copy the endpoint, or change the MCP port
3. Optional: set an Obsidian vault path, create autofill profiles, or adjust session preferences
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
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
6. Open Runs to inspect or export activity from Chat, MCP, scheduled jobs, and Research; use Threads to reopen and organize durable conversations
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

Notes:

• Vessel exposes browser control to external agents through its local MCP server
• The MCP endpoint supports both legacy clients and the modern 2026-07-28 protocol revision, including server/discover
• The default MCP port is 3100
• Hermes Agent and OpenClaw should treat Vessel as the persistent, human-visible browser rather than launching their own separate browser session
• Vessel supports a built-in Chat tab with configurable AI provider; open Settings (Ctrl+,) and enable Chat Assistant to set a provider and model
• 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.
• 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
• 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
• Approval policy is controlled live from the sidebar Supervisor panel rather than a separate global settings screen
• Settings now show MCP runtime status, active endpoint, startup warnings, and allow changing the MCP port with an immediate server restart
• Settings also include reusable Form Autofill profiles for one-click filling of common contact and address forms on the active page
• 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
• Premium users can open the sidebar Changes tab for the full What Changed timeline for the active page
• The Bookmarks tab can export browser-compatible HTML, HTML with Vessel notes, or a full Vessel JSON archive with agent metadata intact
• Agents can selectively disable ad blocking for a problematic tab, reload, retry the flow, and turn blocking back on later
• Agents can persist authenticated state with named sessions, for example github-logged-in, and reload that state in later runs
• The intended control plane is an external harness driving Vessel through MCP
• If you set an Obsidian vault path in Settings, harnesses can write markdown notes directly into that vault via Vessel memory MCP tools

Using llama.cpp as the built-in chat provider

Vessel can talk directly to a local llama-server through its OpenAI-compatible API.

Example:

llama-server -m /path/to/model.gguf --port 8080 --ctx-size 32768

Then in Vessel:

1. Open Settings (Ctrl+,)
2. Enable Chat Assistant
3. Choose llama.cpp (Local) as the provider
4. Click refresh if needed; Vessel will auto-detect the active model from http://localhost:8080/v1

Notes:

• --ctx-size 16384 is the minimum practical setting for Vessel agent loops
• --ctx-size 32768 is the recommended default for longer browsing sessions
• 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

Initial memory tools:

• vessel_memory_note_create
• vessel_memory_append
• vessel_memory_list
• vessel_memory_search
• vessel_memory_page_capture
• vessel_memory_link_bookmark

Bookmark and folder tools exposed today include:

• vessel_bookmark_list
• vessel_bookmark_search
• vessel_bookmark_open
• vessel_bookmark_save
• vessel_bookmark_remove
• vessel_create_folder
• vessel_folder_rename
• vessel_folder_remove

Page interaction and recovery tools exposed today include:

• vessel_extract_content
• vessel_read_page
• vessel_scroll
• vessel_dismiss_popup
• vessel_set_ad_blocking
• vessel_wait_for
• vessel_screenshot (Premium) — capture the full page as an image for visual AI analysis
• undo_last_action — restore the browser to the snapshot captured before the last successful mutating agent action

Page highlight tools:

• vessel_highlight — visually mark text or an element on the page with a labeled, color-coded overlay; persists until cleared
• vessel_clear_highlights — remove all highlights from the current page

Workflow tracking tools:

• vessel_flow_start — begin a named multi-step workflow and declare its steps upfront; progress appears in the sidebar throughout execution
• vessel_flow_advance — mark the current step complete and advance to the next
• vessel_flow_status — check current workflow progress
• vessel_flow_end — clear the active workflow tracker

Data extraction tools (Premium):

• vessel_extract_table — extract a page table as structured JSON rows with column headers

Named session tools exposed today include:

• vessel_save_session
• vessel_load_session
• vessel_list_sessions
• vessel_delete_session

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.

Agent Credential Vault tools (Premium):

• vessel_vault_status — check whether stored credentials exist for a domain (returns labels/usernames, never passwords)
• vessel_vault_login — fill a login form using stored credentials (blind fill — credentials go directly into the page, never into the AI conversation)
• vessel_vault_totp — generate and fill a TOTP 2FA code from a stored secret

Session performance tools (Premium):

• vessel_metrics — show per-tool call counts, average durations, error rates, and total session stats

Vault security model:

• Credentials are encrypted at rest using AES-256-GCM with a key protected by the OS keychain (Electron safeStorage)
• Credential values are never sent to AI providers — they flow only through the main process to the content script
• Every credential use triggers a user consent dialog ("Allow Once" / "Allow for Session" / "Deny")
• All credential access is recorded in an append-only audit log
• Credentials are domain-scoped — they can only be used on matching domains
• Users manage credentials in Settings > Agent Credential Vault

Notable extraction modes include:

• visible_only — only currently visible, in-viewport, unobstructed interactive elements plus active overlays
• results_only — likely primary search/result links only
• full / summary / interactives_only / forms_only / text_only

The extraction output can distinguish:

• active blocking overlays
• dormant consent/modal UI present in the DOM but not active for the current session or region

Stdio proxy MCP config (recommended — resolves auth automatically):

{
  "mcpServers": {
    "vessel": {
      "command": "vessel-browser-mcp",
      "args": ["--stdio"]
    }
  }
}

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. Vessel must already be running when your MCP client connects, and ~/.config/vessel/mcp-auth.json must exist from install or first launch.

Generic HTTP MCP config (requires copying the token manually):

{
  "mcpServers": {
    "vessel": {
      "type": "http",
      "url": "http://127.0.0.1:3100/mcp",
      "headers": {
        "Authorization": "Bearer <token from ~/.config/vessel/mcp-auth.json>"
      }
    }
  }
}

Hermes Agent config.yaml MCP config:

mcp_servers:
  vessel:
    url: "http://127.0.0.1:3100/mcp"
    headers:
      Authorization: "Bearer <token from ~/.config/vessel/mcp-auth.json>"
    timeout: 180
    connect_timeout: 30

Configuration

The installer writes three snippets to:

• ~/.config/vessel/mcp-stdio-snippet.json
• ~/.config/vessel/mcp-http-snippet.json
• ~/.config/vessel/mcp-hermes-snippet.yaml

It also installs a helper command:

vessel-browser-mcp

Helper examples:

# Run as stdio-to-HTTP proxy (for MCP client integration)
vessel-browser-mcp --stdio

# Recommended stdio MCP snippet
vessel-browser-mcp

# Generic JSON snippet with Authorization header
vessel-browser-mcp --format json

# Hermes-ready YAML snippet with Authorization header
vessel-browser-mcp --format hermes

# Raw MCP endpoint URL
vessel-browser-mcp --format url

# Raw MCP bearer token
vessel-browser-mcp --format token

Source install update helpers:

# Check whether a source-install update is available
vessel-browser-update --check

# Fetch, rebuild, and update the local source install
vessel-browser-update

Status helper:

# Human-readable local install + MCP status
vessel-browser-status

# Machine-readable status for harnesses
vessel-browser-status --json

Smart launch helper:

# Launch Vessel using the best available local install
vessel-browser-launch

# Show the chosen launch path without starting anything
vessel-browser-launch --dry-run

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.

Keyboard Shortcuts

Project Structure

src/
├── main/                 # Electron main process
│   ├── ai/               # Agent tools, query flow, and AI provider implementations
│   ├── tabs/             # Tab + TabManager (WebContentsView)
│   ├── agent/            # Agent runtime, checkpoints, supervision, flow tracking
│   ├── conversations/    # Secure conversation thread and chat storage
│   ├── runs/             # Durable cross-source run records, timelines, export redaction
│   ├── policy/           # Action classification and scoped approval policies
│   ├── persistence/      # Debounced JSON and secure-storage persistence helpers
│   ├── content/          # Readability extraction, reader mode, screenshot, page snapshots/diff
│   ├── config/           # Settings persistence
│   ├── autofill/         # Autofill profile persistence and form-field matching
│   ├── ipc/              # IPC handler registry
│   ├── vault/            # Agent Credential Vault (encrypted storage, consent, audit)
│   ├── mcp/              # MCP server for external agent control
│   ├── devtools/         # CDP session management for Dev Tools panel
│   ├── highlights/       # Page highlight capture, injection, and persistence
│   ├── health/           # Runtime health monitoring (MCP, settings, ports)
│   ├── premium/          # Subscription management, feature gating, Stripe integration
│   ├── bookmarks/        # Bookmark and folder persistence
│   ├── history/          # Browse history
│   ├── memory/           # Obsidian vault hooks
│   ├── network/          # Ad blocking, URL safety, link validation, downloads
│   ├── sessions/         # Named session save/load/delete
│   ├── startup/          # App initialization, menu, shortcuts, renderer bootstrap
│   ├── telemetry/        # PostHog analytics (opt-in)
│   ├── tools/            # Tool definitions, input coercion, pruning
│   ├── window.ts         # Window layout manager
│   └── index.ts          # App entry point
├── preload/              # contextBridge scripts
│   ├── index.ts          # Chrome UI preload
│   └── content-script.ts # Web page preload (readability)
├── renderer/             # SolidJS browser UI
│   └── src/
│       ├── components/
│       │   ├── chrome/   # TitleBar, TabBar, AddressBar, AgentTranscriptDock
│       │   ├── ai/       # CommandBar, Sidebar (Supervisor/Runs/Threads/Bookmarks/Checkpoints/Chat/Skills/History/Changes/Research)
│       │   ├── devtools/ # DevTools panel (Console, Network, Activity)
│       │   └── shared/   # Settings panel
│       ├── stores/       # SolidJS stores (runtime, runs, conversations, policies, tabs, AI, etc.)
│       ├── styles/       # Theme, global CSS
│       └── lib/          # Keybindings, markdown, skills registry
└── shared/               # Types + IPC channel constants

Design Principles

• Agent first — the browser is the agent's operating surface, not just a human tool with automation bolted on
• Human visible — the UI should make agent behavior easy to follow, audit, and steer
• Persistent by default — browser state should survive long-running workflows and repeated sessions
• Content first — chrome is 110px, everything else is your page
• Easy on the eyes — warm dark grays, muted text, no visual noise
• Linux-native — frameless window, system font fallbacks, XDG conventions

License

MIT

Developed by Tyler Williams in Portland, Oregon (2026)