> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Reproducible cloud computers, defined in a single file and launched in seconds.

A template is a declarative spec for an Orgo computer. One file describes the hardware, the software to install, the services to run, the secrets it needs, and what the user sees on connect. Orgo builds that file once into a **golden snapshot**. Every launch starts from it in seconds, fully configured and identical every time.

Think of it as a `Dockerfile` for a full desktop computer: write it once, version it, and hand out reproducible computers from it.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/guides/templates/quickstart">
    Author, build, and launch your first template.
  </Card>

  <Card title="Schema reference" icon="file-code" href="/guides/templates/schema">
    Every field in the `orgo.ai/v1` format.
  </Card>

  <Card title="Secrets" icon="key" href="/guides/templates/secrets">
    Inject API keys without baking them in.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/templates/publish">
    Publish, build, and launch over HTTP.
  </Card>
</CardGroup>

## Why templates

Without a template, every new computer starts from a base image and you script the setup yourself: install packages, write config, start services, and wait for it all to converge. That work runs on every boot and drifts over time.

A template moves all of that to **build time**. The result is a snapshot that boots ready.

| | Base image + setup script | Template |
| - | - | - |
| Time to ready | Minutes of install on every boot | Seconds, restoring a prebuilt snapshot |
| Reproducibility | Drifts as packages and scripts change | Content-addressed, identical every launch |
| Definition | Imperative script you maintain | One declarative file, versioned |
| Services & health | You wire up supervisord and watchdogs | Declared once, managed for you |
| Sharing | Copy the script around | Publish a `ref`, launch it into any of your workspaces |

## Golden snapshots

When you **build** a template, Orgo boots a real computer, runs your install steps, then pauses it and captures its full state (disk, memory, and CPU) as a *golden snapshot*. Launching a computer from the template copies that snapshot and resumes it, unless the launch has to cold-boot from the snapshot's disk instead.

* **Build once:** rebuild only when the template changes.
* **Launch in seconds:** a launch skips the entire install phase.
* **Content-addressed:** the snapshot is keyed by a SHA-256 `digest` of the canonical template. Two identical templates share a build. Change one byte and you get a new digest.

This is why a template computer comes up with Node already installed and your service already running, while a base image would still be downloading packages.

<Note>
  A launch that injects your [secrets](/guides/templates/secrets), or lands on a host that cannot restore the snapshot's memory, cold-boots from the snapshot's disk instead, and the `on_every_boot` [hook](/guides/templates/schema#hooks) runs. `on_first_boot` runs only during the build, and launched computers do not run `on_resume`.
</Note>

## Lifecycle

<Steps>
  <Step title="Write">
    Author a template in YAML or JSON using the [`orgo.ai/v1`](/guides/templates/schema) format. A short [sugar form](/guides/templates/schema#sugar-form) keeps simple templates tiny.
  </Step>

  <Step title="Publish">
    `POST` the document to your registry. Refs are immutable and content-addressed: `namespace/name@version`.
  </Step>

  <Step title="Build">
    Bake the golden snapshot, and poll its build status until `ready`.
  </Step>

  <Step title="Launch">
    Create a computer with `template_ref`. It starts from the golden snapshot, pre-configured.
  </Step>
</Steps>

```text theme={null}
WRITE  →  PUBLISH  →  BUILD  →  LAUNCH
 yaml     registry    golden    seconds
          immutable    once     per computer
```

## Refs

Every template version is addressed by a **ref**:

```text theme={null}
namespace / name @ version
   default / my-template @ 1.0.0
```

* **namespace:** groups your templates. Your own default to `default`. Curated templates published by Orgo live in the `system` namespace (for example, `system/coding@1.0.3`).
* **name:** lowercase kebab-case.
* **version:** semver, immutable once published. Bump it to ship a change.

Pass a ref as `template_ref` to [Create computer](/api-reference/computers/create), or anywhere the API takes a template.

## Curated vs. your own

<CardGroup cols={2}>
  <Card title="Curated templates" icon="star">
    Published and maintained by Orgo in the `system` namespace: Coding (Claude Code and Codex), OpenClaw, and Hermes Agent. **Any paid plan can launch them.** Browse with [List curated templates](/api-reference/templates/list-curated).
  </Card>

  <Card title="Your templates" icon="user">
    Author and publish your own on a **Scale** plan. They live in your namespaces and launch into your workspaces.
  </Card>
</CardGroup>

<Note>
  **Plan requirements.** Creating a computer from a template is a computer create like any other: it needs a paid plan and counts against the workspace owner's computer quota. When the workspace owner is on the free plan, that quota is zero, so a launch, curated or your own, returns `403` with code `UPGRADE_REQUIRED`. **Publishing, building, and test-running** your own templates additionally require a **Scale** plan. See [pricing](https://www.orgo.ai/#pricing).
</Note>

## What goes in a template

A quick tour. See the [schema reference](/guides/templates/schema) for every field.

| Field | What it does |
| - | - |
| `hardware` | CPU, RAM, disk, resolution, audio, bandwidth |
| `build` | `apt` / `pip` / `npm` / `run` steps baked into the snapshot |
| `apps` | Installed apps with long-running [services and health checks](/guides/templates/schema#apps) |
| `files` | Inline or fetched files written into the computer |
| `env` + `secrets` | Environment variables and [vault-injected secrets](/guides/templates/secrets) |
| `triggers` | [Reactive automation](/guides/templates/triggers): a source fires, actions run |
| `terminal` | Pre-staged tmux sessions the browser terminal attaches to |
| `hooks` | Shell that runs at [lifecycle points](/guides/templates/schema#hooks). Today only the first-boot and every-boot hooks run |
| `egress_policy` | Per-computer domain/IP allow or block rules |

## Next steps

<CardGroup cols={2}>
  <Card title="Build your first template" icon="rocket" href="/guides/templates/quickstart">
    A complete walkthrough, end to end.
  </Card>

  <Card title="See real examples" icon="book-open" href="/guides/templates/examples">
    Annotated curated templates you can copy.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.