Define a blueprint
A blueprint belongs to one factory. Leave Repository URL empty to use it across the factory, or set a repository URL for a more specific definition.initialize and post_build run in order from /workspace/repo. A failed command stops the build. maintenance and knowledge are stored for the start-from-snapshot flow and do not run during a snapshot build.
What a snapshot contains
A snapshot contains/workspace except blueprint archive.exclude matches, secret-like files detected under /workspace/repo, the agent home at /workspace/home, runtime-managed /workspace/.orq content, and generated repo/.orq/blueprint.md context. Agent state, package-manager caches written to $HOME, factory skills, MCP configuration, and blueprint context are always recreated for each session and are never restored from another session. Add generated caches or other reproducible large files to archive.exclude. The default compressed and extracted-size limit is 5 GiB.
Build a snapshot
Select a blueprint, enter the project, repository, and ref, then click Build now. A build is a special agent session: no coding agent runs, but its event page shows each command’s output.
A ready row shows the repository commit, compressed size, and SHA-256 checksum. Failed build computers remain available for one hour for event inspection. Successful build computers are released immediately.
Start a session from a snapshot
When a session first checks out a repository, Orq.ai looks for a ready snapshot from the matching blueprint and Git ref. A pinned snapshot wins; otherwise the newest ready snapshot is selected. An empty ref represents the repository’s default branch. The control plane signs a download URL for five minutes. The computer streams the archive directly into/workspace, checks the compressed size and SHA-256 checksum, verifies the archived Git commit, then fetches and fast-forwards the requested ref. It does not create a temporary archive copy. An explicit commit, tag, or branch can be newer than the snapshot because the final fetch resolves it from origin.
Restore is an optimization, never a prerequisite. A missing, expired, corrupt, oversized, or otherwise invalid snapshot emits session.restore_failed and the computer performs a normal clone. A successful restore records snapshot_id on the session and emits session.restored with the snapshot age, compressed size, and restore duration.
After restore, the computer writes .orq/blueprint.md in the repository and adds an AGENTS.md pointer to it. The page contains the snapshot id and build time, maintenance commands, and the blueprint knowledge table. Set the factory default run_maintenance_on_start to run maintenance[] before the first agent run. It defaults to false; when enabled, progress appears as maintenance.step.started, maintenance.step.output, maintenance.step.completed, and maintenance.step.failed events.
The session header identifies the snapshot it started from. Factory Analytics compares the share of sessions restored from snapshots and time to first run with and without a snapshot.
Retention and pinning
Each blueprint keeps its three newest ready snapshots plus its pinned snapshot. Pin the known-good snapshot before building a replacement when a stable rollback point is required. Unpinned snapshots outside the retention window expire and their object archives are deleted by the Agent Sessions reconciler. Set Refresh every N h to rebuild a snapshot after the selected interval. The default is 24 hours;0 means manual builds only. Changing the blueprint specification also schedules a rebuild using the last successful build’s project, repository, ref, and SCM connection. The Settings page shows the latest build status, age, and size, the active snapshot, and the next refresh time. Pinning freezes session selection and keeps that snapshot out of garbage collection; refresh builds may continue until you unpin and select the newest ready snapshot.
Factory as code
factory.yaml supports factory default run_maintenance_on_start and a top-level blueprints[] list with refresh.interval_hours and pinned_snapshot_id. Export and apply manage blueprint definitions; snapshot builds remain operational actions. See the private ComputerBlueprintsService API under /v2/factories/{factory_id}/blueprints and /v2/computer-blueprints/{blueprint_id}.