ESF — Engineering Software Factory

A self-hosted software factory that runs coding agents in isolated CubeSandbox microVMs, verifies their changes, and preserves the patch and execution evidence. Temporal coordinates the workflow and sandbox cleanup.

Task → Temporal → CubeSandbox → coding agent → verification → patch + evidence

ESF is an independent fork of Machinist by Owain Lewis. It retains the Machinist CLI, local control plane, and web UI, and adds factory orchestration. See upstream attribution.

Features

• Named, operator-configured agent harnesses and repository policies.
• Isolated execution in an existing CubeSandbox deployment.
• Deterministic verification gates; agent success alone is not factory success.
• Durable patches, logs, manifests, and verified cleanup outcomes.
• Temporal TLS/mTLS, API-key authentication, and optional encrypted payloads.
• Bounded execution, cancellation, and recovery after a lost create response.
• Optional patch assurance: frozen policies, independent review, authenticated approvals, attestations, and local non-conformance/CAPA records.

This is actively developed software. Review the validated behavior and operational requirements before deployment. ESF produces changes for review; it does not decide what ships. The v0.5.0 archives are a binary preview. VM, Kubernetes, container-image, security, restore, and soak qualifications are recorded separately in the release inventory and are not complete.

QMS is optional

The default configuration runs ESF without QMS. Keep [quality] and scope quality_policies bindings absent to use the normal agent, verification, patch, and cleanup workflow. No quality database, approval socket, repository registry, or enterprise QMS service is required in this mode. Ordinary runs do not receive quality approval or readiness attestations.

The local QMS implementation is included under the same MIT license and works without an external QMS product. It attests readiness of an exact patch; it does not authorize releases or certify regulatory compliance. See quality operations and the R2/R3 examples to opt in.

Quick start

Requirements for v0.5.0 development: Go 1.27.1, Node.js 24.21.0, Git, an existing CubeSandbox deployment with a READY template, and Temporal. Python tools use the frozen uv.lock; they are optional. Docker Compose can run the included local Temporal stack.

git clone https://github.com/mitkox/esf.git
cd esf
mkdir -p bin
make build
./bin/factory init

Edit factory.toml with your Cube API endpoint, template, proxy address, agent harness and verification profile. Configure narrowly scoped credentials locally. Neither factory.toml nor .env belongs in Git. The example uses placeholder production endpoints and paths. Set these to your actual TLS-protected Cube and Temporal services, or loopback development services, before running factory config validate.

The v0.5.0 release installs the factory archive by default. The console and managed worker use the separate Machinist archive or the optional combined archive. Install pinned agent binaries separately with scripts/install-agents.sh; factory agents verify checks configured digests.

For local Temporal:

cp deployments/dev/temporal/.env.example deployments/dev/temporal/.env
# Set a random database password in that .env file before starting.
make temporal-up
./bin/factory config validate
./bin/factory doctor
./bin/factory worker

In another terminal, submit a task for an allowed repository:

./bin/factory run \
  --repo https://github.com/your-org/your-repo \
  --rev FULL_COMMIT_SHA \
  --task "Describe the change and acceptance criteria" \
  --agent opencode2 \
  --verification default

The default profile expects repository-owned build.sh and test.sh scripts. Configure gates appropriate to your project. Inspect results with factory status RUN_ID and factory logs RUN_ID:

./bin/factory describe run RUN_ID       # manifest + conditions + inventory + audit
./bin/factory status RUN_ID --watch     # stream condition transitions
./bin/factory get changes               # durable work items and their spend

With [review] enabled = true, a run pauses after the gates report:

./bin/factory review RUN_ID --approve
./bin/factory review RUN_ID --reject --note "use the formal greeting"
./bin/factory run --change CHANGE_ID --parent-run RUN_ID ...   # rework activation

A run can also be submitted from a reviewed manifest:

./bin/factory apply -f run.toml

Build the inherited CLI separately with go build -trimpath -o bin/machinist ./cmd/machinist, then run ./bin/machinist init. Machinist now supports staged workflows, review gates, shared artifacts, and final-message summaries. Its approvals do not replace ESF's optional QMS approvals. See workflow guidance.

Documentation

Development

make lint
make test
make frontend
go test -race ./...

Integration tests require configured services; see the operator guide. Read CONTRIBUTING.md and the Code of Conduct. Report vulnerabilities privately through SECURITY.md.

License

MIT. Original Machinist copyright and attribution are preserved.