OpenFactory Appliance: Run the Factory Inside Your Own Network

OpenFactory handles material that says a great deal about an organization: operating-system recipes, source locations, package inventories, vulnerability findings, device identities, deployment targets, and approval records. Sending all of that through a vendor-run agent is a poor default for a regulated lab or a private engineering network.

The planned OpenFactory Appliance puts the control plane on a computer the operator controls. The console, builders, test VMs, evidence, policy, and integration adapters run in one Debian virtual machine. The operator chooses the hypervisor, storage, identity system, network rules, model endpoint, and update schedule.

This is a boundary decision before it is a packaging decision. The model is replaceable. The customer's VM, network policy, credentials, and data rules decide what the model can see and what it can do.

The boundary is the product

OpenFactory Appliance treats the customer-owned virtual machine as the main security boundary. The console, builders, test runners, evidence store, policy engine, and integration adapters stay inside it. Only an operator-approved route can carry model requests, updates, or reviewed support data across the customer network boundary.

Hardware virtualization gives the appliance a computer-sized boundary. It can be firewalled, snapshotted, scanned, attested, and replaced as one unit. Inside it, libvirt can still create short-lived test machines for the images OpenFactory builds. KVM is a Linux virtualization system for x86 hardware with Intel VT or AMD-V extensions, as described by the KVM project.

What runs inside

One appliance contains the public OpenFactory surfaces and the private services behind them. Its HTTPS entry point reaches the site, build workspace, console, API, and MCP endpoint, while recipe planning, image building, KVM testing, PostgreSQL state, evidence, policy, updates, and customer adapters remain local.

• The local site, build workspace, management console, API, and MCP endpoint.
• Recipe planning, image builders, nested KVM test runners, and build orchestration.
• PostgreSQL-backed state plus local storage for images, SBOMs, logs, approvals, and verification results.
• Policy, attestation, update, support-bundle, and optional enterprise integration services.

Public-cloud routing, marketing analytics, mail infrastructure, speech services, and developer automation stay out of the image. A private appliance should not carry every service that happens to exist in a production checkout.

The LLM is not a trust boundary

A model can propose a recipe or request a tool action, but it never becomes the authority for data access. One policy service classifies and filters every model request before routing. Builds, approvals, tests, and evidence review must remain usable when no model is configured or a provider fails.

Each request receives a context class before routing: public, internal, restricted, regulated, secret-bearing, or export-prohibited. The last two classes cannot go to an external model. Restricted and regulated requests need an approved provider and redaction policy. A failed model call stays failed or returns to local/manual operation; it does not jump to an unapproved provider.

The default mode is no model at all. Recipe editing, approvals, builds, tests, and evidence review must continue to work without an LLM. A local OpenAI-compatible endpoint or a customer-approved SaaS provider becomes a route the operator adds later.

Egress is a setting, not an assumption

Network access is expressed as four operator-selected levels. E0 permits signed offline inputs only; E1 permits private customer endpoints; E2 adds named model and update vendors; E3 adds an opt-in, reviewed support path. Nftables and an application proxy must enforce the same choice for every outbound service.

These levels cover more than model traffic. Update checks, package mirrors, diagnostics, and support exports use the same explicit exit paths. A support bundle is built and redacted locally, then reviewed by the operator before export.

Current platform and appliance target

The current platform already builds Linux images, boots test VMs, records verification artifacts, exposes MCP tools, and offers Claude and Codex execution paths. The appliance work is the packaging and enforcement layer: one customer-operated image, persistent local state, provider-neutral policy, controlled egress, signed updates, and measured-boot reporting.

Provider-neutral model routing, appliance-wide egress enforcement, measured boot, signed offline updates, and automatic base rollback are target controls. This preview does not claim that they ship today.

Why Debian 13 and KVM come first

The first acceptance target is deliberately narrow: Debian 13 on amd64, delivered as QCOW2 for KVM and Proxmox. A single base, CPU architecture, and artifact format make failures attributable. Nested virtualization is required for builds and VM tests, while a virtual TPM remains optional but its absence is reported.

Debian 13, code-named trixie, supports amd64 and is the current stable Debian line. Its release and support dates are published on the official Debian release page. The first artifact is a QCOW2 image for KVM and Proxmox. VMware and Hyper-V packages can follow after the same tests pass on the first target.

A virtual TPM is optional in the first environment, but its absence must be visible. Linux exposes the firmware TPM event log used to understand which pre-boot components extended Platform Configuration Registers; the kernel documentation describes that handoff. When no vTPM is attached, the appliance should report that measured-boot evidence is unavailable instead of inventing an attestation result.

Reference build prompt

The reference prompt is a testable release contract, not a deployment button. It fixes the base image, artifact format, trust boundaries, service set, egress behavior, update rules, failure modes, and validation suite. A future appliance should be judged against these checks instead of a package list or boot screenshot.

