Skip to content
bb plugin atlas

Environment providers

bb 0.43.3SDK 0.4.104pinned e865697 (desktop-v0.43.3)

experimental Plugin backend Show on the zone map

Offers plugin-provisioned places a thread can run, picked like any environment. With this, a plugin can:

Provision where a thread runs

What it gives you

  • Declare a provider with a required display name, description, and icon, picked in New Thread or bb thread spawn --environment-provider
  • Use a host glyph, plugin-relative asset, declared icon, or React provider icon slot targeted by required providerKind and providerId
  • Declare the project facts it consumes in one place — requires.projectCheckout, requires.gitCheckout, requires.gitRemote, requires.projectless — which structurally decides where the picker offers it
  • Answer availability for a project and machine with available, setup-required, or unavailable; core probes connected machines in the background so pickers hide unsupported ones, caches the answer, and checks it afresh for the selected machine at thread creation
  • Declare what it needs from the request as a zod inputs schema; bb parses the request with it before the thread exists, publishes it as JSON Schema for the CLI, and hands create the parsed value as inputs
  • Validate a resolved selection once before thread creation; host-dependent preflight requires connectivity, and create checks conditions that can change afterward
  • Read the facts as typed values on the create context: host is always non-null, while projectCheckout and gitRemote are non-null exactly when required
  • Read projectCheckout.experimental_ownsPath to distinguish core clones from user-maintained attachments; core runs environment hooks for owned paths
  • Render its own control for those inputs beside the picked provider with app.slots.experimental_environmentProviderInputs, reporting either ready inputs or a blocked reason
  • Use experimental_BranchPicker for a standard branch choice, or compose experimental_useBranches with experimental_useCheckoutState when it needs checkout-aware branch selection
  • Run one idempotent long create call that returns a created directory or failure; a failed create is terminal and an explicit retry starts a new attempt on the same environment; provider policy exposes only retirement grace and path-key strategy
  • Let bb run the repo setup hook after an owned-path create and teardown before removal; attached paths skip both hooks; unknown hook outcomes after daemon restart block automatic cleanup
  • Use core's pathKey for stable resource identity; core records it as the environment instance key
  • Reserve a shared checkout before mutation with create.experimental_claimPath; core holds the host/path claim through attachment or cleanup
  • Name a branch the way bb would, from the suggestedBranchName core hands every create, and stream progress with report.step and report.log
  • Honor create and remove abort signals; core aborts create before asking remove to clean everything under the same path key
  • Work on the existing enrolled machine carried by the selection, returning the path it produced
  • Environment input controls receive target: { kind: 'existing-host', hostId } or { kind: 'new-host' }; compositions reuse the underlying control before provisioning, and backend create receives the real host
  • Register a composition with an explicit display name, description, icon, machineProviderId and environmentProviderId instead of lifecycle callbacks; core creates the machine and uses the concrete environment provider, preserving its checkout ownership
  • Return an opaque JSON resource handle from a created launch; core keeps up to 16 KiB private and supplies it only to recovery and removal callbacks from the recorded owning plugin

API

Each symbol links to the pinned commit it was read at.

Used by

Project checkout, Personal workspace, Worktree

The brief is Markdown, written for a coding agent: what the capability is, where it registers, every SDK symbol with a pinned permalink, the rules that bite, and what done means.