> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Computer blueprints > Prepare repository dependencies once, build portable computer snapshots, and manage snapshot retention for an agent factory. Beta Computer blueprints prepare a repository before an agent starts working. A build clones the repository into a temporary computer, runs the blueprint commands, and stores the prepared workspace as a compressed snapshot. Open **Managed Agents** > **Factories**, choose a factory, then go to **Settings** > **Computer blueprints**. Builds have their own concurrency limit and do not consume the factory's agent-session limit. ## 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. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} base_computer_template: coding-session-gvisor initialize: - bun install --frozen-lockfile maintenance: - bun install --frozen-lockfile knowledge: verify: command: bun nx affected -t test description: Run affected tests before handoff. post_build: [] env: CI: 'true' archive: exclude: - repo/.nx/cache/** timeouts: step_seconds: 1800 archive_seconds: 1200 build_seconds: 3600 ``` `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. | Event | Meaning | | ------------------------------------------------ | -------------------------------------------------- | | `build.step.started` / `build.step.output` | A command started or produced output. | | `build.step.completed` / `build.step.failed` | A command finished. | | `snapshot.build.started` | The build session is ready and the pipeline began. | | `snapshot.build.ready` / `snapshot.build.failed` | The snapshot reached a terminal state. | 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}`.