Configuration

OpenFleet uses a layered configuration model with multiple sources. Higher-priority sources override lower ones. There are 200+ configuration variables across 30+ categories — all of them optional unless marked [REQUIRED].

Load Order (Highest Priority First)

1. CLI flags — --arg value
2. Environment variables — export VAR=value
3. .env file — dotenv format in your project root
4. openfleet.config.json — structured JSON config
5. Built-in defaults — sensible zero-config values

Configuration Files

.env — Environment Settings

The primary configuration file. Generated by openfleet --setup with inline documentation. All variables are optional unless marked [REQUIRED].

openfleet.config.json — Structured Config

For complex executor routing, failover, and multi-repo setups:

{
  "$schema": "./openfleet.schema.json",
  "projectName": "my-project",
  "executors": [
    {
      "name": "copilot-claude",
      "executor": "COPILOT",
      "variant": "CLAUDE_OPUS_4_6",
      "weight": 50,
      "role": "primary",
      "enabled": true
    },
    {
      "name": "codex-default",
      "executor": "CODEX",
      "variant": "DEFAULT",
      "weight": 50,
      "role": "backup",
      "enabled": true
    }
  ],
  "failover": {
    "strategy": "next-in-line",
    "maxRetries": 3,
    "cooldownMinutes": 5,
    "disableOnConsecutiveFailures": 3
  },
  "distribution": "weighted"
}

Task Claims & Coordination

Shared state enables distributed task coordination across multiple agents and workstations with atomic claims, heartbeat liveness, and conflict resolution.

Project Identity

Executor Configuration

Executor Shorthand Syntax

EXECUTORS=ENGINE:VARIANT:WEIGHT,ENGINE:VARIANT:WEIGHT

# Examples:
EXECUTORS=COPILOT:CLAUDE_OPUS_4_6:50,CODEX:DEFAULT:50
EXECUTORS=CODEX:DEFAULT:100
EXECUTORS=COPILOT:GPT_4_1:30,COPILOT:CLAUDE_OPUS_4_6:40,CODEX:DEFAULT:30

Failover Configuration

Controls what happens when an executor fails repeatedly.

Internal Executor

Controls local task execution via agent-pool instead of (or alongside) VK's cloud executor.

SDK Transport

Kanban / Task Board

Task-board backend selection and sync policy. Supports internal store, GitHub Issues, GitHub Projects v2, and Jira.

GitHub Issues Backend

GitHub Projects v2 Status Mapping

GITHUB_PROJECT_STATUS_TODO=Todo
GITHUB_PROJECT_STATUS_INPROGRESS=In Progress
GITHUB_PROJECT_STATUS_INREVIEW=In Review
GITHUB_PROJECT_STATUS_DONE=Done
GITHUB_PROJECT_STATUS_CANCELLED=Cancelled

GitHub Projects v2 Webhooks

Jira Backend

Full Jira Cloud integration with status mapping, custom fields, and ADF comments.

Jira Status Mapping

JIRA_STATUS_TODO=To Do
JIRA_STATUS_INPROGRESS=In Progress
JIRA_STATUS_INREVIEW=In Review
JIRA_STATUS_DONE=Done
JIRA_STATUS_CANCELLED=Cancelled

Telegram Bot

Full bot with 30+ commands, inline keyboards, and rich notification system.

Notification Batching

Telegram Mini App

7-tab web dashboard: Dashboard, Tasks, Agents, Infra, Control, Logs, Settings.

Cloudflare Tunnel

Provides persistent HTTPS for the Mini App. Two modes:

• Quick tunnel (default): Random *.trycloudflare.com URL, no setup required. URL changes on restart.
• Named tunnel: Custom domain that never changes. Requires Cloudflare account.

Telegram Sentinel

Independent watchdog that maintains Telegram command availability even when openfleet is down. Can auto-restart, detect crash loops, and run repair-agent.

Presence & Multi-Instance

Discover multiple openfleet instances across machines.

WhatsApp Channel

Optional notification/command channel using @whiskeysockets/baileys.

Container Isolation

Run agent tasks inside Docker, Podman, or Apple Container for security isolation.

Codex SDK

Sandbox Policy

Feature Flags

AI Provider / Model

Copilot SDK

GitHub Copilot CLI integration with full model access, MCP tools, and sub-agents.

Claude SDK

Claude Code integration for autonomous agent operations.

Agent Pool

Ephemeral agent pool for concurrent operations.

Agent Hooks

Lifecycle hooks scaffolded across Codex, Claude, and Copilot agents. Configured in .codex/hooks.json, .claude/settings.local.json, and .github/hooks/openfleet.hooks.json.

Per-Event Command Overrides

OPENFLEET_HOOK_PREPUSH=go vet ./...;;go build ./...
OPENFLEET_HOOK_PRECOMMIT=gofmt -l .
OPENFLEET_HOOK_TASK_COMPLETE=echo "task completed"
OPENFLEET_HOOK_SESSION_START=echo "session start"
OPENFLEET_HOOK_SESSION_STOP=echo "session stop"

Daemon Mode

Run openfleet as a background daemon with crash supervision.

Vibe-Kanban

GitHub

Merge Strategy

Codex-powered PR decision engine analyzing agent output to decide: merge, prompt, close, re-attempt, review, or wait.

Autofix Mode

Task Planner

Complexity Routing

Automatically select AI models based on task size labels: [xs], [s], [m], [l], [xl], [xxl].

CI Sweep

Dependabot Auto-Merge

Stale Task Recovery

GitHub Issue Reconciler

Periodically reconciles open GitHub issues against open/merged PRs with hybrid close policy.

Completed Task Archive

Git Identity

Agent Work Logging & Analytics

Structured logging for real-time monitoring and offline analysis, with error loop detection and stuck agent alerts.

Detection Thresholds

Prompt Overrides

OpenFleet scaffolds generic prompt templates under .openfleet/agents/*.md. Override paths:

Advanced Settings

Recommended Profiles

Local Development

DEVMODE=true
DEVMODE_MONITOR_MONITOR_ENABLED=true
CODEX_TRANSPORT=sdk
COPILOT_TRANSPORT=sdk
CLAUDE_TRANSPORT=sdk
EXECUTOR_MODE=internal
KANBAN_BACKEND=internal

Production / End-User

DEVMODE=false
DEVMODE_MONITOR_MONITOR_ENABLED=false
CODEX_TRANSPORT=sdk
COPILOT_TRANSPORT=sdk
CLAUDE_TRANSPORT=sdk
EXECUTOR_MODE=internal
KANBAN_BACKEND=github
KANBAN_SYNC_POLICY=bidirectional