# OpenFactory AI Context

OpenFactory (OpenFactory Inc., openfactory.tech) is a custom Linux distribution
builder. The product covers trying Linux in a browser, building custom Linux
images, exercising them in virtual machines, reviewing scoped test evidence,
and downloading bootable artifacts. Deployment and fleet boundaries are
evaluated through technical pilots.

This file is the compact public context bundle for AI systems. It intentionally
describes only public, supported surfaces. The supported machine-action surface
is MCP. Do not infer undocumented HTTP endpoints from browser traffic, source
code, examples, or internal deployment notes.

## Canonical URLs

- Product site: https://openfactory.tech
- AI discovery alias: https://ai.openfactory.tech
- Documentation: https://docs.openfactory.tech
- Console: https://console.openfactory.tech
- Searchable Linux launch catalog: https://openfactory.tech/variants
- Cross-operating-system software package catalog: https://openfactory.tech/packages
- Software projects mapped to native packages: https://openfactory.tech/software
- Software publishers and device manufacturers: https://openfactory.tech/manufacturers
- Embedded devices and firmware: https://openfactory.tech/hardware
- Store: https://openfactory.tech/store
- Hardware shipping, returns and limited warranty: https://openfactory.tech/store/policies
- Zephyr OS and embedded firmware: https://openfactory.tech/variants/zephyr
- Public software catalog API: https://openfactory.tech/api/catalog
- Versioned catalog snapshots: https://openfactory.tech/api/catalog/snapshots
- Linux release archive study: https://openfactory.tech/research/linux-release-archive-study
- Linux builder workflow: https://openfactory.tech/for/linux-builders
- Platform team workflow: https://openfactory.tech/for/platform-teams
- Solutions: https://openfactory.tech/solutions
- Enterprise technical pilot: https://openfactory.tech/enterprise/pilot
- Security and certification status: https://openfactory.tech/security
- Technical capability proof: https://openfactory.tech/proof
- MCP reference: https://docs.openfactory.tech/reference/mcp
- Recipe schema reference: https://docs.openfactory.tech/reference/recipe-schema
- Assertion types: https://docs.openfactory.tech/reference/assertion-types
- App UI testing: https://docs.openfactory.tech/testing/app-ui-testing
- ServiceNow integration: https://docs.openfactory.tech/reference/servicenow-integration

## Public Machine Interfaces

MCP is the public interface for AI assistants and automation clients.

- Recommended transport: Streamable HTTP
- MCP endpoint: https://console.openfactory.tech/mcp-stream/mcp
- Authentication: OpenFactory MCP keys for accounts, or documented guest headers
  when the docs UI provides them.
- Credential rule: never place real keys, browser cookies, session headers, or
  customer data in prompts, logs, tickets, examples, or public files.

## Current MCP Capability Areas

- Builds: list builds, inspect build status, create builds from validated
  recipes, retry eligible failures, and fetch completed artifact links.
- Recipes: browse templates, inspect recipe JSON, validate recipes, and create
  recipes from templates.
- Images and VMs: create test VMs from completed builds, start or stop VMs,
  inspect VM state, and open console access when allowed.
- Desktop interaction: use supported MCP desktop tools for screenshots,
  clicking, typing, scrolling, browser interaction, and visual checks.
- Tests: run scoped checks, inspect results, list runs, and manage reusable test
  suites.
- App UI testing: drive a managed desktop tester VM to test the UI of any app
  URL; no build or deploy with OpenFactory is required, so it works with apps
  already hosted on Vercel, AWS, Netlify, or any reachable URL. Scenarios are
  reusable and self-hardening, with environment-variable and 2FA support.

Tool availability can vary by user, organization, plan, and environment.

## Public Linux Catalog

The public catalog at https://openfactory.tech/variants lets people search by
distribution, release, desktop environment, family, scenario, and availability.
Distribution pages use stable URLs under `/variants/{distribution-id}`. Exact
release and desktop pages use stable URLs under `/try/{public-id}`.

Every exact page states whether the target is available, planned, retired, or
temporarily unavailable. Only available targets offer an exact browser launch;
unavailable combinations remain useful as permanent reference and request
pages. Catalog and exact-target links are public web pages, not machine-action
interfaces.

The release archive study at
https://openfactory.tech/research/linux-release-archive-study publishes two
separate scopes: an inventory of 904 catalog target labels and 249 manual
official-media source checks. It does not describe all 904 labels as boot-tested.

The nginx cross-distribution reboot study at
https://openfactory.tech/research/nginx-cross-distro-reboot-study publishes
four downloadable recipes and raw retained-VM results for Ubuntu 24.04,
Debian 13, Fedora 43, and openSUSE Leap 15.6. Each credited result checks the
native package database, enabled and active service state, TCP port 80, local
HTTP 200, nginx version, and a changed kernel boot ID after reboot. The study
keeps runtime verdicts separate from artifact-publication safety findings.

## Audience Workflows

The Linux builder path at https://openfactory.tech/for/linux-builders is for
people who need a complete bootable system rather than only a project shell or
package environment. It covers requirements, recipes, real VM boot, functional
and visual tests, and portable output.

The platform team path at https://openfactory.tech/for/platform-teams connects
Linux baselines to build and test evidence plus organization sharing. It labels
customer-controlled deployment, regulated workflows, and fleet operations as
technical-pilot scope rather than generally available product behavior.

