Project Tendril

A local-first Obscura browser and web-research runtime built for AI agents, with Chromium available as a compatibility fallback.

Project Tendril gives MCP clients and autonomous agents a real, isolated browser process with token-efficient semantic snapshots, ref-based browser actions, rendered-page extraction, search, research, crawling, screenshots, diagnostics, and authenticated Chrome DevTools Protocol access where the backend supports it. The default Obscura engine is written in Rust; Chromium remains available for headed sessions and long-tail web compatibility.

It runs locally, has no embedded LLM, sends no telemetry, and never attaches to your everyday browser profile.

Contents

• Why Project Tendril?

• Features

• How it works

• Requirements

• Quick start

• Connect an MCP client

• MCP tools

• REST and CDP

• Search, research, and crawling

• Challenge handling

• Configuration

• Security model

• Docker

• Deployment and recovery

• Release process

• Development

• Troubleshooting

• Project status and roadmap

• Contributing

Related MCP server: MCP Chrome Bridge

Why Project Tendril?

Most browser integrations give an agent either raw screenshots or a large, unstable DOM. Project Tendril adds an agent-oriented layer over a selectable browser backend:

• Fast default engine — Obscura provides a Rust browser engine, V8 JavaScript, CDP automation, persistent storage, and consistent fingerprinting without shipping Chromium in the default container.

• Compatibility fallback — Chromium supports headed operation and browser features not yet implemented by Obscura.

• Compact semantic state — accessibility-informed snapshots expose roles, names, values, and short-lived element refs without returning an entire page source.

• Deterministic actions — agents act on refs from the newest snapshot; stale refs fail instead of silently selecting the wrong element.

• Useful web evidence — search, rendered-page extraction, and multi-source research return structured URLs and untrusted evidence without hiding an LLM in the browser layer.

• Process isolation — each Tendril session owns a browser process, profile directory, CDP endpoint, and network proxy.

• Multiple interfaces — use stdio MCP, Streamable HTTP MCP, authenticated REST, raw CDP, the CLI, or the local dashboard.

• Local control — profiles, cookies, downloads, browser processes, and logs remain on the machine running Tendril.

Project Tendril is inspired by the architectural ideas in Cloudflare's Kitesurf announcement: fresh sessions, centralized outbound access, structured browser representations, bounded failure, and disposable workers. Project Tendril is an independent implementation and contains no Cloudflare source code.

Features

Browser automation

• Dedicated Obscura or Chromium process and user-data directory per session.

• Ephemeral sessions by default; opt-in named profiles for durable logins.

• Multiple pages per session with open, list, select, and close operations.

• Navigation history, reload, configurable load states, and bounded waits.

• Click, double-click, hover, focus, fill, type, select, check, press, scroll, drag, and upload actions.

• JavaScript dialogs, cookies, storage, viewport, locale, and headers, with Chromium-only support for permissions, geolocation, offline mode, timezone, media preferences, and HTTP credentials.

• Full-page, viewport, and element screenshots, with Chromium available for native PDF output and long-tail rendering compatibility.

• Bounded console events, request/response metadata, response bodies, downloads, and page-scoped JavaScript evaluation.

Agent-oriented page understanding

• Interactive, full, reader, and differential semantic snapshots.

• Short element refs tied to a specific page, frame, URL, and snapshot.

• Snapshot pagination and output limits for predictable context use.

• Mozilla Readability extraction and HTML-to-Markdown conversion.

• Structured links, metadata, forms, and tables.

• Explicit untrustedContent: true markers and heuristic prompt-injection warnings.

Web discovery

• Browser-independent search with Bing, DuckDuckGo, Google, and optional SearXNG adapters.

• Automatic provider fallback when a provider fails or challenges the browser.

• Multi-query research with URL deduplication and source-attributed evidence chunks.

• Bounded, cancellable, robots-aware crawling with same-origin and depth controls.

Interfaces and operations

• MCP over stdio for simple local client ownership.

• Stateless Streamable HTTP MCP for a shared long-running service.

• Authenticated REST quick actions and session APIs.

• Authenticated raw CDP WebSockets for Chromium sessions. Obscura isolates each CDP connection, so Tendril does not advertise a second raw gateway connection for those sessions.

