Skip to Content
Getting StartedUnderstanding recipes

Understanding recipes

A BuildRecipe is the normalized specification OpenFactory sends into the image pipeline. Chat can help author it, but the recipe, source snapshots, generated files, and test evidence are what define a build.

The mental model

The canonical recipe has four main layers:

  1. Identity and target: name, description, base image, and hardware intent.
  2. Operating system: features, packages, services, users, security, desktop, installer, attachments, and startup scripts under os.
  3. Verification: one or more scenarios with built-in tests and custom assertions.
  4. Delivery intent: requested publication destinations and optional delivery settings.
{
  "name": "debian-web-check",
  "display_name": "Debian Web Check",
  "description": "Small Debian image with explicit smoke tests.",
  "base_image": "debian-trixie",
  "hardware": {
    "platform": "pc",
    "architecture": "x86_64",
    "min_cpu_cores": 2,
    "min_memory_gb": 4,
    "min_storage_gb": 16,
    "nic_count": 1
  },
  "os": {
    "features": ["ssh"],
    "packages": ["curl"],
    "services": [
      {
        "name": "ssh",
        "enabled": true,
        "config": {"port": 22, "disable_password_auth": true}
      }
    ],
    "security": {
      "hardening_level": "standard",
      "audit_logging": true
    }
  },
  "scenarios": [
    {
      "id": "primary-smoke",
      "name": "Primary image smoke test",
      "enabled": true,
      "tests": ["boot", "login", "packages"]
    }
  ],
  "publish_to": ["local"]
}

Use snake_case. New integrations should not send legacy shapes such as baseImage, top-level features, or startupScripts.

Three checks, three different answers

Schema validation

Validation answers: “Does the recognized data have an acceptable shape?” It does not prove packages exist or behavior works. Some unknown fields are ignored for compatibility, so a validation success can still omit an important request.

Always compare the returned normalized recipe with the original chat and requirements. A missing desktop, application, installer, attachment, or test is a recipe defect even if validation says valid.

Build evidence

A successful build answers: “Did the pipeline produce an artifact?” It does not prove every intended feature made it into the image. Inspect the package inventory, source provenance, warnings, and build-stage evidence.

Guest verification

Guest tests answer narrow runtime questions: whether the VM booted, a service is active, a port listens, a file has expected content, or an application launched. A passing assertion supports only the behavior it actually observed.

Security settings are intent

The accepted hardening_level values are minimal, standard, and strict, but those labels are not portable compliance profiles. Target generators can interpret them differently. If you require a benchmark, select the exact applicable benchmark and retain per-control results; do not infer CIS conformance from strict.

Similarly, disk_encryption, audit_logging, SELinux, fail2ban, Secure Boot, dm-verity, and installer settings require matching artifact and runtime tests.

Chat and recipe ownership

When you validate or edit a chat-authored recipe, the existing conversation remains part of the authoring context. Validation should refine the current recipe, not silently replace it with a generic default. Even so, the normalized recipe is the final checkpoint before build.

For each material requirement:

  • find the corresponding normalized field;
  • confirm its value and target scope;
  • add an assertion where runtime proof is possible; and
  • preserve deployment-only work as an explicit warning rather than pretending it happened during image build.

Review checklist

  • Is the base image and architecture correct?
  • Are all requested desktop and application features present?
  • Are external sources pinned and licensed for the intended use?
  • Are secrets absent from saved recipe fields and scripts?
  • Is the installer configured and tested on a disposable disk if requested?
  • Do scenarios test the actual acceptance criteria?
  • Are unsupported or deployment-time requirements called out?

See Recipe Schema for the field reference and Your First Build for the build and download workflow.

Your First BuildBuild guides