> ## 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 quickstart
> Launch a curated template, then author and ship your own.
Two paths. Launching a curated template is one API call on any paid plan. Authoring your own takes a few minutes and a [Scale plan](https://www.orgo.ai/#pricing). This page covers both.
```bash theme={null}
export ORGO_API_KEY=sk_live_...
export WORKSPACE_ID=550e8400-e29b-41d4-a716-446655440000
```
## Launch a curated template
The fastest way to see templates in action: launch a computer from one Orgo maintains. Pass its `ref` as `template_ref` to [Create computer](/api-reference/computers/create). The computer starts from the prebuilt golden snapshot with everything already installed.
Creating a computer from a curated template needs a paid plan, the same as any other computer. It does not need a Scale plan; that is only for publishing your own.
Curated templates live in the `system` namespace, for example `system/coding@1.0.3`. Call [List curated templates](/api-reference/templates/list-curated) for the current catalog and its exact refs.
```bash cURL theme={null}
curl -X POST https://www.orgo.ai/api/computers \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"workspace_id\": \"$WORKSPACE_ID\",
\"name\": \"claude-1\",
\"template_ref\": \"system/coding@1.0.3\"
}"
```
```python Python theme={null}
import os, requests
r = requests.post(
"https://www.orgo.ai/api/computers",
headers={"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"},
json={
"workspace_id": os.environ["WORKSPACE_ID"],
"name": "claude-1",
"template_ref": "system/coding@1.0.3",
},
)
computer = r.json()
print(computer["id"], computer["status"])
```
```javascript JavaScript theme={null}
const r = await fetch("https://www.orgo.ai/api/computers", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ORGO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
workspace_id: process.env.WORKSPACE_ID,
name: "claude-1",
template_ref: "system/coding@1.0.3",
}),
});
const computer = await r.json();
console.log(computer.id, computer.status);
```
The computer boots with Claude Code and Codex already installed, each in its own terminal session. Browse the full catalog with [List curated templates](/api-reference/templates/list-curated).
Hardware in the request overrides the template's defaults. Add `"cpu"` and `"ram"` to launch the same template on a bigger computer. A value above your plan's per-computer limit returns `403`.
From the [CLI](/guides/cli), `orgo templates list` shows the catalog and `orgo templates run system/coding@1.0.3 --name claude-1` launches the same computer.
***
## Author your own
Now build a template from scratch. This section recreates a minimal Claude Code environment so you can see every step. It publishes to your own `default` namespace as `default/claude-code@1.0.0`. That is your private template, separate from the curated templates in the `system` namespace.
Publishing and building require a [Scale plan](https://www.orgo.ai/#pricing); below Scale, both return `403` with code `UPGRADE_REQUIRED`. Launching what you build counts against your normal computer quota.
Save this as `claude-code.yaml`. It declares the hardware, an optional secret, a build-time install, and the terminal session the browser attaches to.
```yaml claude-code.yaml theme={null}
api_version: orgo.ai/v1
template:
name: claude-code
version: 1.0.0
description: Claude Code CLI, ready in the terminal.
hardware:
cpu: 2
ram_gb: 4
resolution: 1280x720x24
# The launching user supplies this from their vault; injected at create time.
secrets:
- name: anthropic_api_key
description: Anthropic API key, used by Claude Code when set.
optional: true
# Baked into the golden snapshot at build time.
apps:
- name: claude-code
title: Claude Code
install: |
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code
# The tmux session the browser terminal attaches to by name.
terminal:
- name: claude-code
cwd: /root
```
Catch mistakes before publishing. [Validate](/api-reference/templates/validate) has no side effects.
```bash theme={null}
curl -X POST https://www.orgo.ai/api/templates/validate \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/yaml" \
--data-binary @claude-code.yaml
```
A clean template returns `200` with `{ "ok": true, "template": { … } }`. An invalid one returns `422` with `{ "ok": false, "errors": [ … ] }`, each entry carrying the exact `field`, a `code`, and a `message`.
[Publish](/api-reference/templates/publish) with `?auto_build=true` to register the ref and start baking the golden snapshot in one call.
```bash theme={null}
curl -X POST "https://www.orgo.ai/api/templates?auto_build=true" \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/yaml" \
--data-binary @claude-code.yaml
```
```json theme={null}
{
"ref": "default/claude-code@1.0.0",
"digest": "a1b2c3d4e5f6...",
"published": "2026-06-08T17:00:00Z",
"auto_build": "building",
"build": { "queued": true, "status": "queued", "job_id": "9f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f", "state": "queued", "phase": "queued", "tier": "standard", "ahead": 0 }
}
```
From the [CLI](/guides/cli), `orgo templates validate claude-code.yaml` checks the file, and `orgo templates publish claude-code.yaml --build` publishes it and starts the build.
Poll [Get build status](/api-reference/templates/build-status) until `status` is `ready`. The build runs on a dedicated build runner, which does not publish to [Stream build logs](/api-reference/templates/build-events), so polling is how you follow it.
```bash theme={null}
curl https://www.orgo.ai/api/templates/default/claude-code/1.0.0/build \
-H "Authorization: Bearer $ORGO_API_KEY"
# -> {"status": "building"} ... {"status": "ready"}
```
Once the build is `ready`, create a computer with your `template_ref`.
```bash theme={null}
curl -X POST https://www.orgo.ai/api/computers \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"workspace_id\": \"$WORKSPACE_ID\",
\"name\": \"claude-dev\",
\"template_ref\": \"default/claude-code@1.0.0\"
}"
```
The computer starts from the golden snapshot, with Node and Claude Code already installed and your terminal session ready. Poll `https://www.orgo.ai/api/desktops/{instance_id}/proxy/health` until it returns `200`, then connect. See [Create computer](/api-reference/computers/create) for the full response and connection details.
## Iterate
Refs are immutable, so you have two ways to ship a change:
* **Bump the version:** `1.0.0` → `1.0.1`. The clean path for anything you've shared.
* **Force-replace:** re-publish the same version with [`?force=true`](/api-reference/templates/publish) while you're still iterating locally.
```bash theme={null}
curl -X POST "https://www.orgo.ai/api/templates?auto_build=true&force=true" \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/yaml" \
--data-binary @claude-code.yaml
```
## Next steps
Let users supply their own API keys.
Long-running processes with health checks.
Cron, file, HTTP, and metric triggers.
Every templates endpoint.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.