# Архив исходника 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](docs/support.md) 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`](plugins/execution-broker/plugin.json); [`docs/support.md`](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](docs/protocol.md#artifact-inputs) for limits and the required worker protocol. Artifact inputs do not install a toolchain or change its policy. [Immutable repository caching](docs/repository-cache.md) and [safe environment changes](docs/environment-changes.md) use operator policy and execution/v3. An agent can select an operator-approved [tooling profile](docs/tooling.md) 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 ` or `/skill execution-broker:execution-broker `. A chat transport may require mentioning the bot. Existing sessions keep their old capability snapshot until reset. See [Balda setup](integrations/balda/README.md) 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. ```sh 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](docs/deployment.md) 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 - [Installation and profiles](docs/deployment.md), [Balda integration](integrations/balda/README.md) - [Protocol and guarantees](docs/protocol.md), [supported configurations](docs/support.md) - [Operations](docs/operations.md), [coordinated recovery](docs/recovery.md) - [Executor profiles and enrollment](docs/executors.md) - [Credential lifecycle](docs/credentials.md), [security](docs/security.md) - [Testing](docs/testing.md), [release procedure](docs/releasing.md) MIT licensed. Dependency licenses and inventories are included in every binary archive; see [third-party notices](THIRD_PARTY_NOTICES.md).