• Local observation and control dashboard.

• Runtime diagnostics, structured logging, profile management, Docker packaging, and CI.

How it works

flowchart LR
    A[AI agent or MCP client] -->|stdio MCP| M[MCP server]
    A -->|Bearer-authenticated HTTP| H[HTTP service]
    C[CDP client] -->|Authenticated WebSocket| H
    U[Local operator] -->|Dashboard| H

    M --> B[BrowserManager]
    H --> B
    B --> S1[Tendril session]
    B --> S2[Tendril session]

    S1 --> P1[Per-session egress proxy]
    S1 --> R1[Dedicated Obscura process]
    S2 --> P2[Per-session egress proxy]
    S2 --> R2[Dedicated browser process]

    P1 --> W[Public web]
    P2 --> W

For every session, Project Tendril:

1. Creates an ephemeral directory or locks an explicitly named profile.

2. Starts a loopback forward proxy with that session's network policy.

3. Launches a separate Obscura or Chromium process with a random loopback CDP port.

4. Connects Playwright over CDP for high-level browser control.

5. Registers bounded browser, console, network, download, crash, page, and dialog observers.

6. Terminates the complete process group and deletes ephemeral state when the session closes.

This process-per-session model prevents unrelated agents from sharing cookies, cache, storage state, or a browser crash boundary.

See Architecture for implementation detail.

Requirements

• Node.js 22.19 or newer

• Obscura 0.2.1 for the default backend; tendril install-browser installs a checksum-pinned build

• Chromium, Google Chrome, or Playwright-managed Chromium only when using the fallback backend

• A non-root user with a working Chromium sandbox when Chromium is selected

Linux is the fully tested v1.0 platform. Project Tendril includes Chromium discovery for Windows and macOS, and CI exercises all three operating systems, but Linux remains the recommended deployment target.

Quick start

Install from source

git clone https://github.com/gadgethd/Project-Tendril.git
cd Project-Tendril
npm ci
npm run build
npm link
tendril doctor

If no supported browser is installed:

tendril install-browser

Run the local HTTP service, dashboard, MCP endpoint, and CDP gateway:

tendril serve

Or run only a stdio MCP server:

tendril mcp

Use --headed when a visible browser is required. This selects the Chromium fallback because Obscura is currently headless-only:

tendril serve --headed

tendril serve prints a dashboard URL containing the local bearer token in the URL fragment. The dashboard moves the token to session storage; URL fragments are not sent as part of HTTP requests.

Run without linking

npm ci
npm run build
node dist/cli.js doctor
node dist/cli.js mcp

Connect an MCP client

Local stdio

Stdio is the simplest and safest configuration. The MCP client starts Project Tendril as a child process and owns its lifetime:

{
  "mcpServers": {
    "project-tendril": {
      "command": "tendril",
      "args": ["mcp"]
    }
  }
}

For a source checkout without npm link:

{
  "mcpServers": {
    "project-tendril": {
      "command": "node",
      "args": [
        "/absolute/path/to/Project-Tendril/dist/cli.js",
        "mcp"
      ]
    }
  }
}

To permit a person to complete an interactive login or challenge, add --headed to the arguments.

Streamable HTTP

Start the shared service:

TENDRIL_TOKEN="replace-with-a-long-random-token" tendril serve

Then configure an MCP client for:

• URL: http://127.0.0.1:3210/mcp

• Header: Authorization: Bearer replace-with-a-long-random-token

If TENDRIL_TOKEN is not set, Project Tendril creates a random token and stores it at:

• Linux: ~/.local/share/project-tendril/http-token

• Other platforms: the operating system's equivalent user data directory

On POSIX, Tendril validates owner-only permissions and ownership for this file. On Windows, token privacy inherits the ACL on the configured data directory; restrict ACLs on custom or shared paths, or supply TENDRIL_TOKEN through your secret manager.

Recommended agent workflow

1. Create an ephemeral session with browser_session.

2. Navigate with browser_navigate.

3. Take a fresh browser_snapshot.

4. Use refs from that snapshot with browser_act.

