# Console and the Assistant (https://docs.dvoid.io/workbench/guides/console)



Start the console with `dvoid console` (bare `dvoid` opens it too). Its menu is generated from the
CLI's commands, so what you see depends on your machine: its harnesses, profiles and workstreams.
Selecting an action does not run it; you press Enter.

## The menu [#the-menu]

The sections are **Quick agents**, **Workstreams**, **Estate (Repos)**, **Setup** and
**Advanced / Troubleshoot**. **Advanced / Troubleshoot → Health check** lists account and machine
problems with their fixes and a request you can copy to your admin; the header's "⚠ N issues"
opens it too.

Menus and choice screens have a Search box: click it, or press `/` in a menu. Arrows browse the
matches, Enter opens one, and Esc clears the filter before it goes back. Ctrl+G, a left-click or a
right-click opens the organization and project dropdown where there is one; your current
workstream is first and marked `here`, and a repo's aliases share one choice. The shortcuts
along the bottom are clickable, and the active pane and editor are tinted.

## The top strip and workspaces [#the-top-strip-and-workspaces]

Across the top: Commands (the command palette, Ctrl+G, or Ctrl+Shift+P where your terminal
reports Shift; never Ctrl+P or Ctrl+K), the Home and Settings tabs, then your workspace tabs, with
`+ New` after the last one shown and the rest behind `+N ▾`. `o` opens Console windows. Home holds
the command menu and context-first Layouts. New empty console starts separate work with its own
saved state.

A workspace tab's right-click has New workspace, Layouts… (the context and layout desktop),
Rename, Close, Color… (which marks the tab and its companions) and the rest:

* Pop out workspace gives the workspace a window of its own. Its panes and Files move there while
  this console keeps running them; its tab here shows a card with Focus it and Bring back.
  Closing that window, or Bring back, returns everything.
* Move to console (or Move to new console) hands the workspace to another console. A confirmation
  lists what restarts there: shells in their folders (ending what runs in them), agents resuming
  their exact conversations, pages reopening, the Assistant starting over. An unsaved editor
  blocks the move.

A companion window shares its primary's workspace. Closing a companion returns its views; closing
the primary ends its shells, browsers and companions. Switching workspaces never closes a
companion: one whose workspace is not shown dims and offers `Show in primary` (click, or
Ctrl+G p).

## Files [#files]

F3 toggles the workspace's one Files navigator. Its root is the workspace's context; changing a
shell's directory does not move it, and Back/Forward navigate within that root. Enter or Right
expands a folder; Left collapses it or selects its parent. Search filters the loaded branches; F2
switches between list and preview. Dotfiles are listed; the eye on `Hidden` (Ctrl+H) hides them.
`Go ▾` holds the path field (Ctrl+L), Home, the workspace root and your bookmarks.

Right, Tab, Ctrl+E or a click on a file's preview opens it in a basic editor beside the tree;
Shift+Tab returns to the tree and leaves the file open. Ctrl+S saves, Ctrl+Z undoes, and Esc
closes after offering Save, Discard or Cancel. Ctrl+Shift+E opens your external editor and
returns. The editor takes UTF-8 files up to 128 KiB and notices changes on disk.

The preview tab (an italic filename, or Welcome) is replaced by the next file you preview, never
when it holds unsaved work. Double-click, Keep Open, editing or moving it keeps it. Split out makes
a new group; Join moves a tab into a neighbouring one. Files cannot detach. In a popped-out
workspace, its window has the Files.

## The Assistant [#the-assistant]

Every workspace has its own Assistant (F4 there): its own conversation, draft and model, started
when you first use it and ended when the workspace closes. It sees and reaches only that
workspace's panes. Home's docked Assistant has no terminal or browser tools.

* The integrated terminal (F5) belongs to Home; no Assistant reaches it.
* Tab opens it and switches between chat and menu; on a short screen chat takes the body and Tab
  shows the menu. F4 or `Minimize` hides it, even mid-reply; the alien avatar brings it back.
  Ctrl+F or `Expand / Restore` resizes it.