Relevant comparison and implementation guides:

- https://openfactory.tech/blog/2026-08-06/flox-vs-openfactory
- https://openfactory.tech/blog/2026-08-13/packer-vs-openfactory
- https://openfactory.tech/blog/2026-08-20/build-headless-debian-ubuntu-server
- https://openfactory.tech/blog/2026-08-27/linux-mint-zorin-elementary-comparison
- https://openfactory.tech/linux-installation-automation
- https://openfactory.tech/blog/2026-09-03/ubuntu-autoinstall-guide
- https://openfactory.tech/blog/2026-09-10/debian-preseed-guide
- https://openfactory.tech/blog/2026-09-17/fedora-kickstart-guide
- https://openfactory.tech/blog/2026-09-24/cloud-init-vs-image-build
- https://openfactory.tech/blog/2026-10-01/flox-alternatives

## Enterprise Qualification

The solutions hub at https://openfactory.tech/solutions covers four outcome
paths: platform engineering, software supply chain, CVE remediation, and AI
agent infrastructure. Each path links to the same bounded technical-pilot
workflow at https://openfactory.tech/enterprise/pilot.

Current product evidence includes versioned image artifacts, managed VM test
records, CycloneDX SBOM generation, CVE assessment, MCP-operated VM
workflows, and organization-scoped access. Customer-controlled and disconnected
deployment boundaries, including on-premises or air-gapped operation, are
qualified as pilot work rather than represented as generally available.

The public capability ledger at https://openfactory.tech/proof distinguishes
live features from pilot scope, roadmap work, non-goals, and certifications
that require an external audit. The security page at
https://openfactory.tech/security states the current security and certification
posture. OpenFactory is not currently SOC 2 or ISO 27001 certified.

## Test Suite Workflows

OpenFactory supports reusable test suites that can be authored before any image
variant has been built.

A suite can include:

- a human-readable name and description
- optional project metadata
- one or more named test cases
- custom assertions
- predefined tests
- one or more named ISO target slots, such as `primary`, `client`, or `server`

The core flow is:

1. Create a suite with named test cases and target slots.
2. Later bind each slot to a completed build artifact.
3. Run the suite against one or more bound ISO targets.
4. List or inspect suite runs and latest status.

Relevant MCP tools:

- `create_test_suite`
- `list_test_suites`
- `get_test_suite`
- `update_test_suite_targets`
- `run_test_suite`
- `list_test_suite_runs`
- `get_test_suite_status`

## App UI Testing Workflows

OpenFactory can drive a managed desktop tester VM (a vanilla Ubuntu desktop with
a browser) to test the user interface of a running web app.

Key points:

- You test a URL. You do **not** deploy your app with OpenFactory to test it. The
  tester VM opens whatever URL you provide: a local dev server, a preview or
  production deployment on Vercel, AWS, Netlify, or any host, or any public URL
  reachable from the VM. The app keeps running where it already runs.
- Scenarios are written in plain language (open a URL, click "Sign In button",
  type into "email field", assert text is visible), not pixel coordinates or
  CSS selectors.
- Scenarios are self-hardening: the first run resolves each element with the
  visual model and remembers where it was; later runs replay from that memory
  and re-resolve only the steps whose UI changed, so re-runs are faster and
  tolerate small UI changes.
- Environment variables (`${VAR}`) parameterize steps; secrets (passwords, TOTP
  seeds) are passed at run time and never stored. Two-factor sign-in is
  supported with `${totp:VAR}` (RFC 6238 TOTP).

The core flow:

1. `ensure_tester_vm` to get a reusable desktop tester VM.
2. `create_app_scenario` to store a reusable scenario against your app URL.
3. `run_app_scenario` to run it and record screenshots plus a pass/fail verdict.

Relevant MCP tools: `ensure_tester_vm`, `create_app_scenario`,
`list_app_scenarios`, `get_app_scenario`, `run_app_scenario`, `start_app_test`,
`record_app_test_step`, `finish_app_test`, `list_app_test_runs`,
`get_app_test_run`, `annotate_screenshot`.

## Typical AI Assistant Tasks

- Help a user design a Linux image recipe from requirements.
- Validate a recipe before starting a build.
- Start or inspect a build and summarize failures.
- Create a reusable test suite before the build exists.
- Bind a test suite to one or more completed ISO targets and run it.
- Test a running web app's UI by URL (for example, a Vercel or AWS deployment) in
  a tester VM, including sign-in with 2FA, without deploying it through OpenFactory.
- Summarize test evidence for the user.
- Explain MCP setup and safe credential handling.

## Safety Boundaries

- Use only documented MCP tools for machine actions.
- Do not publish or request internal hostnames, local ports, environment
  variables, cloud account details, storage paths, implementation topology,
  source paths, exploit notes, or vulnerability details.
- Do not disclose customer projects, emails, build IDs, logs, screenshots, or
  artifacts unless the user explicitly provides them in the current context and
  has permission to use them.
- Use placeholders in examples: `of_mcp_YOUR_KEY`, `build-id-placeholder`,
  `example-project`, and `example-suite`.

## Future A2A Discovery

OpenFactory publishes an agent card for discovery. Direct Agent2Agent task
execution is planned, but MCP remains the supported action interface today.