dvoid docs
WorkbenchGuides

Machine checks and recovery

Diagnose and repair your machine, your dvoid installation and your fleet access, and see where a machine's configuration comes from.

dvoid-io/workbench · partner

New here? Set up first with Getting started: you sign in with dvoid login and your org's slug through --org before you bootstrap. Signing in does not fetch your org's workspace defaults; dvoid bootstrap and dvoid update do. If the repo picker is empty, check dvoid estate config show and dvoid estate.

Diagnose

Start with dvoid version, dvoid self and dvoid doctor --fresh. Doctor compares the machine with its spec and exits 1 when it has drifted; that exit is a result, not a failure of doctor. dvoid bootstrap --plan previews what would change; dvoid update converges the machine and may change tools and configuration. A plan is not proof of what is installed.

The Assistant and the fleet

The Assistant needs pi and Node on your PATH; dvoid bootstrap installs your machine's declared toolchain if either is missing. When the fleet is not set up yet, the Assistant runs dvoid llm setup --lease itself. If the fleet refuses your lease, your admin has to add your LiteLLM row (the health screen's Copy request asks for it). dvoid llm check proves the fleet answers on your key (models, a chat and a streamed completion, with the lease revoked after) and names the cause when it does not. Never paste keys into chat or pass them as command arguments.

Your dvoid installation

Advanced / Troubleshoot → This dvoid shows the running installation and where your PATH points; an irregular installation also shows in the console header.

  • dvoid self shim selects the canonical source shim (or a checkout path you give it). On Linux and macOS it usually lives at ~/.local/bin/dvoid, pointing at the canonical workbench clone; dvoid update can point it back there after you test a worktree's shim.
  • dvoid self binary installs the release executable.
  • dvoid self reset restores what your machine class expects.

These take effect on the next run; a console that is already running keeps its code. Windows uses the release executable; switching to a source shim is Unix-only.

Where a machine's configuration comes from

Three layers, each later one winning: built-in, then org, then personal.

  • Built-in: dvoid's own classes (partner-dev, partner-secure-dev) and every installer, shipped in the binary from workbench (core/bootstrap/classes/, bootstrap/installers.ts).
  • Org: your org's config repo, if it has one. machines/classes/ (each class include:s a built-in and adds only what differs), machines/profiles/ (what a role adds) and the org's dotfiles at the root (applied with chezmoi; .chezmoiignore keeps machines/ out). dvoid clones it to ~/.dvoid/cache/org-config/<org> and trusts it only while its origin is the URL your org registered. dvoid doctor and dvoid bootstrap --plan name the source in use.
  • Personal: ~/.config/dvoid/machine.toml, the profiles this machine takes and a [local] table for this hardware alone. dvoid machine show, dvoid machine save and dvoid machine restore manage it; it never goes in git.

Changing it

  • For your whole org (a package, a profile, a new class): edit your org's config repo, check it with dvoid machine lint from that repo, and open a pull request there.
  • Your org has no config repo yet: dvoid machine config init, with your org's slug as --org and the new owner/repo as --create, writes a starting repo (a class including a built-in, an example profile, a README) and creates it on GitHub with gh (check gh auth status first). Then ask your org's staff to register it; the command prints what they need.
  • A fix every org should have (a broken installer, a better default): a pull request on dvoid-io/workbench.
  • This machine only: the [local] table in machine.toml.

On this page