Build a technical-preview virtual machine appliance named openfactory-appliance.

This appliance runs the OpenFactory control plane inside infrastructure owned by its operator. Treat every requirement below as an acceptance criterion. If the build platform cannot implement a requested security control, report a blocking gap. Do not replace security controls, application services, tests, or source packages with mock services, compatibility listeners, placeholder pages, or generated claims of success.

Base and output
- Use Debian 13 (debian-trixie), amd64, headless, with systemd and UEFI boot.
- Produce one bootable QCOW2 appliance for KVM and Proxmox. Do not produce OVA or VHDX images in this first target.
- Set the minimum appliance profile to 8 vCPUs, 16 GB RAM, and 250 GB storage.
- Install QEMU guest agent and virtio storage, network, and entropy drivers.
- Require host CPU passthrough and nested virtualization for image builds and VM tests. Expose a clear blocked status when /dev/kvm is unavailable.
- Accept a virtual TPM 2.0 when supplied by the hypervisor. Record measured-boot evidence when it is present and report attestation as unavailable when it is absent.

Source and provenance
- Package OpenFactory and the openfactory.tech site from operator-supplied source bundles under /run/openfactory-sources.
- Require a full commit ID and SHA-256 digest for every source bundle. Reject floating branch names and unpinned dependencies.
- Install application code under /opt/openfactory and record the resolved commits and bundle digests in /usr/share/openfactory-appliance/provenance.json.
- Build the web applications, Python services, and Rust daemons during image creation. Do not ship live Git checkouts or development servers.
- Generate an SPDX SBOM, package manifest, QCOW2 digest, build recipe, test results, and provenance record beside the image.
- Sign the artifact manifest with a build-time key supplied from outside the image. Never create, copy, or retain the release signing private key inside the appliance.

Storage and first boot
- Keep the vendor-supplied base separate from customer state. Use /var/lib/openfactory for databases, build artifacts, evidence, configuration overlays, model audit records, and update state.
- Require a customer-managed persistent data disk before leaving setup mode. Preserve that disk when the base appliance is replaced or rolled back.
- Generate all instance secrets, local TLS keys, admin recovery material, and service credentials on first boot. Do not bake shared passwords, API keys, certificates, or private keys into the image.
- Provide /usr/local/sbin/openfactory-setup on the VM console. It must configure the admin account, hostname, persistent disk, local network, TLS, time source, model mode, egress level, and optional identity and secrets backends.
- Use openfactory-appliance.local as the default mDNS name and allow an operator-supplied FQDN. Show the active URL and certificate fingerprint on the VM console.
- Expose one HTTPS entry point. Route the site, build workspace, console, API, and MCP endpoints through the local reverse proxy. Bind internal service ports to loopback or private service bridges.

Local OpenFactory services
- Run the openfactory.tech site, the build workspace, the management console, the OpenFactory API, and the MCP service locally.
- Run the recipe engine, policy and approval engine, build orchestrator, image builders, KVM test runners, evidence store, SBOM services, attestation services, update agent, and integration adapters locally.
- Use local PostgreSQL for application state. Store build images and evidence on the persistent data disk with owner and service-level access controls.
- Install libvirt and QEMU for nested test VMs. Keep test networks separate from the appliance management interface and block test guests from reaching appliance control ports unless a test grants that path.
- Include customer-configured adapters for Git, OIDC identity, package mirrors, object storage, ServiceNow, vulnerability feeds, and SIEM. Leave every adapter disabled until configured.
- Exclude public-cloud routing, marketing analytics, visitor tracking, mail infrastructure, speech services, and development-only automation from the image.

Model routing and secrets
- Default to no-model/manual mode. The appliance must remain usable for recipes, approvals, builds, tests, and evidence review without an LLM.
- Provide model adapters for a private OpenAI-compatible endpoint, Claude, Codex/OpenAI, and Kimi. Prefer a local endpoint when one is configured.
- Keep model credentials in the configured customer secrets backend or an encrypted local fallback. Inject credentials at runtime and never write them to prompts, logs, recipes, support bundles, or build artifacts.
- Route every model request through one policy service. Other OpenFactory services must not call external model endpoints directly.
- Classify each request as public, internal, restricted, regulated, secret-bearing, or export-prohibited before routing it.
- Block external routing for secret-bearing and export-prohibited requests. Restricted and regulated requests require an allowlisted provider, redaction, and an operator-approved policy.
- Redact tokens, passwords, private keys, certificates, personal identifiers, customer names, repository paths, and environment-specific hostnames before allowed external calls.
- Log provider, model, user, time, context class, redaction result, token counts, policy decision, and request digest. Do not store raw restricted prompt content in the model audit record.
- Never reroute a failed model request to another provider unless that exact fallback route was approved in advance. Fall back to local or manual operation when policy permits.

