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.

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.