Workspaces

A workspace is a directory holding a bldr-workspace.yml. That file is the whole definition. If it is there, the directory is a workspace; if it is not, nothing else makes it one.

Commands find it by walking up from where you are, the way git finds a repo, so bldr build works from anywhere inside the tree. Pass -W when you mean a different one.

What it holds

members:
  site: members/site
  node:
    content:
      kind: container-registry
      reference: docker.io/library/node@sha256:6c74791e...
    tracking:
      kind: container-registry
      reference: docker.io/library/node:22-slim

options:
  build_controller: default
  targets:
    - site

members is the map that matters. options holds settings for the workspace as a whole: targets is the default selection a bare bldr build uses, and build_controller names the controller that runs builds here. The controller is required, and a workspace without one parses fine and cannot build, which is a confusing five minutes if you have just removed it.

The pin and the thing it follows

This is the idea worth internalising, and it is deliberately a little inconvenient.

content: is what builds. tracking: is where a newer version would come from. Asking what upstream currently offers never changes what builds. Only an explicit bldr ws pull writes a new digest into content:.

The alternative, following a tag directly, is how most build systems do it, and it means the same command produces different output on Tuesday than it did on Monday for reasons nothing recorded. Here the manifest is the record.

bldr ws pending-changes    # what has moved upstream
bldr ws pull node          # adopt it, and write it down

Tracking is optional. A member with no tracking: is not pullable, which is the right answer for content that should never drift.

Editing it

You can edit the file. You can also let the CLI do it, which is what you want when it is scripted:

bldr ws add <NAME> --path members/thing
bldr ws set targets '[site]'
bldr ws rm <NAME>

Either way your comments survive. The CLI rewrites the manifest in place rather than regenerating it, so the reasoning you left beside a pinned digest is still there next time.

Sequences

A workspace can keep named counters under sequences:. They are a small versioning service: a number the workspace hands out, kept in the manifest so it is versioned with everything else and survives whatever machine last bumped it. How a build reads one is a later step; today the counter is the feature.

sequences:
  release: 7
  app: 1.4.0

Two kinds, and the shape of the initial value picks one. An integer is a plain counter. Three dot-separated integers are a major.minor.build triple, where bumping minor or major resets the components below it to zero.

bldr ws sequences create release 0     # an integer
bldr ws sequences create app 1.0.0     # major.minor.build
bldr ws sequences bump release         # 1
bldr ws sequences bump app --minor     # 1.1.0
bldr ws sequences set app --to 2.0.0
bldr ws sequences get app
bldr ws sequences list
bldr ws sequences remove release

A bump is computed against the value on disk, inside the same locked, comment-preserving edit as every other manifest change, so two bumps racing each other produce two different numbers. The workspace page in the console shows the sequences alongside the options.

Registering with a node

A node builds workspaces it knows about.

bldr ws register     # tell the node about this one
bldr ws status       # what it currently sees, per member
bldr ws status -w    # follow that live