Network policy
- Start at E1 private-only. Allow the appliance to reach customer-approved private Git, identity, secrets, mirror, storage, SIEM, and local model endpoints. Deny public internet egress.
- Support E0 air-gapped, where updates, packages, licenses, and models arrive only through signed offline bundles.
- Support E2 approved-vendor egress, where only named model and update endpoints can pass through the configured proxy and policy service.
- Support E3 managed support as an additional opt-in export path for customer-reviewed diagnostics or telemetry.
- Enforce the selected level with nftables and an application egress proxy. Record policy changes and denied connections in the local audit log.
- Do not require OpenFactory-hosted APIs, telemetry, authentication, licensing, or storage for local fleet operation.

Updates, attestation, and rollback
- Verify every update against a pinned public trust root and an anti-rollback version before installation.
- Replace the appliance base as one unit while preserving the customer data disk. Keep the prior base and a pre-migration database snapshot until post-update checks pass.
- Provide online, customer-mirror, and signed offline update inputs that use the same verification path.
- Produce a local health and attestation report containing the appliance version, source provenance, package manifest digest, boot measurements when available, service status, policy version, and data migration version.
- Block regulated deployment actions when required attestation fails. Leave read-only evidence review and incident export available.
- Generate support bundles locally. Apply secret and path redaction, show the file list and size to the operator, and export only after approval. Never upload a support bundle automatically.

Failure behavior
- If an external model is unavailable or a request violates policy, keep the data local and return the policy or availability reason.
- If the secrets backend is unavailable, fail secret-dependent work closed. Allow local work that needs no secret.
- If /dev/kvm is unavailable, keep the console and evidence store online but block image builds and VM tests with a specific readiness error.
- If the update source is unavailable, keep the installed version running and accept a signed offline bundle.
- If startup migration or health checks fail after an update, restore the prior base and database snapshot and record the rollback.

Validation
- Boot the QCOW2 image on KVM with a persistent data disk, complete first-boot setup, and confirm the configured HTTPS URL responds.
- Confirm the site, build workspace, console, API health endpoint, MCP health endpoint, PostgreSQL, policy service, evidence store, and update service are active after reboot.
- Confirm all internal ports are unavailable from an untrusted network and the single HTTPS entry point is reachable from the management network.
- Confirm public internet egress is denied at E1 and that an allowlisted private endpoint remains reachable.
- Send test requests for every context class through a local mock model endpoint. Confirm external secret-bearing and export-prohibited requests are blocked and no automatic provider fallback occurs.
- Seed canary passwords, tokens, private keys, personal identifiers, and hostnames. Confirm they do not appear in model audit records, service logs, build artifacts, or a generated support bundle.
- Start a nested KVM guest, build one minimal Debian image, run its boot test, and retain the recipe, logs, SBOM, test result, and artifact digest in the local evidence store.
- Reboot and confirm the admin configuration, evidence, model policy, and build artifact persist on the customer data disk.
- Apply a valid signed test update, reject an update with an invalid signature, then force a failed post-update check and confirm automatic rollback preserves the prior working state.
- Verify the final artifact manifest signature outside the appliance.

Documentation
- Include an operator guide covering KVM and Proxmox import, CPU passthrough, nested virtualization, virtual TPM attachment, persistent-disk backup, first-boot setup, local DNS and TLS, egress policy, model configuration, offline updates, rollback, support bundles, and disaster recovery.
- Mark the image and documentation as a technical preview. State which acceptance checks passed, which require customer infrastructure, and which remain blocking gaps.

The acceptance bar

The appliance name is earned only when a fresh image survives first boot, a nested guest build, policy denial tests, secret-canary checks, signed update verification, and forced rollback. Missing virtualization or secrets infrastructure must produce a specific blocked state, while evidence review and other unaffected local functions stay available.

• Boot the image, attach customer state, finish local setup, and reach the site, build workspace, console, API, and MCP endpoint over one HTTPS entry point.
• Build and boot a minimal Debian guest through nested KVM, then retain its recipe, SBOM, logs, test result, and digest locally.
• Deny public egress at E1 while allowing a named private endpoint, and prove that secret-bearing model requests cannot leave.
• Seed canary secrets and confirm that none appear in logs, artifacts, model audit records, or a reviewed support bundle.
• Accept a correctly signed update, reject a bad signature, and restore the prior base and database snapshot when a health check fails.

Missing hardware or a missing secrets backend should produce a useful blocked state. A compatibility service that returns green is not evidence that a builder, attestation service, or policy route works.

Open source includes the build definition

The planned release license is MIT. The source release needs more than the application code: the image recipe, service units, dependency pins, provenance format, update verification path, and acceptance tests need to be inspectable too. Otherwise an operator can read the app and still cannot reproduce the computer that runs it.

That release has not happened yet, so this page does not point at a source repository or image download. The immediate purpose of the reference prompt is to make the promise testable. When the artifact is published, its behavior can be compared with this contract instead of a softer launch announcement.