Virgo overview

Virgo

Virgo turns multiple AI agents into a working team. Resident personas message one another through the hub, route tasks and decisions, delegate from leads to deputies, consolidate through a secretary, and involve the owner at explicit approval gates. Continuity is what makes that collaboration compound instead of starting cold every turn.

Each persona is a native interactive session, not a repeated headless prompt. It stays resident, accumulates context, memory, and conversation, and can be anchored to a repository as that project's persistent lead.

virgo is the single entrypoint CLI. Everything — machine onboarding, persona lifecycle, hub services, status — is a subcommand:

virgo onboard              # prepare a machine to host personas
virgo workspace add <name> # add an isolated work domain
virgo persona add [name]   # register a resident role path and CHARACTER.md
virgo persona up <name>    # restore & activate a persona from the central store
virgo persona down <name>  # checkpoint & stop safely
virgo hub start            # run hub services (transport, store, human-surface relay)
virgo status               # machines / personas / fences at a glance
virgo init                 # scaffold YOUR canon (classes, base, people)
virgo skill list           # inspect persona, class, and workspace work skills

The public installer resolves and installs one exact release SHA:

curl -fsSL https://virgo.codes/install.sh | sh
virgo onboard
virgo init
virgo persona add
virgo persona up <name>

Persona creation suggests a Virgo-constellation name, defaults the first persona to the secretary class, and lets you describe its personality—or start with the class's sensible default. Language and tone are optional; deeper fine-tuning lives in the hub's Personas screen.

Persona addresses are role paths. root/secretary and home/secretary are scope-wide; work/core/lead is project-bound. root is reserved for the owner-facing secretary and system operator. No placeholder segment is used.

First usable command: virgo onboard

The onboarding wizard turns the machine-onboarding checklist into measured, resumable state. It currently supports macOS targets over key-only SSH (or local) and deliberately does not install credentials.

Its first persisted choice is whether this is the owner's first machine, which becomes the hub, or a machine joining an existing hub address.

# First run: answer the machine/profile questions interactively.
bun run src/cli.ts onboard

# Repeatable, unattended inspection from a saved profile.
bun run src/cli.ts onboard --profile ./machine.json --inspect

# Preview what would be recorded without changing any file.
bun run src/cli.ts onboard --profile ./machine.json --dry-run

Every run measures the target before reporting a missing step. A normal run writes a private 0600 onboarding manifest and resumes from it later. A run with --profile never prompts: human-only checkpoints remain visibly waiting until the saved profile records the decision. This makes re-provisioning replayable without pretending that credential placement, OS permissions, or the first persona activation can be automated.

The stages mirror the operator procedure: role/scope, network and SSH, absolute tool paths, immutable runtime release and launchd services, loopback store access, registration and eligibility, credential decisions, then first-session trust and persona-up approval. Start from examples/machine-profile.macos.json.

On macOS, onboarding also runs a bounded protected-folder read through the same noninteractive SSH and absolute Bun path that personas use. If TCC blocks that path, the manifest pauses at a distinct Full Disk Access stage and guides the operator to System Settings. It advances only after the identical probe passes; a recorded click or an unobserved GUI dialog is never treated as proof.

Greenfield hub runtime

The first hub service is a pinned FalkorDB/Redis container with Redis Streams, graph storage, AOF, and RDB persistence. It binds only to loopback and keeps its data, generated ACL, and generated password under one private 0700 state directory. The password is never printed or stored in the repository.

Copy examples/hub-config.macos.json to the machine's private Virgo configuration directory, replace the release SHA, container-engine path, and state path with measured values, then set the file to mode 0600:

virgo hub start  --config /absolute/path/to/hub.json
virgo hub status --config /absolute/path/to/hub.json
virgo hub stop   --config /absolute/path/to/hub.json

The running container is labeled with the same release SHA as the rest of the Virgo release and with a hash of its strict configuration. start resumes an exact stopped container without replacing its persistent data. It refuses a container whose image, release, configuration, mount, restart policy, or loopback port binding differs. status is read-only and reports unhealthy, stopped, absent, and specification-mismatch states instead of calling them running. stop is idempotent and preserves the container and data for restart.

Design principles (day one, non-negotiable)

1. One release SHA. Hub services, machine runtime, and tooling ship as one hash. Version skew between components is a bug class we refuse to have.
2. No owner-specific hardcoding. Machine addresses, workspace names, people, and paths live in the user's private canon/config, stamped at persona creation — never in this codebase. Virgo is the public tool; your canon and personas are your private data (virgo init creates yours).
3. Mechanisms over documents. Invariants (single active copy, audit-gated lifecycle verbs, process-bound identity) are enforced by tooling that refuses, loudly — not by agreements that get breached under time pressure.
4. Loud failure over false-running. A component that cannot prove its state refuses to act. Recovery is first-class: fenced single-writer identity, checkpoint/restore, and autonomous restart are the core, not add-ons.