5. Take another snapshot after navigation or DOM-changing actions.

6. Close the session when the task is complete.

Never cache element refs across navigation. Refs are intentionally invalidated when their page state is no longer current.

MCP tools

Project Tendril exposes 18 tools:

The MCP resource tendril://status reports runtime version and active-session status.

REST and CDP

Only /health, /dashboard, and the root dashboard redirect are public. MCP, REST, metrics, OpenAPI, and CDP access require authentication even from loopback or private-network peers. The service binds to loopback by default.

Extract Markdown from a rendered page

TOKEN="$(tr -d '\n' < ~/.local/share/project-tendril/http-token)"

curl --fail-with-body --silent --show-error \
  http://127.0.0.1:3210/v1/markdown \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com"}'

Other quick actions include:

• POST /v1/snapshot

• POST /v1/content

• POST /v1/accessibility-tree

• POST /v1/links

• POST /v1/screenshot

• POST /v1/pdf

• POST /v1/search

• POST /v1/research

• POST /v1/crawl

Create a durable browser session

curl --fail-with-body --silent --show-error \
  http://127.0.0.1:3210/v1/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"profile":"documentation"}'

Chromium session responses include a browser-level cdpUrl. Its query token supports CDP clients that cannot supply custom WebSocket headers. Obscura sessions intentionally omit cdpUrl because each new CDP WebSocket creates a different isolated context.

Connect Playwright over CDP

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(process.env.TENDRIL_CDP_URL);
const context = browser.contexts()[0];
const pages = context.pages();

console.log(await pages[0].title());

CDP URLs contain a short-lived capability bound to one Tendril session; they never contain the master bearer token. Treat possession of an unexpired CDP URL as full control of that browser session.

The authenticated service exposes a compact OpenAPI document at http://127.0.0.1:3210/openapi.json.

Search, research, and crawling

browser_search queries configured providers through bounded HTTP adapters, rejects results that do not cover the query, and deterministically fuses provider rank with relevance. It returns normalized titles, URLs, snippets, ranks, scores, provider provenance, and typed partial failures. The default preference order is:

1. SearXNG, when an endpoint is configured

2. DuckDuckGo

3. Bing

4. Google, when Custom Search credentials are configured

Configure a self-hosted SearXNG instance by setting searxngUrl. Its JSON API is used directly, retaining native scores, engines, publication dates, and unresponsive-engine metadata. Unconfigured providers are skipped without opening a browser session.

Search discovery does not require an installed browser or a free browser slot. Provider requests use the same network policy and DNS pinning as browser egress, with a total deadline covering DNS, redirects, retries, and response streaming. Transient GET failures receive one bounded retry; rate limits and Retry-After responses are respected. Gzip, deflate, and Brotli responses are decoded within compressed and decompressed byte limits.

Completed search results and research evidence survive another provider or page reaching the deadline. Such responses set partial: true and explain the missing work in failures or evidenceFailures. Explicit cancellation still stops work. An entirely failed search remains an error, with error.recovery explaining the next step. See the agent workflow and recovery guide.

Run npm run test:search for offline reliability checks. Live provider checks are opt-in: TENDRIL_LIVE_SEARCH=true npm run test:search:live, or TENDRIL_LIVE_SEARXNG_URL=https://your-instance.example npm run test:search:live for your SearXNG endpoint. Normal tests never contact a live provider.

browser_research accepts up to ten queries, balances sources across queries and domains, visits sources concurrently within session and output budgets, and returns stable citation IDs with originating query, canonical and final URLs, status, MIME type, retrieval time, and content hash. It does not generate a summary; the calling agent remains responsible for analysis and citation.

Research waits for temporary browser capacity within its deadline. Retrieve a retained job with action: "get" and jobId; this does not repeat searches or visits. Refinement prioritizes newly discovered sources when the source budget is full and gives their evidence first use of the output budget.

browser_crawl creates an asynchronous job with:

• A maximum of 100 pages.

• A maximum depth of 5.

• Same-origin restriction enabled by default.

• robots.txt compliance enabled by default.

• Joinable cancellation, compact status, paginated partial results, and per-page errors.

• At most 100 retained jobs, with completed jobs expiring after 30 minutes.

