Getting Started

This guide walks you through installing VulpineOS and launching your first AI browser agent. VulpineOS is an anti-detect browser built for browser automation at scale — each agent gets a unique fingerprint, isolated context, and prompt injection protection out of the box.

Prerequisites

macOS (Apple Silicon or Intel) or Linux (x86_64)
Go 1.26+ — for building the TUI binary
Node.js 22.16+ — for OpenClaw agent runtime
Python 3.10+ — for full fingerprint generation (optional, falls back to built-in profiles)
Make — build orchestration

Installation

Option 1: Build from Source


git clone https://github.com/VulpineOS/VulpineOS.git
cd VulpineOS
 
# Build the browser engine
make fetch     # Download Firefox 146.0.1 source
make setup     # Extract and initialize
make dir       # Apply patches + copy additions
make build     # Compile (artifact builds: ~5 min on M1)
 
# Build the Go binary
go build -o vulpineos ./cmd/vulpineos
 
# Install OpenClaw
npm install

Option 2: Docker (Vulpine-Box)


git clone https://github.com/VulpineOS/VulpineOS.git
cd VulpineOS
export VULPINE_API_KEY=$(openssl rand -hex 32)
docker compose up -d

Then connect from any machine:


vulpineos remote tui --url http://your-server:8443 --api-key $VULPINE_API_KEY

First Run

Launch the local TUI:


./vulpineos
# or
./vulpineos tui

Launch the local panel instead:


./vulpineos panel

vulpineos panel binds to 127.0.0.1, prints a direct panel URL, and opens the browser when possible. If no --api-key is provided, VulpineOS generates a session access key and includes it in the printed panel URL so the panel can log in directly.

On first launch, the setup wizard appears:

Select AI Provider — Choose from 30+ supported providers (Anthropic, OpenAI, Google, xAI, Ollama, and more)
Enter API Key — Paste your API key for the selected provider
Choose Model — Pick the model to power your agents

The wizard saves configuration to ~/.vulpineos/config.json and generates ~/.openclaw-vulpine/openclaw.json automatically.

Creating Your First Agent

Once in the TUI workbench:

Press n to create a new agent
Type a name and press Enter
Type a task description (e.g., “Search for the latest AI news on Hacker News”)
Press Enter — the agent spawns and begins working

The center panel shows the agent’s conversation in real-time. The right panel shows its browser contexts, token usage, and fingerprint profile.

Key Bindings

Key	Action
`n`	New agent
`j` / `k`	Navigate agent list
`Enter`	Send message to agent
`p`	Pause agent
`r`	Resume agent
`x`	Delete agent
`Shift+S`	Open settings
`c`	Reconfigure provider/model
`Tab`	Cycle focus between panels
`q`	Quit

Demo Mode

To explore the TUI without launching the browser engine:


./vulpineos --no-browser

This runs the full interface with simulated data — useful for testing layouts or developing new panels.

Remote Modes

Expose a server with the web panel and remote control API:


./vulpineos serve --host 0.0.0.0 --port 8443 --no-tls

If --api-key is omitted, VulpineOS generates one at startup and prints both the access key and a direct panel URL containing the token.

Open a remote panel from another machine:


./vulpineos remote --url http://your-server:8443 --api-key YOUR_KEY
# or explicitly:
./vulpineos remote panel --url http://your-server:8443 --api-key YOUR_KEY

Connect the remote TUI:


./vulpineos remote tui --url http://your-server:8443 --api-key YOUR_KEY

Next Steps

Architecture — understand the full stack
Injection Filter — how VulpineOS protects agents from prompt injection
MCP Tools — the browser tools available to agents