Install and run

Verchestra is published as one npm package, verchestra. The README’s beta section names the exact current build. Installing it needs no clone, no build, no credential, and no configuration.

npx verchestra@0.0.0-qualification.9 --help

The package provides two equivalent binaries, verchestra and vestra.

This installs the qualification build

The published package installs 0.0.0-qualification. It is not a production release and not 1.0. The signed 1.0 decision is a hold (T77); the candidate keeps operating as 0.0.0-qualification.

What the first run does

The first run does the real work:

1. it checks that your platform and architecture are qualified by the release;
2. it reads the trust root and release source pinned inside the package;
3. it resolves and stages that exact release through TUF, verifying every component byte;
4. it activates the release transactionally behind a health gate; and
5. it hands control to the activated release’s own launcher.

Your ambient Node runs the bootstrap and nothing else. The activated release carries its own Node runtime; npx needs Node 24.14.0 or later to run the bootstrap. Expect a couple of minutes on a cold first run, and a few seconds once a release is activated.

One prerequisite is not bundled: a git binary must be on PATH, because the Self-Test profiles provision their fixtures by invoking git.

Next: deliver a governed task

To take one change from a request file to a reviewed commit on a task branch, with Claude Code implementing and Codex verifying, follow the quick start for a governed task. The governed task path is experimental in this build.

Prove portability on your own machine

npx verchestra self-test --profile smoke

A self_test.verdict: PASS with an empty self_test.failure_codes means this machine resolved and verified a signed release, activated it, and ran the packaged Self-Test profile inside a disposable, isolated trust domain — with no repository checkout anywhere in the journey. The run also reports its check count, duration, and redaction count, and seals a report.

Fixed limitation

The first published release, 0.0.0-qualification, refused self-test when the working directory was an ancestor of the operating system’s temporary directory. On Windows the default home directory is such an ancestor, so a shell opened at its default location failed with VES_CLI_COMMAND_FAILED. Every published release from 0.0.0-qualification.3 on carries the fix (issue #370). A deterministic test reproduces that layout on every platform; no recorded live run has yet started from a default Windows home directory.

Health check

vestra doctor is a read-only health report of the activated release and of this machine. It is not a setup check.

• PASS (exit 0). In a Workspace whose Claude Code credential is bound, a healthy installation reports PASS.

• not-offered. This release does not offer six subsystems, so doctor reports each of them as not-offered. It lists them under doctor.not_offered_capabilities:

  • connectors.available
  • drivers.available
  • policy.enforceable
  • probes.available
  • sandbox.enforced
  • state.durable

  You do not need to do anything for them, and they never change the verdict.

• BLOCKED (exit 4). Something you can set up is missing, such as the Claude Code credential.

Managed state, recovery, and cleanup

The launcher keeps its staged releases, its activated install, its trust anchor, and the active-release pointer under one machine-local state root. Nothing of yours is stored there.

Platform	Managed state root
Windows	%LOCALAPPDATA%\Verchestra\state
macOS	~/Library/Application Support/Verchestra/state
Linux	~/.local/state/verchestra

The launcher derives that location from your home directory and the platform alone. It deliberately reads no environment variable, so redirecting LOCALAPPDATA or XDG_STATE_HOME does not move it and cannot be used to redirect a trust root or a release.

To recover from a failed run, run the command again: activation is transactional and converges. If activation keeps failing, delete the managed state root and run the command again — the next run resolves and activates from scratch.

To remove Verchestra completely, delete the managed state root and clear the downloaded package with npm cache clean --force. The two are independent, and neither touches your own workspace data.