Skip to content
bb plugin atlas

Machine providers

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

experimental Plugin backend Show on the zone map

Adds plugin-provisioned machines that compose with environment providers. With this, a plugin can:

Create and own execution machines

What it gives you

  • Register bb.experimental_machines with a display name, one-line description, and required glyph, plugin-relative SVG, declared icon, or React icon
  • Show the provider display name and icon as the kind next to every machine it creates; manually enrolled machines have no kind
  • Declare automatic retirement for thread-created ephemeral machines; standalone machines remain until explicit removal. Core parses Standard Schema inputs and checks availability and validation before create
  • Keep secrets in plugin settings because persisted machine inputs are readable by every plugin; pass only non-secret configuration or references
  • Register an environment composition with machineProviderId and environmentProviderId to create a machine and then use a concrete environment provider; machine registration alone adds no picker option; CLI selects the composition with --environment-provider
  • Create machines that belong to no project; projects reach a machine later through project sources
  • Make create idempotent by its host launch key so a restart after enrolment recovers the same machine
  • Bootstrap over a required MachineExecutor; core Manual setup uses internal enrollment operations; never put credentials in resource JSON or output
  • Install a daemon for pending enrollment and restart an enrolled identity after snapshot restore
  • Stream progress on the creating host and honor abort signals for create, suspend, resume and remove
  • Keep credentials out of report.step and report.log: core persists progress and copies it into thread transcripts; core exposes manual enrollment commands transiently by host ID
  • Await create.checkpoint(resource) immediately after allocation so cancellation can remove it without waiting for bootstrap
  • Implement reconcileCleanup to discover and remove uncertain allocations by durable key when no checkpoint exists; remove receives known resources; never create or bootstrap; return failed while allocation intent is unresolved so core retries on its cleanup interval
  • Await suspend.checkpoint(resource) before destructive cleanup
  • Await resume.checkpoint(resource) before bootstrap; core fences provider ownership, phase and operation and recovers the same enrollment after restart
  • Allocation checkpoints are recovery records, not filesystem saves; daemon-connected does not mean agent-ready
  • Read the current persisted machine resource by host ID with bb.experimental_machines.getResource; reads work across plugins and return null for absent hosts or resources
  • Own idle timing in the plugin using thread-sequence and terminal-input events plus background schedules
  • Render one compact machine-inputs control in composed thread creation with app.slots.experimental_machineProviderInputs, reporting a ready non-secret JSON value on mount or a one-sentence blocked reason
  • Request suspend/resume through the host SDK; calls return the updated host when the tracked operation starts, core coordinates drain, starting thread launches, provisioning environments, and project checkout setup reject suspend with machine_busy, and plugins own idle policy
  • Read maintenance state and lifecycle failures from each host's lifecycle phase and message
  • Call hosts.experimental_reconcile from plugin-owned maintenance to enforce core’s suspended state through the provider; active and transitional states are unchanged, the call returns after acceptance; poll host status for completion, and core does not poll. Suspend and resume must be idempotent: preserve stopped resources and reuse running compute. Request new pauses with experimental_suspend
  • Await suspend.checkpoint(resource) to persist opaque resource state before termination; schedule vendor maintenance in the plugin using bb.background.schedule and bb.sdk.hosts.experimental_suspend
  • Optionally declare suspend and resume together; plugins own idle timing and core coordinates transitions
  • Return an opaque JSON resource that core persists and passes back to lifecycle operations; never include credentials
  • Return a required readable machine name from create
  • Treat a failed create as terminal and retry vendor API hiccups inside the create call

API

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

Used by

Modal sandbox

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.