Skip to content

Workspaces & the Workbench

Everything in the Investigate half of the guide happens in one place: a workspace — a directory that is the model — driven by the Workbench, an AI-free server that turns that directory into a git-backed research notebook. The data lives in the workspace, never in the server.

The workspace/Workbench split

The Workbench is tooling; the workspace is data.

vivarium-workbench — the server

A single-process FastAPI web app. It has no database of its own and no AI. It reads and writes plain files in a workspace directory and delegates every simulation to process-bigraph. Every mutating action commits to the active git branch, so there is a full audit trail.

the workspace — the data

A git repository holding the model's Python package, its composites, its studies and investigations, its references, and its results. It is the unit of reproducibility: clone it, run it, get the same answer. The server runs inside the workspace's own venv.

The dependency arrow points one way: the workspace depends on vivarium-workbench (it is a pip dependency in the workspace's pyproject.toml), never the reverse. That is why the server can import the workspace's own package and any installed simulator stacks — it is running in their environment.

flowchart LR
    subgraph WS["Workspace directory (the data + the model)"]
      Y["workspace.yaml"]
      P["viva_<pkg>/ · build_core()"]
      S["studies/ · investigations/"]
      DB[("runs.db · .pbg/")]
    end
    WB["vivarium-workbench<br/><small>FastAPI · AI-free · commits to git</small>"]
    SK["viva-superpowers<br/><small>/viva-* skills (all AI)</small>"]
    WB -->|reads / writes files| WS
    SK -->|HTTP /api/*| WB
    WB -->|delegates| E["process-bigraph engine"]

The Workbench is AI-free. All AI capability is packaged as the viva-superpowers Claude Code plugin — a set of /viva-* skills that drive the Workbench's HTTP API — which keeps the tool auditable and the AI swappable. See Working with AI agents for how that split works.

Modules vs workspaces

Two nouns are easy to confuse, so pin them down early:

Module Workspace
What it defines processes, composites, runtime-environment dependencies studies, composites, investigations — with modules installed
Ownership distributable, versioned, immutable at a version owned, mutable, not itself a unit of distribution
Back-reference a module has no back-reference to any workspace a workspace holds a list of modules

A module is a viva-<tool> / pbg-<tool> package that wraps a simulator; a workspace installs several of them and attaches science to the composites they provide. A composite-only repo (e.g. a bare simulator wrapper) has no workspace.yaml — just a pyproject.toml, a viva_<slug>/ package, and tests/ — and is pulled into a workspace through workspace.yaml's imports. You can promote such a repo into a workspace in place (see scaffolding, below).

What a workspace looks like on disk

A workspace is a directory with a workspace.yaml manifest and a viva_<pkg>/ Python package that exposes a build_core() entry point. Everything else hangs off those two.

my-workspace/
├── workspace.yaml                          # the manifest (schema below)
├── viva_<pkg>/                             # the workspace's Python package
│   ├── core.py                             #   build_core() — registers this repo's processes
│   ├── composites/<id>.composite.yaml      #   the runnable substrate (JSON/YAML or a generator .py)
│   ├── processes/                          #   Process / Step classes
│   └── visualizations/                     #   Visualization Steps
├── studies/<slug>/                         # CANONICAL: studies live flat here, one dir per slug
│   ├── study.yaml                          #   a question + its narrative spine
│   ├── runs.db                             #   canonical run + outcome record (SQLite)
│   ├── parquet-runs/<run>/                 #   emitted trajectories (Parquet hive)
│   └── viz/                                #   rendered figures + report cards
├── investigations/<slug>/investigation.yaml   # a collection (= git branch = worktree); lists its members by slug
│                                           #   (nesting a study.yaml under investigations/ is a hard L0 audit violation)
├── references/papers.bib                   # shared bibliography
├── notes/                                  # field records — cleanup PRs must SPARE these
└── .pbg/                                   # gitignored runtime state (see below)
    ├── server/server-info                  #   the live server URL every client reads
    ├── runs/<run_id>/                      #   detached-run request + observables
    ├── composite-runs.db · artifacts/      #   run metadata + content-addressed caches
    └── schemas/ · events.jsonl · state.json

Studies are flat; investigations reference them by slug

The canonical layout is studies/<slug>/study.yaml at the workspace root, with investigations/<slug>/investigation.yaml naming its member studies through a members: list of slugs. Nesting a study.yaml under investigations/**/ is a deliberate hard L0 audit violation (no-nested-study) — the reproducibility contract mandates the flat layout, and study_audit.py fails --gate CI on it.

.pbg/ — a legacy prefix that stayed

The runtime control directory is still named .pbg/, and the global registry still lives at ~/.pbg/, even in viva-branded workspaces. The pbg → viva rename covered skills and packages but deliberately left these paths alone so existing tooling keeps working. See A note on names.

The build_core() convention

The workspace package's job is to hand the engine a Core — the type-and-process registry (see Schemas, types & state). By convention the package exposes a single build_core() function that composes any imported repos' cores and then registers this repo's own processes:

# viva_<pkg>/core.py
def build_core(core=None):
    core = compose_import_cores(core)              # pull in imported module stacks
    register_package_processes(core, f"{__package__}.processes")
    return core
Accuracy note — viva_ vs pbg_, build_core() vs core.py

The ecosystem is mid-migration. Newer scaffolds emit a viva_<pkg>/ package exposing build_core(). Older docs and workspaces show a pbg_<pkg>/ package and refer to the registration entry point simply as core.py. The convention — "the package exposes a build_core() that returns a populated Core" — is stable; only the package prefix and some prose differ. Prefer the viva_ spelling.

The workspace.yaml manifest

workspace.yaml is validated against a Draft-07 JSON schema shipped in the plugin (viva_superpowers/schemas/workspace.schema.json).

Required: schema_version, name, created (a date), plugin_version (semver).

Commonly used optional keys:

Key What it declares
package_path the viva_<pkg>/ directory holding the package
default_baseline pre-filled composite + params + run-knobs for new study baselines
imports a map of imported pbg-* / viva-* repos a composite instantiates directly ({source, ref, mode, installed})
observables named {name, store_path, units} observables the workspace tracks
visualizations · simulations · datasets declared figures, run recipes, and input datasets
references_bib · references_pdfs the shared bibliography and cited PDFs
server.enabled whether this workspace runs a dashboard server
ui.composite_view which renderer draws composite wiring (loom-explore — the default — or legacy bigraph-viz)
layout optional per-directory relocations (e.g. group studies/ under workspace/studies/)
Accuracy note — schema version and the runtime: block

The shipped workspace.schema.json pins schema_version to the enum [2, 3] and does not constrain a top-level runtime: block. The concept docs describe a runtime: block (default_emitter: parquet|sqlite, subprocess_timeout_s, shared_artifacts: [...]) that migrated workspaces carry; treat it as a documented, schema-tolerated convention rather than a required, schema-enumerated field.

Scaffolding a workspace

The /viva-workspace skill (backed by the viva-scaffold console script and the vwb CLI) creates a workspace in one of three modes, chosen by your starting state:

Starting state Mode Command
No directory yet, no upstream model repo standalone /viva-workspace <name>
No directory yet, want to branch off an existing repo upstream-branch /viva-workspace <name> --upstream owner/repo
Already inside a git checkout you want to promote in-place /viva-workspace <name> . --in-place
  • standalone clones the viva-template scaffold (vwb scaffold-workspace), runs git init, creates a .venv and uv pip install -e .[dev], commits the bootstrap, and registers the workspace in the global catalog (~/.pbg/workspaces.json).
  • upstream-branch clones an upstream model repo, cuts a workspace branch off origin/main, applies the scaffolding on top, and commits — the recommended path when you are adding an investigation to code that already exists.
  • in-place promotes a checkout you already have (skipping any files that already exist), then registers it. This is the right answer for composite-only repos.
Template repo naming

The scaffold source is the viva-template repo. The canonical scaffolder (viva_superpowers/scaffold.py) defaults its clone URL to vivarium-collective/viva-template; the older /viva-workspace skill prose still names pbg-template, and either $VIVA_TEMPLATE or $PBG_TEMPLATE (or --template-source) overrides it. Same scaffold, two names. After scaffolding, python3 scripts/lint-workspace.py should print workspace lint: OK.

If you prefer to do it by hand, cloning the template and initializing it is equivalent:

git clone https://github.com/vivarium-collective/viva-template my-workspace
cd my-workspace
bash use-this-template-init.sh          # renders the .j2 scaffolding
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"              # pulls in vivarium-workbench as a dependency
python3 scripts/lint-workspace.py       # -> "workspace lint: OK"

Starting the server

From the workspace root (the directory containing workspace.yaml):

vivarium-workbench serve --workspace .              # picks a free port, then serves
vwb serve --workspace . --port 8000 --host 0.0.0.0  # vwb is the short alias
bash scripts/serve.sh                               # convenience shim in a scaffolded workspace

On start the server writes a JSON server-info doc to .pbg/server/server-info — the file every client and agent reads to discover the server. It carries port, host, and a ready-to-use url (clients parse it with json.loads, not as a bare string). Never hardcode a port.

BASE=$(python3 -c "import json; print(json.load(open('.pbg/server/server-info'))['url'])")
curl -s "$BASE/api/workspace-manifest"   # one-call situational snapshot — start here

Because the server runs in the workspace's venv, it can import the workspace's build_core() and any installed pbg-* / viva_* simulator stacks directly.

Running modes

Point the server at a remote viva-api backend (VIVA_API_BASE=...) to submit runs that execute on GovCloud (Ray → AWS Batch → zarr/parquet on S3) and land back as study runs. The same codebase, with writes gated to a small whitelist, is what serves the read-only online dashboard — "the workbench with writes gated."

Session-per-tab: one workspace per browser tab

The server can host many workspaces at once. It keeps them from colliding with a simple rule: a session is pinned to one workspace, per browser tab, for its life.

  • Picking a workspace from the left-rail workspace switcher opens it in a new tab rather than re-pointing the current one — "one workspace per browser tab."
  • Session middleware resolves each request's session to a workspace and sets a request-scoped root (a ContextVar), so two tabs on two workspaces never interfere.
  • Runs are workspace-scoped, not session-scoped. A run outlives the session that launched it; another tab on the same workspace sees it in the Runs index.

The side-rail tabs

The left rail is the map of the Workbench. The shipped labels (authoritative) and what each surfaces:

Rail tab Shows
Resources the workspace.yaml summary — dependencies, references, datasets, scaffolding status
Catalog the marketplace / module catalog: install and list available processes and composites
Processes the Registry — every Process / Step / Composite the workspace can import
Studies the Investigations DAG canvas, grouping studies into research arcs
Runs the Simulations DB / runs index — every run across every emitter backend
Analysis saved interactive visualizations, 3D viewers, and the Analysis Tools / PTools card
Two vocabularies

An earlier README describes "seven tabs" (Workspace · Registry · Composites · Studies · Investigations · Visualizations · GitHub Branches). That is the conceptual model; the shipped rail above is the reorganized, renamed reality. Sections such as the single-study view, the Composite Explorer, GitHub Branches, and the audit panel exist but are not top-level rail links — they open from within the tabs above.

Every mutating action in any tab commits to the active git branch in the workspace, so there is a full git audit trail of the investigation as it is built.

The Composite Explorer (loom)

Opened from the Catalog or Composites views (or with /viva-explore <spec-id>), the Composite Explorer browses, configures, and runs a single composite. Its centerpiece is an embedded bigraph-loom state-tree viewer — an interactive rendering of the composite's place graph and wiring, served at /loom-explore.

The composite registry the Explorer draws from is the union of three sources:

  1. the workspace's own package composites/,
  2. every installed pbg-* / viva_* distribution's composites/, and
  3. @composite_generator-decorated factory functions discovered across those packages.

A composite is referenced by a dotted id like v2ecoli.composites.baseline.baseline — the same id a study points at. From the Explorer you can run a scratch simulation (a detached, durable run), inspect the emitted observables, and promote a configured composite into the catalog. See Composites & wiring for how composites are built.

Golden rules for driving the Workbench

  • Read .pbg/server/server-info for the URL — never hardcode a port.
  • Orient with GET /api/workspace-manifest (state) and GET /api/linkage-index (graph); trust GET /openapi.json for exact shapes.
  • Runs are async — poll status and check the result field, not just HTTP 200.
  • Every write is a git commit in the workspace.

Next: Studies