Search providers and websites may rate-limit automated access. Project Tendril reports the failure or tries the next configured search provider. Obscura's default stealth mode keeps its browser fingerprint internally consistent, but is not a challenge-bypass mechanism.

Challenge handling

When browser_challenge detects Cloudflare, Turnstile, reCAPTCHA, hCaptcha, DuckDuckGo, Google, or an unknown challenge, Project Tendril pauses automation for a human handoff. It does not attempt to solve or bypass challenges automatically.

A human completes the challenge in a headed Chromium window:

1. Start Project Tendril with --headed, or select browserBackend: "chromium" and create the session with headless: false.

2. Call browser_challenge with action: "inspect".

3. Call it with action: "handoff"; Project Tendril focuses the exact challenged page.

4. A human completes the challenge in Chromium.

5. Call it with action: "wait"; the tool returns when the challenge disappears.

6. Resume automation in the same session.

General guidance

• Use a narrowly scoped named profile when a legitimate login or clearance cookie must survive a restart. Project Tendril does not copy clearance between profiles or machines.

• For automated tests, prefer the challenge provider's official testing keys and test modes.

Configuration

Copy the example:

cp tendril.config.example.json tendril.config.json

Configuration precedence is:

1. Built-in defaults

2. tendril.config.json

3. TENDRIL_* environment variables

4. CLI flags

Important options

Action timeout, navigation timeout, snapshot size, and maximum response-body size can also be set in the JSON configuration. See tendril.config.example.json and src/config.ts for the complete schema and defaults.

Local-development access

Private and loopback destinations are blocked by default. To test a local site:

tendril mcp --allow-private-network

This is intentionally explicit. Prefer a narrow allowedHosts entry when possible.

Security model

Project Tendril assumes every URL, page, frame, script, download, and MCP argument may be hostile.

Network boundary

• Every session uses a dedicated HTTP/HTTPS forward proxy.

• The proxy resolves hostnames and connects only to the checked address, reducing DNS-rebinding exposure.

• Loopback, RFC1918 private networks, link-local ranges, multicast, reserved addresses, carrier-grade NAT, and cloud metadata destinations are blocked by default.

• Redirects and subresources create new proxy requests and are checked again.

• High-level navigation accepts only public HTTP(S) URLs.

• Chromium additionally disables non-proxied WebRTC UDP, QUIC, WebTransport, extensions, and background networking.

Profile and filesystem boundary

• Project Tendril never opens the user's normal browser profile.

• Named profiles are opt-in and locked to one live session; deletion acquires the same exclusive lock before removing profile data.

• Profile locks fail closed after an unclean exit. After verifying that no Tendril process owns the profile, remove the reported .profile-locks/<name>.lock file explicitly before restarting it; Tendril never reclaims stale locks automatically because replacing a lock safely cannot be guaranteed portably.

• Upload paths are canonicalized and restricted to configured workspace roots.

• Ephemeral profiles are deleted on close.

• Chromium is refused when Project Tendril runs as root unless an explicit development override is supplied.

Agent boundary

• Page-derived data is marked untrusted.

• Common instruction-override and exfiltration phrases produce warnings.

• Snapshot, extraction, console, network, and response-body output is bounded.

• Page JavaScript evaluation is explicit and runs inside the selected page, not the Project Tendril Node.js process.

• Challenge resolution is opt-in and local-only; no external solving services are contacted.

These controls are guardrails, not a complete virtual-machine boundary. Use the hardened container or another VM boundary for adversarial browsing. Read Security and SECURITY.md before exposing Project Tendril to other machines.

Docker

Build the image:

docker build -t project-tendril:local .

Run Obscura as the image's non-root tendril user with a read-only root filesystem:

docker run --rm --init \
  --name project-tendril \
  -p 127.0.0.1:3210:3210 \
  --memory 2g \
  --cpus 2 \
  --pids-limit 512 \
  --read-only \
  --tmpfs /tmp:rw,nosuid,nodev,size=1g \
  --security-opt seccomp=seccomp_profile.json \
  --cap-drop ALL \
  -e TENDRIL_TOKEN="replace-with-a-long-random-token" \
  project-tendril:local