* Enter sends; Shift+Enter or Alt+Enter adds a newline (Ctrl+J also works). The wheel or
  PageUp/PageDown scroll, Shift+Up/Down scroll a line, Ctrl+Home/End jump. Click the transcript to
  scroll with the arrows, or the composer to edit with them.
* `Show result / Hide result` expands a tool's output; Ctrl+O shows the latest one. Esc stops a
  reply, otherwise collapses chat. Ctrl+N starts a new chat. F2 shows the menu preview when narrow.
* The header's `Model` button (or Ctrl+L) lists the fleet models your own key reaches and
  switches between turns; your choice is remembered.

Choice chips sit above the composer: starters in an empty chat, then 2–4 next steps after each
reply. Click one or press Alt+1–4 to send it; your draft is kept. On macOS, Alt needs your
terminal's "Option as Meta" setting; clicking always works.

To copy, drag to highlight, then Ctrl+C or `Copy` (Ctrl+Shift+C where your terminal forwards it);
your terminal must allow clipboard writes. Ctrl+A or `All` selects the whole input. Right-click
(or Shift+F10) offers Select all, Copy, Paste and a short in-memory history of what you copied.
Get help with this drafts a chat message for you to review; it never sends by itself.

The Assistant reads freely, but every change it proposes shows the complete command above
Decline and Allow once. Enter declines at first; Y allows once, N or Esc declines. Reading or
typing into one of your terminals asks the same way, showing the lines or the exact keys. Drafts
and chat survive navigation and terminal handoffs; quitting or logging out ends the chat.

Secrets, sign-in and enrollment stay with you. The secrets browser is private: the Assistant
cannot look at, navigate or run anything there. Never paste a credential, a secret screenshot or
clipboard contents into chat.

## Agents in your panes [#agents-in-your-panes]

Claude Code, Codex and the rest run in terminal panes. An agent there reads where it stands with
`dvoid console context` (`--json` for data): the pane and workspace, the workstream, machine
class, sign-in and harness, and the commands that apply, each naming its guide. `dvoid console docs`
lists these guides and prints one by topic.

An agent may ask for a Browser pane beside its own with `dvoid console browser`. The console shows
you who asks, the URL and the identity (your remembered profile, a copy of one of your Chrome
profiles signed in as you, or a fresh one); nothing opens until you allow it, and a request you
decline or leave for two minutes is refused.

When something is wrong, start with `dvoid console context`, then the guide it names, then
`dvoid doctor`.

### Requests waiting on your other machines [#requests-waiting-on-your-other-machines]

The Inbox also lists requests waiting on your other machines (`On <host>`). You can read the
conversation that led to one, but you can only answer it on the machine where it waits. To read it,
pair this machine with that console once:

1. On that machine, open Settings › Paired devices › Pair a device…. It shows a 6-digit code for
   5 minutes.
2. Here, on its row, choose Pair to read (P) and type the code.

Each code allows one try: a wrong guess uses it up, so ask for a new one. What is read is redacted on
the machine where the request waits, sealed so that only this device can open it, and never stored
here. Settings › Paired devices lists the devices a machine answers, and Remove ends a device's
access. Settings › Console › Answer my other devices turns answering off altogether.

## Reopening and layouts [#reopening-and-layouts]

Reopening restores paths, browser pages and fresh shells, never previous jobs. An agent pane
resumes its exact saved conversation; one that was never used starts fresh; one that cannot be
verified asks you first, never guessing. Reopening a primary relaunches the companion windows of
the workspace it shows; other workspaces' come back the first time you show them. A popped-out
workspace reopens as its card, and its window opens when you first show that tab.

Save as layout exports a portable recipe you review first. It leaves out environment,
credentials, running processes and monitor positions.


