Quick Start

Get OpenFleet running in under 5 minutes. This guide covers install, setup, and your first supervised run.

Prerequisites

Node.js 18+ — Download (v22 recommended)
git — installed and on your PATH
GitHub CLI (gh) — Install (recommended for PR operations)

💡

Run gh auth status to verify your GitHub CLI is authenticated before setting up OpenFleet.

Step 1: Install

npm install -g @virtengine/openfleet

Verify the installation:

openfleet --version
# @virtengine/openfleet v0.26.2

Step 2: Run Setup

Navigate to your project directory and run the setup wizard:

cd your-project
openfleet --setup

The wizard starts with two modes:

Recommended Mode (default)

Prompts only for important decisions
Auto-generates .env based on .env.example with inline docs
Auto-configures VS Code settings for Copilot agent defaults
Sets up proven defaults for hooks, orchestrator, and failover

Advanced Mode

Full control over repository layout and failover strategy
Custom hook targets and event overrides
Explicit VK URL/port wiring
Optional channel and runtime tuning

Key decisions in setup:

Project identity — name and GitHub repo
Executor preset — which AI agents to use and their weights
AI provider credentials — API tokens for your chosen executors
Telegram — bot token and chat ID (optional but recommended)
Board backend — Internal, GitHub Issues, GitHub Projects v2, or Jira
Execution mode — Internal, VK, or Hybrid

Step 3: Launch

openfleet

That's it! OpenFleet connects to your configured board, initializes the agent pool, and starts the supervisor loop.

Run Modes

Foreground (default)

openfleet

Runs in your terminal with live log output. Press Ctrl+C to stop.

Daemon Mode

# Start as background daemon
openfleet --daemon

# Check status
openfleet --daemon-status

# Stop
openfleet --stop-daemon

Startup Service

# Auto-start on login
openfleet --enable-startup

# Check status
openfleet --startup-status

# Remove
openfleet --disable-startup

Interactive Shell

openfleet --shell

Opens an interactive session inside the running monitor for live debugging.

Step 4: Validate

After setup, validate your configuration:

openfleet --doctor

This checks:

.env file presence and validity
openfleet.config.json schema compliance
GitHub CLI authentication
Telegram bot token validity
Executor pool configuration
Kanban backend reachability

What's Next?

Configuration Reference — deep dive into all settings
CLI Reference — every flag and command
Integrations — connect Telegram, GitHub Projects, Jira
Architecture — understand how it all fits together