Getting Started

This guide walks you through installing VulpineOS and launching your first AI browser agent. VulpineOS combines a hardened Vulpine browser runtime with a local TUI, web panel, remote control plane, and browser tools for agents.

Prerequisites

macOS (Apple Silicon or Intel) or Linux (x86_64)
Python 3, unzip, and either curl or wget for the installer
Go 1.26+ only when building the runtime from source
Python 3.10+ and make only when rebuilding the browser engine

Installation

Option 1: One-Line Install


curl -fsSL https://vulpineos.com/install | bash
vulpineos

The installer downloads the latest published vulpineos CLI and matching Vulpine browser bundle for your platform, installs the CLI onto your PATH, and records the browser path in ~/.vulpineos/config.json.

Option 2: 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

Source builds need a Vulpine-compatible browser binary. Use the browser build above, place a packaged Vulpine bundle next to ./vulpineos, or pass one explicitly with --binary /path/to/vulpine.

Option 3: 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 --url http://your-server:8443 --api-key $VULPINE_API_KEY

First Run

Launch the local TUI:


vulpineos
# or, from a source build:
./vulpineos

Launch without a browser for configuration or layout checks:


vulpineos --no-browser

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 prepares the local agent runtime workspace automatically.

Creating Your First Agent

Once in the TUI workbench:

Type a task directly in the chat input.
Use /new when you want to create another agent.
Use /agents to open the agent picker.
Click an agent in the left column to switch conversations.

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

Main Controls

Type in the chat input and press Enter to send.
Type / to open the command palette.
Use ↑/↓ and Enter to choose a command.
Use Esc to close menus or cancel selection.
Click agent rows to switch agents.
Use the mouse wheel over the chat or agent list to scroll.
Use /settings, /config, /view, /hide, /log, /trace, /copy, and /quit for workbench actions.
Ctrl+C remains an emergency quit path.

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.

Open the printed panel URL in a browser from another machine.

Connect the remote TUI:


./vulpineos remote --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