# Customizing: templates, playbooks, layouts, workspaces (https://docs.dvoid.io/workbench/guides/customize)



"I always open these three repos together", "every security job should start with these
instructions", "I want the terminal under the files": each of these is one of four things you can
shape.

| noun        | means                                                                                                  | lasts | your own copy lives in                        |
| ----------- | ------------------------------------------------------------------------------------------------------ | ----- | --------------------------------------------- |
| *template*  | what a workstream starts from: repos, and optionally the layout it opens in                            | yes   | `~/.config/dvoid/estate.toml` `[[templates]]` |
| *playbook*  | how the work is done: the `AGENTS.md` it seeds (`{{goals}}` etc. substituted), its plugins, its layout | yes   | `~/.config/dvoid/playbooks/<name>.json`       |
| *layout*    | an arrangement of console panes, paths relative to `${root}` so it fits any workstream                 | yes   | `~/.config/dvoid/console/layouts/<slug>.json` |
| *workspace* | the live arrangement for one workstream, folder or Quick; closes with it                               | no    | the console's state, never shared             |

Each kind layers the same way: *built-in* (shipped with dvoid) \< *org* (what your org's staff
manage) \< *personal* (`~/.config/dvoid/`, yours). A later layer wins a name, and a personal
`remove = true` hides something a lower layer carries.

## See what you have [#see-what-you-have]

```sh
dvoid estate config show --json        # repos and templates, and the layer each came from
dvoid workstream playbook list --json
dvoid workstream playbook show <name>
```

## Change it [#change-it]

```sh
# a template
dvoid estate config template set <name> --repos a,b [--layout <id>] [--description "…"]
dvoid estate config template remove <name>   # drops yours; an org's is hidden on this machine
# the repos every sweep includes
dvoid estate config repos add a,b
dvoid estate config repos remove a,b
# a playbook (one named like an org's or a built-in replaces it on this machine)
dvoid workstream playbook set <name> --describe "…" --agents-md "…" [--plugins a,b] [--layout <id>]
dvoid workstream playbook remove <name>
# a workstream from them
dvoid workstream new --template <t> --playbook <p>
```

Run `show` or `list` again to see the result. The Assistant can make these changes for you; each
one asks you first and shows the exact command.

Layouts are made in the console: ⋯ → Save workspace as layout, or Ctrl+G then `s`. It asks for a
name and saves the layout relative to the workstream, so it fits the next one. The desktop
(Ctrl+G `d`) opens, favourites, reorders and hides layouts.

## Personal or org? [#personal-or-org]

* Personal when it is yours, an experiment or a preference. This is the default, and reversible.
* Org when everyone in your org should start from it: a template every new teammate needs, the
  playbook a kind of work must follow, a layout the team shares. You cannot change the org layer
  from your machine; your org's staff do. Ask the Assistant to draft the exact entry, then send it
  to them.

## Old words, still heard [#old-words-still-heard]

Everything older keeps working; dvoid prints one `hint:` line with the new word.

| you may say                                     | it is now                                                                                  | the old way                                                |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| taskgroup, `--group`, `[[taskgroups]]`          | *template*, `--template`, `[[templates]]`                                                  | works; `dvoid estate config migrate` rewrites the file     |
| workstream type, `--type`, `"type"` in a record | *playbook*, `--playbook`, `"playbook"`                                                     | works; `dvoid workstream migrate --apply` rewrites records |
| F12                                             | Ctrl+G (the Commands key, configurable; Ctrl+Shift+P too where the terminal reports Shift) | works; the Commands title names the key                    |
| "session" (old name for a workstream)           | *workstream*                                                                               | `dvoid workstream migrate` moves the old folders           |

## Read more [#read-more]

