Installing Virgo
Release status: Virgo is in release preparation. There is no public downloadable installer at this documentation snapshot. The operator example below assumes an already supplied, verified preview release. It is not a download or general-availability announcement.
The installation contract
Install a Hub for shared authority and durable records. Install or enroll a Host on each machine that will run provider conversations. Hub and Host may run on the same machine, or Hosts may connect to a remote Hub.
Hub/Host installation and update must supply the common MCP, skills, rules, Ponytail, memory and Graphify resources and their supported connections. Users should not separately clone those projects, install a second server for each feature, or hand-wire each Seat. Feature policy and provider login/trust are distinct from installing the capability.
The target completion check is to open an ordinary supported conversation beneath the Virgo root, claim an authorized Seat and receive a native message. Repeating that with a new conversation must not require new Seat files or a Host restart.
Current preview source does not yet complete that journey. Automatic common provider setup, dynamic claim attachment, full feature wiring and automatic cross-Host updates remain implementation gaps.
What an installation needs
- A compatible Virgo release with an exact artifact identity and manifest.
- Bun available to the native runtime and CLI. Use the release's tested runtime version; a TypeScript type-package version is not a runtime requirement.
- Docker and available service ports on a machine installing a local Hub's PostgreSQL and JetStream services. Remote Hosts use the Hub API rather than connecting directly to these databases.
- Write access to the chosen Virgo root, normally
~/virgo, and read access to the selected release source. - Supported provider executables, provider account access and required trust on the machine that will run those conversations.
- For a remote Host, a reachable HTTPS Hub endpoint and authorized Host enrollment. Network connectivity alone does not establish a Virgo identity.
Artifact availability must be checked for the selected operating system and architecture. Source platform checks do not prove that a corresponding public binary has been released.
Current preview: install a local Hub
This is an operator reference for the implemented CLI. Replace the placeholder values with the verified release and manifest directory supplied for the preview. The command creates a local Hub; it does not make an unconfigured provider Seat ready or complete the integrated-feature acceptance above.
VIRGO_BIN="/absolute/path/to/verified-release/bin/virgo"
VIRGO_ROOT="$HOME/virgo"
VIRGO_RELEASE="REPLACE_WITH_EXACT_RELEASE_ID"
VIRGO_MANIFESTS="/absolute/path/to/verified-manifests"
VIRGO_MACHINE="my-machine"
"$VIRGO_BIN" install --mode local \
--root "$VIRGO_ROOT" \
--release "$VIRGO_RELEASE" \
--machine "$VIRGO_MACHINE" \
--manifest-directory "$VIRGO_MANIFESTS"Use exactly one distribution source. Authorized preview operators may replace --manifest-directory with --github-repository virgo-codes/virgo-release when they have access to that release repository. This is access to a distribution source, not proof of public download availability.
The installer returns the exact installationDirectory. Preserve that value and the selected release and plan receipts. Do not construct the encoded instance path by hand. The installation owns database storage under its root and verifies the selected artifact before activation.
The local preview above remains separate from the new additional-Host installation and update procedure. That procedure uses install --mode host with an existing Hub and a canonical release bootstrap. Its source implementation and isolated installation tests exist; publication of the matching CLI, bootstrap and release metadata is still required at this snapshot. Do not run those commands against an older release.
Current preview gaps
| Boundary | Current state |
|---|---|
| Same-machine Host | The local installer can additionally create a Host from operator-prepared adapter and Host-settings files. This is the current preview path, not the intended zero-preparation Seat flow. |
| Provider MCP setup | Generated registration material still requires external provider registration and a configured principal. A generated file is not an active MCP connection. |
| Ordinary Seat claims | Existing provider/session bindings remain prerequisites. The complete dynamic claim-first path is pending. |
| Integrated features | Bundled code/resources do not yet establish automatic installation and functioning native hooks, memory derivation or Graphify retrieval. |
| Multi-Host updates | Local package installation exists; automatic propagation and reconnect convergence are not yet accepted. |
These gaps belong in the implementation and release acceptance. They do not redefine the product as a collection of separately installed plugins.
Verify completion from the bottom up
- Verify the installed artifact and configuration match the selected release.
- Confirm the exact running process and its protocol health.
- Confirm the provider actually discovers the common MCP and expected tools.
- Claim an authorized Seat and inspect its actual session, Host and delivery state.
- Send a fresh native message, observe receipt in that session and verify the reply relation. Repeat the required reconnect case.
- Exercise each enabled capability at its real entrypoint: guidance injection, memory capture through restore, and repository extraction through retrieval.
An installation state of active or an HTTP health response proves only its own boundary. See operations and validation for the complete checks.