# Companion

> An open-source CLI tool for launching and managing fleets of task-optimized AI agents with tools, memory, and private Tailscale networking.

Companion is an open-source, MIT-licensed tool by The Vibe Company that lets developers go from "I need several specialized agents" to a running fleet they can actually use. Each agent in a fleet gets its own role, tools, memory, runtime, and private access. The project is hosted on GitHub under The-Vibe-Company organization and is available as a compiled Go binary for Linux and macOS.

## What It Is

Companion is a CLI-driven agent fleet manager. It treats a local folder as the source of truth — a set of TOML files describing providers, agents, vaults, networking, and identity — and compiles that desired state into typed resources, compares it with observed provider state, and applies changes idempotently. The result is a reproducible, copyable workspace that can be adapted per client, team, or use case without rebuilding the ops stack from scratch.

## How the Fleet Model Works

A Companion workspace defines one or more named agents, each with its own:
- **Identity** — a `SOUL.md` file that sets the agent's persona and memory policy
- **Model** — routed through OpenRouter with optional catalog validation
- **Runtime** — deployed as a Fly.io app with a persistent volume and secrets bundle
- **Memory** — Granite vaults for durable, cross-agent shared memory
- **Private networking** — reachable only through Tailscale VPN, not the public internet
- **Chat surface** — Open WebUI connected to enabled Hermes API servers in the fleet

The CLI loop is: edit TOML → `companion validate` → `companion plan` → `companion apply`.

## Architecture and Toolchain

Companion is written in Go. The binary embeds the status dashboard UI (`go:embed`), so there is no separate frontend build step. State is stored in a local SQLite file (`.companion/state.sqlite`) as evidence, not desired config. Resource addresses are deterministic (e.g., `fly_app.agent.<id>`), making plans readable and repeatable. Provider e2e tests use local `httptest.Server` mocks for Fly, Tailscale, and OpenRouter.

Key infrastructure integrations:
- **Fly.io** — agent app deployment, volumes, secrets, rollouts
- **Tailscale** — private mesh networking and hostname drift checks
- **OpenRouter** — model routing and provider references
- **Granite** — durable vault memory with MCP read/write roles
- **Open WebUI** — shared chat frontend backed by fleet API servers

## Deployment Model

Companion supports three deployment patterns: a local CLI against a workspace directory, a remote control plane (a persistent Fly app running `companion console` with a mounted volume), and a deployed dashboard (a stateless Fly app reachable only over Tailscale). The control plane tracks multiple workspaces in `~/.companion/workspaces.json` and supports upgrade, export, and status commands. Secrets are read from `.env` or the shell environment; Companion prints secret names only, never secret values.

## Update: v0.2.0

The latest release is v0.2.0, published in June 2026. The GitHub README notes that the previous Companion web UI codebase has been archived at `archived/legacy-companion/`, and Companion is now the Go control plane described in the current README. Release Please manages version PRs, changelog updates, tags, and GitHub Releases; release assets contain a single `companion` binary for Linux and macOS. The repository has accumulated over 2,300 stars and nearly 300 forks since its creation in early 2026, according to GitHub metadata.

## Features
- Launch fleets of task-optimized AI agents
- Per-agent identity via SOUL.md files
- Durable Granite vault memory with cross-agent sharing
- Private Tailscale networking for agent isolation
- OpenRouter model routing and catalog validation
- Open WebUI shared chat surface for fleet
- TOML-based declarative workspace configuration
- Idempotent apply with deterministic resource addresses
- SQLite state evidence store
- Live fleet status dashboard (embedded UI)
- Control plane deployment on Fly.io
- CLI commands: init, validate, plan, apply, output, dashboard
- Explicit destroy with backup-first option for persistent data
- Import existing provider resources into state
- Drift detection for Tailscale and Fly resources
- Versioned agent identities and vault connections
- Release Please managed versioning and changelogs

## Integrations
Fly.io, Tailscale, OpenRouter, Granite, Open WebUI, Hermes, GitHub Actions

## Platforms
MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v0.2.0

## Links
- Website: https://thecompanion.sh
- Documentation: https://github.com/The-Vibe-Company/companion
- Repository: https://github.com/The-Vibe-Company/companion
- EveryDev.ai: https://www.everydev.ai/tools/companion-vibe-company