* [Workstreams and harnesses](./workstreams.md) and [Machine checks and recovery](./machine.md)
  (where a machine's configuration comes from).
* The console spec, [§ Templates and contexts and § Layouts](https://github.com/dvoid-io/workbench/blob/main/specs/07-console-workspaces.md),
  and the [workstreams spec](https://github.com/dvoid-io/workbench/blob/main/specs/02-workstreams.md).
* [LEXICON](https://github.com/dvoid-io/agent-extensions/blob/main/context/LEXICON.md): one meaning
  per word (template, playbook, layout, workspace, workstream, seed).
* `dvoid --help`, `dvoid estate config --help` and `dvoid workstream playbook --help` for the exact
  flags on your build.


# Getting started (https://docs.dvoid.io/workbench/guides/getting-started)



dvoid installs as one release binary on macOS, Linux (Debian, Ubuntu or Mint) and native Windows.
It includes the console and needs no Bun or Node. The releases are on GitHub and need access to
the `dvoid-io` repositories: accept the invitations your org sent you first.

## 1. Install Git and the GitHub CLI [#1-install-git-and-the-github-cli]

<CodeBlockTabs defaultValue="macOS">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="macOS">
      macOS
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Linux">
      Linux
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Windows">
      Windows
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="macOS">
    ```sh
    # Homebrew first (https://brew.sh), following its printed shell setup
    brew install gh
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Linux">
    ```sh
    sudo apt update && sudo apt install -y git gh
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Windows">
    ```powershell
    winget install --id Git.Git --exact --source winget
    winget install --id GitHub.cli --exact --source winget
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Open a new terminal, then sign git in to GitHub (every OS):

```sh
gh auth login
gh auth setup-git
```

Skipping `gh auth setup-git` makes every private clone fail later.

## 2. Install dvoid [#2-install-dvoid]

The installer picks the release for your OS and CPU, downloads it through `gh` and prints
`dvoid version`. It refuses to overwrite an existing install; use `dvoid update` for that.

<CodeBlockTabs defaultValue="macOS">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="macOS">
      macOS
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Linux">
      Linux
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Windows">
      Windows
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="macOS">
    ```sh
    dvoid_installer=$(mktemp)
    gh api repos/dvoid-io/workbench/contents/install.sh -H 'Accept: application/vnd.github.raw+json' > "$dvoid_installer" && sh "$dvoid_installer"
    rm -f "$dvoid_installer"
    export PATH="$HOME/.local/bin:$PATH"
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Linux">
    ```sh
    dvoid_installer=$(mktemp)
    gh api repos/dvoid-io/workbench/contents/install.sh -H 'Accept: application/vnd.github.raw+json' > "$dvoid_installer" && sh "$dvoid_installer"
    rm -f "$dvoid_installer"
    export PATH="$HOME/.local/bin:$PATH"
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Windows">
    ```powershell
    # PowerShell, outside WSL
    $dvoidInstaller = Join-Path ([System.IO.Path]::GetTempPath()) ('dvoid-install-' + [guid]::NewGuid().ToString() + '.ps1')
    try {
        gh api repos/dvoid-io/workbench/contents/install.ps1 -H 'Accept: application/vnd.github.raw+json' | Set-Content -LiteralPath $dvoidInstaller
        if ($LASTEXITCODE -ne 0) { throw 'Installer download failed; check gh auth status and repository access.' }
        powershell.exe -NoProfile -ExecutionPolicy Bypass -File $dvoidInstaller
        if ($LASTEXITCODE -ne 0) { throw 'dvoid installation failed.' }
    } finally { Remove-Item -LiteralPath $dvoidInstaller -Force -ErrorAction SilentlyContinue }
    $env:Path = "$HOME\.local\bin;$env:Path"
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Windows on ARM64 has no native release. In WSL, use the Linux installer for the console.

## 3. Sign in to your org [#3-sign-in-to-your-org]

Use the org slug you were given:

```sh
dvoid login --org your-org
```

A browser opens on your org's sign-in. `dvoid whoami` shows who you are signed in as.

## 4. Preview, then set up your machine [#4-preview-then-set-up-your-machine]

```sh
dvoid bootstrap --plan --class partner-dev --org your-org   # writes nothing
dvoid bootstrap --class partner-dev --org your-org
```

The plan shows each step, plus your org's repos, templates and plugin changes. Bootstrap installs
the CLI's tools and the agent harnesses (Claude Code, Codex and pi), the console's needs, and a
shell baseline; it keeps your own dotfiles. It is safe to rerun: fix a failed step and run it
again. A summary that ends "with warnings" needs reading, warning by warning.

Already have a machine you only want the console and its Assistant on? Use
`--class partner-console` instead.

## 5. Check it [#5-check-it]

Open a new terminal, then:

```sh
dvoid doctor
dvoid harness
```

`dvoid doctor` lists anything that drifted from your machine's spec with its fix, usually
`dvoid update`. `dvoid harness` lists the agents you can launch.

Pi and the Assistant run on the model fleet with your own key, once your admin has set up your
fleet access:

```sh
dvoid llm setup --lease
dvoid llm check
```

## 6. Start your first workstream [#6-start-your-first-workstream]

```sh
dvoid estate config show    # your org's repos and templates
dvoid workstream new        # a wizard: project, name, repos, goals
dvoid workstream pi         # or claude, codex, hermes
```

Or run `dvoid` to open the console, and press Tab for the Assistant.

## Next [#next]

* [Workstreams and harnesses](./workstreams.md)
* [Console and the Assistant](./console.md)
* [Machine checks and recovery](./machine.md)
* [Customizing](./customize.md)


# Machine checks and recovery (https://docs.dvoid.io/workbench/guides/machine)



New here? Set up first with [Getting started](./getting-started.md): 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 [#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-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 [#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 [#where-a-machines-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 [#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`.


# Workstreams and harnesses (https://docs.dvoid.io/workbench/guides/workstreams)



A workstream is one piece of work across one or more repos: linked checkouts under
`<estate>/workstreams/<project>/<name>/`, all on one branch. The canonical clones they come from
live under `<estate>/repos/`; you read those, and you work in the workstream.

`dvoid workstream list` lists your workstreams.

## Start one [#start-one]

`dvoid workstream new` opens a wizard: pick the project, a name, the repos and your goals (in the
console, **Workstreams** has the same create action). To script it, `dvoid workstream new --help`
names the arguments. Creating a workstream does not open a terminal.

## Its state [#its-state]

Each workstream keeps a state doc: its goal, the next cut, open items and what already failed.
It is the workstream's record, and every agent session in it starts with it.
`dvoid workstream state render` reads it and `dvoid workstream state patch` changes it. A
workstream from before the state doc still has a `.workstream/SEED.md`;
`dvoid workstream state import` carries it in once.

## Keep it current [#keep-it-current]

`dvoid workstream update --check` reads, without changing anything, how each repo's base has moved
and its latest release tag on origin (`dvoid release status`; before cutting a release,
`dvoid release check` with the tag, which never overwrites one).

`dvoid workstream update` makes each worktree rejoin its base, detached, and drops branches proven
merged. It refuses uncommitted changes and work that has not landed, and it never merges a pull
request for you.

`dvoid workstream rm` removes the worktrees, keeps the branches and archives the workstream's
sidecar. `--force` discards uncommitted changes, never commits that nothing else reaches.

## Launch a harness [#launch-a-harness]

**Quick agents** in the console launches a harness from the estate root. Under **Workstreams**,
pick the project and workstream, then **Open ▸** for its harnesses and openers.

From a terminal, `dvoid claude`, `dvoid codex`, `dvoid hermes` and `dvoid pi` launch from the
estate root, and `dvoid workstream claude`, `dvoid workstream codex`, `dvoid workstream hermes`
and `dvoid workstream pi` launch in a workstream. Each command's `--help` lists its
configurations. When the harness exits you are back where you started.

Pi and the Hermes fleet profile run on the model fleet with your own key; Claude Code and Codex use
their own vendor accounts. Some Hermes dashboard features need its gateway running.

A workstream holding a repo your org marks secret runs only `dvoid workstream pi`; the other
harnesses are refused there. That is a launcher default and a block, not isolation.

## Next [#next]

* [Getting started](./getting-started.md)
* [Console and the Assistant](./console.md)


# Secure laptop runbook (partner-secure-dev) (https://docs.dvoid.io/workbench/secure-laptop)



The day-0 path for a Linux Mint laptop of class `partner-secure-dev`, in order. What the class
does and why is in [README § Secure laptop](https://github.com/dvoid-io/workbench/blob/main/README.md#partner-secure-dev) and the
[class file](https://github.com/dvoid-io/workbench/blob/main/packages/dvoid-cli/src/core/bootstrap/classes/partner-secure-dev.yml); this page
is only the steps, what each one asks, and what to check afterwards. Rehearsed end to end on the
Linux Mint 22.3 Cinnamon ISO in a KVM VM (2026-10-21) — everything except the two sign-ins and
the disk encryption, which only the real laptop has.

Replace `your-org` with your org's slug.

## Steps [#steps]

1. **Install Mint 22.x Cinnamon with "Encrypt the new installation" ticked** (Installation type →
   Advanced features → "Use LVM" + "Encrypt the new Linux Mint installation"). It asks for a
   disk passphrase, asked again at every boot. It cannot be added later; `dvoid doctor`'s
   `posture:luks-root` reports it.
2. **Git and GitHub CLI**, then sign git in. Both prompt:
   ```sh
   sudo apt update && sudo apt install -y git gh     # your password
   gh auth login                                      # GitHub.com → HTTPS → "Authenticate Git" Yes → browser code
   gh auth setup-git                                  # idempotent; the step people skip
   ```
   Skipping `gh auth setup-git` makes every private clone (your org's repos, its dotfiles) fail
   with "git has no working credential … `gh auth login`, then `gh auth setup-git`" — fast, not a
   hang — and bootstrap ends with a warning saying `gh auth login && gh auth setup-git`; run
   that, then `dvoid update`.
3. **dvoid**, as in [Getting started § Install dvoid](./guides/getting-started.md#2-install-dvoid) (the
   Linux tab). Success prints `Installed dvoid-linux-x64 at ~/.local/bin/dvoid` and the version.
4. **Sign in to your org** — `dvoid login --org your-org`. A browser opens on your org's sign-in;
   use your org account.
5. **Preview, then bootstrap:**
   ```sh
   dvoid bootstrap --plan --class partner-secure-dev --org your-org   # writes nothing
   dvoid bootstrap --class partner-secure-dev --org your-org          # your sudo password, once
   ```
   Signed in, the plan also shows your org's repos, templates and plugin changes. The run takes a
   few minutes and ends `bootstrap complete` (or `converged with warnings` — read each `⚠`).
   Signed out, it says so in the `dvoid login` and org-settings rows; sign in, then `dvoid update`.
6. **Open a NEW terminal** (PATH, the env opt-outs and the starship prompt arrive there), then:
   ```sh
   dvoid doctor        # every row green — below
   dvoid harness       # pi only
   dvoid claude        # refused: "runs only pi: claude is refused here"
   ```
   If your org names dotfiles, `chezmoi managed` lists them; `dvoid update` keeps them current.

## `dvoid doctor`, green [#dvoid-doctor-green]

* `bin:` git gh mise node python bun uv rg jq ffmpeg starship pi agent-browser dvoid
* `posture:` luks-root, ufw-active, apparmor-enabled, unattended-upgrades, fwupd-refresh,
  ssh-server-off, dns-over-tls, crash-reporting-off, screen-lock
* `mise` (tools current), `dvoid` (current), `signed in`

A red posture row names its fix, almost always `dvoid update`. `luks-root` red means step 1 was
missed: the only fix is a reinstall.

## Check by eye on the real laptop [#check-by-eye-on-the-real-laptop]

What neither CI nor the VM can show:

* **Disk encryption** — the boot passphrase prompt, and `posture:luks-root` green. The probe was
  checked on Mint's LVM-on-LUKS shape, never on a real root.
* **Screen lock** — leave it idle 5 minutes: it locks, and asks for the password at once. The VM
  proved the Cinnamon settings, not a lock.
* **DNS over TLS on your own networks** — home, phone hotspot, office. A captive portal (hotel,
  airport) cannot be passed while strict DoT is on: `resolvectl dns <iface> <portal-dns>` for
  that moment, then `dvoid update` to restore.
* **Chrome**, if you install it — `chrome://policy` shows `MetricsReportingEnabled: false`.
  (Firefox's `about:policies` showing `DisableTelemetry` was proven on the VM.)
* **Firmware** — `fwupdmgr get-updates` sees the vendor; updates stay manual (`fwupdmgr update`).
* **Your org's repos** — the plan lists them; after bootstrap each one is in `~/dvoid/repos`, or
  named in one line as no access (a GitHub grant for your operator to give).
* **pi on the fleet** — `dvoid pi` answers. A secret repo's workstream refuses every other harness.
* **The console** — `dvoid` opens it in Ghostty; the browser pane draws (needs a real display).


# How sign-in works (https://docs.dvoid.io/auth-modes)



Every app in your launcher carries a badge for how its sign-in behaves. They differ because some
apps are part of dvoid itself and some bring their own accounts — the badge makes that contract
visible instead of surprising.

## Unified [#edge]

One login. This surface has no separate session — sign out of dvoid and you are signed out here
too.

* **Session:** the dvoid shell holds the only session.
* **Sign-out:** full — one login, one logout.

## SSO [#federated-internal]

Signs you in automatically from your dvoid session, and signs out when you sign out of dvoid.

* **Session:** the app keeps its own session, signed in silently from dvoid.
* **Sign-out:** propagated — signs out with dvoid.

## SSO · own session [#federated-service]

Signs you in automatically, but keeps its own session — your seat here is independent of the
dvoid shell.

* **Session:** the app keeps its own session, signed in silently from dvoid.
* **Sign-out:** independent by design — your seat here is your own and is not ended when you sign
  out of dvoid.

## Separate login [#island]

Has its own login. Signing in here is separate from your dvoid session.

* **Session:** the app has its own local accounts; dvoid only controls whether you can reach it.
* **Sign-out:** none — its login is entirely separate.

## Engine [#backend]

A backend engine used behind the scenes — no interactive login.

* **Session:** none — reached by service credentials on your behalf.
* **Sign-out:** not applicable — stateless per request.


# Console gallery (https://docs.dvoid.io/gallery)



Each image is a `createTestRenderer` frame of a widget in `tui/ui/`, converted to SVG. The
snapshot test and this picture are the same frame, so the gallery cannot drift from the code.

<Gallery />


# dvoid docs (https://docs.dvoid.io/)



Docs stay in each repo; this site reads them through `docs.sources.json` at the platform
root (repo, path, ref), so what you read here is exactly the ref the manifest pins.

* **[Gallery](/gallery)** — the console's widgets, rendered from the snapshot suite.
* **[Settings schemas](/schemas)** — the JSON Schema behind each dvoid settings file.
* The sidebar lists the rest: the repo docs this deployment carries (each page's `audience`
  frontmatter decides; a page without one stays on the staff site).

Agents: [`/llms.txt`](/llms.txt) and [`/llms-full.txt`](/llms-full.txt).


# Settings schemas (https://docs.dvoid.io/schemas)



`dvoid settings` and the console's Settings group edit these files; each one is created with a
`$schema` pointing here, so an editor completes and checks it. Generated from the settings
registry (`bun run settings:schemas` in workbench), never written by hand.

<Schemas />
