Архив исходника Broker

Историческая копия до очистки репозитория 2026-10-16. Источник: mallexxx/execution-broker, commit ae92c15d31c8396789765cebf82f7971d6f4cb12, файл README.md. Старые статусы и deployment pins ниже не заменяют актуальную personal/projects/balda/execution-broker.

Execution Broker

Execution Broker runs Balda tasks in disposable Docker workers or Virfield macOS VMs. Callee executes the workflow; a separate Prism adapter owns the durable Beads Story. Balda receives progress, asks the user for approval, and reports the result. Provider credentials remain outside plugin packages and VM images.

Release candidate: use the support matrix to select a verified deployment. A Docker smoke test does not qualify Docker coding agents, and installation does not configure access to managed production hosts.

The GitHub main branch is the source of truth for product code and public documentation. The plugin version is defined in plugins/execution-broker/plugin.json; docs/support.md records tested deployment boundaries. Candidate source is not a published release until the release procedure passes.

Runs can consume retained artifacts from an earlier run in the same session using the exact source run, name and SHA256. Broker holds the bytes during the dependency; Runner verifies them before execution and exposes $BROKER_INPUT_DIR. See the input contract for limits and the required worker protocol. Artifact inputs do not install a toolchain or change its policy.

Immutable repository caching and safe environment changes use operator policy and execution/v3.

An agent can select an operator-approved tooling profile for Make/C/C++, Python, Node, JVM or other stacks. Recipes supply checked archives, reviewed Linux image packages or preinstalled guest tools and report their actual versions. Adding a tool does not require a Broker code change. A missing profile or failed prerequisite stops before implementation. Dependencies discovered later use an explicitly authored safe checkpoint and approved environment continuation.

Install the Balda plugin

The repository and binary archives include an Agent Plugins package and a Balda marketplace index. After connecting Broker and Prism, open Balda's Backoffice Operations → Plugins → Marketplaces, add the repository or extracted archive directory, and refresh it. Review the exact execution-broker revision, then select Install plugin.

In a new conversation, use /execute <task> or /skill execution-broker:execution-broker <task>. A chat transport may require mentioning the bot. Existing sessions keep their old capability snapshot until reset. See Balda setup for service credentials, event routing, upgrades and removal.

Start a smoke deployment

Requirements: Docker Engine with Compose, Python 3.12+, Git, and a private Docker network shared with Balda. Source builds also require Go 1.26.9+; the test suite requires Node.js 22+. The example builds Linux ARM64 workers; set TARGETARCH=amd64 and pass amd64 to the two helper scripts on an AMD64 Docker host.

python3 -m pip install -r requirements-tools.txt
make check build linux
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 \
  ./scripts/build-callee.sh "$PWD/.build/linux/broker-callee"
./scripts/fetch-beads.sh arm64
python3 scripts/worker-config.py
docker build -f deploy/Dockerfile.runner -t execution-broker-worker:local .
python3 scripts/init-deployment.py --directory ./state/deploy \
  --worker-image "$(docker image inspect execution-broker-worker:local --format '{{.Id}}')"
export BROKER_CONFIG_DIR="$PWD/state/deploy"
export BALDA_NETWORK=balda_default  # replace with the existing Balda network
# Use docker-compose instead if your installation provides the standalone CLI.
docker compose -p execution-broker -f deploy/compose.yaml up -d --build
.build/bin/executionctl --token-file "$BROKER_CONFIG_DIR/broker.token" --operation tools

For a binary installation, extract the Linux archive matching Docker's CPU, run scripts/prepare-binary-deployment.sh, and continue at fetch-beads.sh. Docker always requires Linux binaries, including when its host runs macOS. Use a native executionctl from your host archive for the final diagnostic command; .build/bin/executionctl is the source-build output. The macOS archive provides native operator and VM binaries.

The initial configuration allows only the deterministic smoke/story fixture and its pinned repository. Configure reviewed profiles and repository allowlists before enabling coding. Deployment profiles explain macOS, provider credentials and signed managed-host plans.

Components

Component	Responsibility
`execution-broker`	Admission, leases, event journal, Human responses, artifacts and notification outbox
`execution-runner`	Worker-local checkout, Callee execution, cancellation and artifact collection
`execution-worker`	Restricted Docker gateway; the only service with the Docker socket
`execution-host-runner`	Fixed, signed host operations and bounded rollback
`execution-prism-adapter`	Story/Task lifecycle and idempotent Beads projection
`execution-credentials`	Encrypted persistent OAuth identity, issuance and checkpointing
`executionctl`	MCP/HTTP diagnostics and operator plan signing

Broker does not interpret workflow graphs or write Beads. Requests cannot supply host paths, shell commands or Docker options. Worker configuration, workflow versions, repository access and agent profiles belong to the operator.

Documentation

MIT licensed. Dependency licenses and inventories are included in every binary archive; see third-party notices.