Browser Agent

The meshbrow-agent is a daemon that runs alongside each browser session inside its network namespace or Firecracker VM. It provides health monitoring, process supervision, metrics collection, and filesystem watching.

The agent is automatically deployed by the Meshbrow platform. You only need to install it manually for self-hosted or custom setups.

Installation

Homebrew (macOS/Linux)
Go Install
Binary
Docker

brew tap meshbrow-dev/tap
brew install meshbrow-agent

go install github.com/meshbrow-dev/meshbrow-agent@latest

curl -fsSL https://github.com/meshbrow-dev/meshbrow-agent/releases/latest/download/meshbrow-agent-linux-amd64 \
  -o /usr/local/bin/meshbrow-agent
chmod +x /usr/local/bin/meshbrow-agent

docker pull ghcr.io/meshbrow-dev/meshbrow-agent:latest

Verify the installation:

meshbrow-agent --version
# meshbrow-agent v0.1.0

Usage

meshbrow-agent \
  --session-id sess_abc123 \
  --socket /run/meshbrow/agent.sock \
  --workspace /tmp/meshbrow-session \
  --log-level info

Configuration

Flag	Env Variable	Default	Description
`--session-id`	`MESHBROW_SESSION_ID`	(required)	Browser session ID
`--socket`	`MESHBROW_SOCKET`	`/run/meshbrow/agent.sock`	Unix socket path
`--workspace`	`MESHBROW_WORKSPACE`	`/tmp/meshbrow-session`	Session workspace directory
`--log-level`	`MESHBROW_LOG_LEVEL`	`info`	Log level (debug, info, warn, error)
`--heartbeat-interval`	—	`5s`	Heartbeat reporting interval
`--metrics-interval`	—	`10s`	Metrics collection interval

What It Does

The agent provides five core capabilities:

Health Reporting

Sends periodic heartbeats to the host (browserd) over the unix socket. Reports:

Browser process alive/dead status
CPU and memory usage
Uptime
Process ID

Browser Process Supervision

Monitors the Chromium process. If the browser crashes, the agent reports it immediately via a health status change, allowing browserd to restart or destroy the session.

Metrics Collection

Collects system metrics at configurable intervals:

CPU utilization
Memory usage (used/total)
Disk usage
Network I/O (bytes sent/received)
Open file descriptors
Active goroutines

Filesystem Watching

Monitors the session workspace for changes and streams events:

File creation
File modification
File deletion

Excludes noise directories (.git, node_modules, __pycache__).

Graceful Shutdown

Handles SIGTERM and SIGINT signals. On shutdown:

Stops all subsystems (heartbeat, metrics, watcher)
Sends a deregistration message to the host
Exits cleanly

Architecture

┌──────────────────────────────────────────────────┐
│ Network Namespace / Firecracker VM               │
│                                                  │
│  ┌──────────────────────────────────────┐       │
│  │         meshbrow-agent                │       │
│  │                                       │       │
│  │  ┌───────────┐  ┌────────────────┐  │       │
│  │  │ FS Watcher │  │ Health/HB      │  │       │
│  │  └───────────┘  └────────────────┘  │       │
│  │  ┌───────────┐  ┌────────────────┐  │       │
│  │  │ Metrics   │  │ Command Rx     │  │       │
│  │  └───────────┘  └────────────────┘  │       │
│  └──────────────────────────────────────┘       │
│           │ unix socket                          │
│           │                                      │
│  ┌────────┴─────────────────────────────┐       │
│  │         chromium (headless)            │       │
│  └───────────────────────────────────────┘       │
└──────────┼───────────────────────────────────────┘
           │
   ┌───────┴───────┐
   │ Meshbrow Host │
   │   (browserd)  │
   └───────────────┘

Protocol Messages

The agent communicates via newline-delimited JSON over the unix socket.

Agent → Host

Type	Description
`register`	Initial registration with version, workspace, PID
`heartbeat`	Periodic health status
`metrics`	System metrics snapshot
`fs_event`	Filesystem change event
`deregister`	Graceful shutdown notification
`health_response`	Response to on-demand health check
`metrics_response`	Response to on-demand metrics request

Host → Agent

Type	Description
`shutdown`	Initiate graceful shutdown
`health_check`	Request immediate health status
`collect_metrics`	Request immediate metrics snapshot

Building from Source

git clone https://github.com/meshbrow-dev/meshbrow-agent.git
cd meshbrow-agent

# Native build
go build -o meshbrow-agent ./cmd/agent

# Static Linux binary (for containers/VMs)
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o meshbrow-agent ./cmd/agent

Development

go test ./...
go test -race ./...
golangci-lint run

​Browser Agent

​Installation

​Usage

​Configuration

​What It Does

​Health Reporting

​Browser Process Supervision

​Metrics Collection

​Filesystem Watching

​Graceful Shutdown

​Architecture

​Protocol Messages

​Agent → Host

​Host → Agent

​Building from Source

​Development

Browser Agent

Installation

Usage

Configuration

What It Does

Health Reporting

Browser Process Supervision

Metrics Collection

Filesystem Watching

Graceful Shutdown

Architecture

Protocol Messages

Agent → Host

Host → Agent

Building from Source

Development