Your First Build

This walkthrough creates, validates, builds, and inspects one custom image. A validated recipe is a configuration check, not proof that the ISO has built or that every requested behavior passed a VM test.

Before You Start

• Sign in so the conversation and build remain attached to your account.
• Start with one operating system and a small set of packages or services.
• Decide what evidence would prove the request was met. Package presence, service state, a listening port, and GUI behavior are different assertions.

For a first run, avoid credentials and private repository URLs in chat. Add secrets later through the supported credential workflow rather than baking them into an image.

1. State the Outcome and Its Checks

Example:

Build a Debian 13 server image with OpenSSH and curl.
Create a password-locked deploy user in the sudo group.
Verify that the image boots, the deploy user exists, the ssh service is
enabled, and curl is installed. Do not add Docker or a desktop.

Specific exclusions help distinguish an intentional minimal image from a request the planner simply missed.

2. Inspect the Recipe Preview

Check at least:

• base_image matches the requested distribution and release;
• requested packages appear under os.packages or are supplied by an explicit feature;
• users, groups, services, networking, installer, and desktop choices match the request;
• scenarios contain the checks you actually need;
• no unrequested package, desktop, installer, credential, or external repository was introduced.

Ask for changes in the same conversation. Follow-up requests are applied to the active recipe. When Validate Recipe is used, the backend preserves the preceding substantive chat request and blocks the recipe if explicit requirements are still missing; the generated control sentence is not allowed to erase the conversation’s intent.

Validation can still miss an unavailable package, an upstream outage, a distro-specific build failure, or behavior that has no test. Read the preview as a proposed contract.

3. Start the Build Once

Select Start Build on the validated preview. A successful click creates a build ID. Keep that ID when reporting a problem; it is more reliable than a percentage or a screenshot alone.

The build panel can show states such as queued, planning, configured, building, finalizing, completed, failed, or cancelled. A queued build may be waiting for worker capacity or startup recovery. A displayed percentage is a progress projection, not a deadline; some packaging and filesystem steps take much longer than others.

You can continue following the build in its live build panel even if you leave the original chat view. Reloading should reconnect through persisted build state and the event stream. Do not click Start Build repeatedly unless the UI reports that no build ID was created or the prior build reached a terminal state.

4. Separate Image Completion from Test Completion

An image may finish before its selected VM verification reaches a terminal state. Read both:

• build status: whether a durable artifact was assembled and finalized;
• test status: not_run, running, passed, failed, or error;
• certification status, when present: the result of the configured evidence policy, not a universal security or hardware certification.

Open the test details. Confirm each requested assertion ran against the expected guest and inspect failures or skipped checks. A passing boot test does not prove an application opens; a package record does not prove its service is healthy.

5. Inspect and Download the Artifact

Before downloading, compare the final recipe and package/test evidence with the request. Record the build ID, artifact filename, size, and checksum when shown.

Use the build’s download action only after artifact finalization completes. The download package may contain the ISO and related evidence. If download returns Failed to create download package, not found, or another JSON error:

1. confirm you are signed in as the build owner;
2. reopen the exact build rather than an older conversation card;
3. verify artifact finalization is complete and the ISO is listed;
4. retry once;
5. report the build ID, timestamp, displayed build/test/finalization states, and exact error text.

Do not rebuild merely to work around an ownership or packaging error; that can discard useful diagnostic state and consume another build slot.

6. Test the ISO in Its Intended Context

Booting in OpenFactory’s VM verifies only the configured virtual environment. For an installable desktop, also test the installer path on a disposable disk. For physical deployment, separately test firmware mode, storage, graphics, networking, suspend, input devices, updates, and recovery on representative hardware.

Common Recovery Paths

Next Steps

• Understanding Recipes
• Recipe Schema
• Custom Assertions
• VNC Console