The image contains a checksum-pinned Obscura 0.2.1 binary and retains no Linux capabilities. The included seccomp profile remains compatible with the Chromium fallback if you build a custom image containing Chromium.

Persist named profiles and the generated HTTP token:

docker volume create project-tendril-data

docker run --rm --init \
  --name project-tendril \
  -p 127.0.0.1:3210:3210 \
  --memory 2g \
  --cpus 2 \
  --pids-limit 512 \
  --read-only \
  --tmpfs /tmp:rw,nosuid,nodev,size=1g \
  --security-opt seccomp=seccomp_profile.json \
  --cap-drop ALL \
  -v project-tendril-data:/data \
  project-tendril:local

Do not publish port 3210 beyond loopback without an authenticated TLS reverse proxy and an explicit threat review.

Development

git clone https://github.com/gadgethd/Project-Tendril.git
cd Project-Tendril
npm ci
npm run check

Useful commands:

The integration suite launches real Chromium for the compatibility suite and a pinned Obscura binary in its dedicated CI job. It covers:

• Semantic snapshots and ref-based actions.

• MCP server discovery and browser control.

• REST quick actions and authenticated raw CDP.

• Search/crawl primitives and robots.txt.

• Challenge detection.

• Private-network and navigation policy.

• Screenshot generation and process cleanup.

Repository layout

Project-Tendril/
├── src/
│   ├── browser/          Backends, sessions, snapshots, extraction, search, crawl
│   ├── security/         Network policy and per-session egress proxy
│   ├── server/           MCP, HTTP, CDP gateway, and dashboard
│   ├── cli.ts            Command-line entry point
│   ├── config.ts         Defaults, file, and environment configuration
│   └── runtime.ts        Shared service composition
├── tests/                Chromium and Obscura integration tests
├── docs/                 Architecture and security documentation
├── .github/              CI, security scanning, releases, and community files
├── Dockerfile
├── seccomp_profile.json
└── tendril.config.example.json

Troubleshooting

No Obscura executable found

tendril install-browser
tendril doctor

Or set TENDRIL_OBSCURA_PATH to an Obscura executable. For Chromium instead, set TENDRIL_BROWSER_BACKEND=chromium and optionally TENDRIL_EXECUTABLE_PATH.

Chromium refuses to start as root

Run Project Tendril as a regular user. The browser sandbox is part of the security model. The Docker image already uses a dedicated non-root account.

Docker reports a sandbox or namespace error

Use the documented seccomp_profile.json, retain only SYS_CHROOT, and do not set no-new-privileges. Run docker build again after changing the Dockerfile.

A local development URL is blocked

Private destinations are denied by default. Add the exact hostname to allowedHosts or use --allow-private-network only for a trusted local-development session.

Element ref is stale

Take a new browser_snapshot and use a ref from that result. Navigation and DOM-changing actions deliberately invalidate old refs.

Search provider returns a challenge

Allow Project Tendril to try the next configured provider, configure SearXNG, or use a headed human handoff where the provider permits it. Do not retry aggressively.

Project status and roadmap

Project Tendril 1.0 is feature-complete for local Linux deployment. The native, MCP, REST, CDP, package, and Docker paths are covered by automated integration tests.

Likely post-1.0 work:

• Broader Windows and macOS runtime validation.

• More search adapters and self-hosted discovery options.

• Trace recording and replay tooling.

• Additional snapshot compression and diff strategies.

• Optional OpenTelemetry-compatible local metrics export without hosted telemetry.

• Published npm and container-registry artifacts.

Roadmap items are not promises. Open a feature request with a concrete agent workflow and expected security boundary.

Contributing

Contributions are welcome. Read:

• Contributing guide

• Code of Conduct

• Security policy

• Support guide

• Changelog

Before opening a pull request:

npm ci
npm run typecheck
npm test
npm run build

Changes that add CAPTCHA solving, access-control or fingerprint-evasion behavior, telemetry, implicit access to normal browser profiles, or private-network access by default are outside the project's scope.

License

Project Tendril is licensed under the Apache License 2.0.

Copyright 2026 Project Tendril contributors.