Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @modelprofile.com/browser-runtime

The runtime requires Node.js 24 or newer and a non-root Linux host. Production browser sessions require a sandbox-capable Chromium installation.

Resource Model

The Controller owns durable resource and attachment truth. BrowserRuntime owns process-local registrations, fences, capabilities, leases, browser incarnations, artifacts, and its runtime lock. Registration never launches Chromium.

import {
  BrowserRuntime,
  type TBrowserCapabilityAuthorizationRequest,
} from '@modelprofile.com/browser-runtime';

const runtime = new BrowserRuntime({
  runtimeDirectory: '/var/lib/example/browser-runtime',
  authorizeCapability: async (binding) => hostPolicy.authorizeBrowser(binding),
});

try {
  await runtime.start();

  const resource = runtime.createResource({
    projectId: 'project-123',
    attachmentBinding: {
      attachmentAuthorityId: 'controller-attachment-1',
      attachmentRevision: 1,
      sessionId: { harnessId: 'opencode', nativeId: 'session-456' },
    },
  });

  const binding = {
    projectId: resource.projectId,
    browserResourceId: resource.browserResourceId,
    attachmentAuthorityId: resource.attachmentBinding.attachmentAuthorityId,
    attachmentRevision: resource.attachmentBinding.attachmentRevision,
    sessionId: { harnessId: 'opencode', nativeId: 'session-456' },
    actorId: 'agent-456',
    role: 'agent',
    peerId: 'worker-789',
    source: 'mcp',
  } satisfies TBrowserCapabilityAuthorizationRequest;

  const issued = await runtime.issueCapability(binding);

  const lease = await runtime.acquireLease({
    ...binding,
    capabilityToken: issued.capabilityToken,
  });

  try {
    console.log(await lease.executeAgentAction({ action: 'snapshot' }));
  } finally {
    await lease.release();
  }
} finally {
  await runtime.stop();
}

Projects and qualified sessions may each own many resources. Human/agent arbitration, mutexes, leases, operations, profiles, proxies, frame subscriptions, and idle timers are per resource.

registerResource() is idempotent only for the same project/resource key and identical attachment. listResources() reports process-local registration and incarnation metadata. terminateResource() terminates only the current incarnation and preserves registration, attachment, and artifacts. retireResource() permanently fences the process-local registration, revokes and quiesces authority, terminates its incarnation, purges exact-resource artifacts, and unregisters only after cleanup succeeds. The Controller separately owns durable retirement truth and must not rehydrate retired resources. Runtime tombstones and registrations are ephemeral, bounded process state. stop() revokes all process-local capabilities, terminates every incarnation, removes the Runtime-owned artifact root and registrations, and releases the lock without deleting Controller durable truth.

Attachment Fencing

Attachment bindings are Controller-owned { attachmentAuthorityId, attachmentRevision, sessionId } values. Any binding with sessionId: null is detached; revision 0 is the initial detached/no-agent-authority state. Reapplying the identical revision and binding is idempotent; lower revisions and conflicting equal revisions fail.

await runtime.applyAttachmentBinding({
  projectId: resource.projectId,
  browserResourceId: resource.browserResourceId,
  attachmentBinding: {
    attachmentAuthorityId: 'controller-attachment-1',
    attachmentRevision: 2,
    sessionId: null,
  },
});

A newer binding synchronously fences admission, revokes older capabilities, and quiesces active work. It normally preserves the incarnation; work that ignores cancellation causes termination of only that resource's incarnation.

Agent capabilities require the exact current non-detached qualified session. Human capabilities deliberately carry no session ID: they bind the exact project, resource, attachment authority, and revision and may be issued while detached. Any attachment revision advance invalidates both human and agent capabilities.

Agent actions are exactly navigate, snapshot, screenshot, click, fill, and press. Human leases additionally expose tab lifecycle, viewport, raw input, frame subscription/acknowledgement, and exact-resource artifact reads/deletes. JavaScript evaluation is not public.

Trusted Pipe And Flex

Trusted framed peers and clients receive the complete authority out of band: project, resource, attachment authority/revision, actor, peer, role, source, qualified session, Flex scope, and resource-specific channel. Incoming frames cannot select identity. One session may use multiple resource-specific channels concurrently.

BrowserRuntimeFlexToolProvider<TScope> resolves only a capability token and exposes the six approved SmartAgent actions. The framed server validates the token against its complete trusted binding.

MCP Handler

createBrowserRuntimeMcpHttpHandler() requires independent request authentication to return the complete expected MCP binding. The bearer capability must match it exactly. Identity remains server-owned and no tool input contains a project, resource, authority, revision, session, actor, or peer selector.

The MCP tool list is exactly browser_navigate, browser_snapshot, browser_screenshot, browser_click, browser_fill, and browser_press.

Egress And Artifacts

Each running resource owns one authenticated loopback BrowserEgressProxy carrying immutable projectId and browserResourceId. HTTP, WebSocket Upgrade, and CONNECT share strict public-unicast DNS/IP validation, numeric dialing, bounded lifetimes, and fail-closed policy.

Artifact identity and APIs use (projectId, browserResourceId, artifactId). Keyed project/resource directories prevent caller IDs from entering paths. Admission is serialized across per-resource, per-project, and global count/byte quotas. Reads use no-follow handles and verify size and SHA-256. Agent, Flex, and MCP surfaces receive metadata only.

Verification

pnpm install
pnpm dedupe
pnpm run build
pnpm run check:test
pnpm test
pnpm run test:real-chrome

The real Chromium check launches two resources in one project and qualified session, verifies distinct private profiles, sandboxed renderer process trees, mandatory confinement, screenshots, confirmed shutdown, and profile deletion.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the contents of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@modelprofile.com/browser-runtime