> ## 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.
# Test-run a template
> Boot a short-lived preview computer from a template ref.
Boots a **short-lived, auto-reaped** computer from a template `ref`. This is the same in-editor “Run” that the dashboard uses to test a template before sharing it. The preview is reclaimed automatically, so a missed stop won't leak a computer.
Test-runs require a [Scale plan](https://orgo.ai/pricing) or higher: the preview is the authoring build-test, so it is gated the same way as publish and build. For a **persistent** computer, use [Create computer](/api-reference/computers/create) with `template_ref` instead. That is the durable path, and it counts toward the workspace owner's computer quota. A preview does not.
## Request body
Template ref to boot, in `namespace/name@version` form. Your own (`default/…`) or a curated (`system/…`) ref. The template's build must be `ready`. A missing or malformed `ref` returns `400`.
## Response
Returns the preview computer you connect to exactly like any other. The body is the fleet's create-computer shape plus three added fields.
The preview's identifier in Orgo. Use it as the `instance_id` in connection URLs (`wss://www.orgo.ai/desktops/{instance_id}/ws/websockify`, `…/ws/terminal`, `…/ws/audio`), and pass it back to stop the run.
Bearer token for the computer's Desktop API: `/bash`, `/terminal`, `/events`. Send it verbatim. Equal to `vnc_password`.
Public hostname of the fleet host this preview was placed on.
The preview's id on the fleet host. `DELETE` also accepts this value.
Current status.
VNC / WebSocket token for the preview.
The computer's address on the host's private network.
Host port serving noVNC / websockify.
Host port serving the Desktop API.
Display resolution, `WIDTHxHEIGHTxDEPTH`.
vCPU count the preview booted with.
RAM in MB.
Disk in GB.
Network bandwidth cap in Mbps.
Whether the audio device is enabled.
Map of the template's public `internal` ports to the host ports they were published on. Absent when the template exposes no public ports.
See [Create computer](/api-reference/computers/create) for the full connection model.
## Example
```bash Start theme={null}
curl -X POST https://www.orgo.ai/api/templates/run \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ref": "default/my-template@1.0.0"}'
```
```bash Stop theme={null}
# Stop the preview when you're done (id = desktop_id from the run response)
curl -X DELETE "https://www.orgo.ai/api/templates/run?id=$COMPUTER_ID" \
-H "Authorization: Bearer $ORGO_API_KEY"
```
## Stop a test-run
`DELETE /templates/run?id={instance_id}` stops the preview and reclaims it. Pass the `desktop_id` from the run response, or the `id`.
Returns `200` `{ "deleted": true }`, including when the preview was already gone. Omitting `id` returns `400` `{ "error": "id required" }`, and a request with no `Authorization` header returns `401` `{ "error": "Authentication required" }`. Any other upstream failure is forwarded with its own status and `{ "error": string }`. Previews are also reaped automatically.
## Errors
| Status | Body | Meaning |
| - | - | - |
| `400` | `{ "error": "invalid JSON body" }` | The body is not valid JSON. |
| `400` | `{ "error": "ref required" }` | No `ref` in the body. |
| `400` | `{ "error": string }` | `ref` is not in `namespace/name@version` form. The message starts with `invalid ref`. |
| `401` | `{ "error": "Invalid API key" }` | The Bearer token starts with `sk_` but is not a known Orgo key. |
| `401` | `{ "error": "Authentication required" }` | No `Authorization` header, or a Bearer token that is not an `sk_` key. |
| `401` | `{ "error": "This endpoint requires an account-wide credential (workspace_scope_mismatch)." }` | The key is workspace-scoped. Template endpoints need an account-wide key. This route answers with `401`, not `403`. |
| `401` | `{ "error": "Service temporarily unavailable. …" }` | Orgo could not verify the key because of a server-side fault. The key is fine. Retry. |
| `403` | `{ "error": string, "code": "UPGRADE_REQUIRED", "upgradeTier": "scale_v2" }` | Below Scale, or your plan could not be verified. The gate fails closed. |
| `403` | `{ "error": string, "code": "PLAN_LIMIT", "upgradeTier": "enterprise" }` | Your account is on a custom plan that does not include templates, or the template's hardware exceeds that plan's per-computer limit. |
| `409` | `{ "error": string, "code": "TEMPLATE_NOT_READY" }` | The template's build isn't `ready`, or the version does not exist. [Build it](/api-reference/templates/build) first. |
| `429` | `{ "error": string, "code": string }` | Run rate limit or concurrency cap reached, e.g. `vm_rate_limited` or `tenant_vm_limit`. Test-runs of curated (`system/…`) refs share these limits across all accounts. Back off and retry. |
| other `4xx` or `5xx` | `{ "error": string, "code"?: string, "upgradeTier"?: string }` | Any other failure from the fleet host is forwarded with the host's status. |
| `500` | `{ "error": "internal error" }` | Unexpected server error. |
| `500` | `{ "error": "could not prepare a preview connection for this run" }` | The preview booted but its connection record could not be stored, so it was torn back down. Retry. |
| `503` | `{ "error": string, "code"?: string, "retryable"?: true }` | The fleet couldn't serve this run: `golden_unavailable` (the built snapshot is missing), or `TEMPLATE_READINESS_UNAVAILABLE` (Orgo could not determine whether the build is ready), which carries `retryable: true`. A `503` with `error` alone means no fleet host was available, or a custom plan's limits could not be read. Retry. |
## OpenAPI
````yaml POST /templates/run
openapi: 3.1.0
info:
title: Orgo API
description: >-
Launch cloud computers that AI agents can control and interact with. Create
workspaces, provision computers, and control them programmatically.
version: 2.0.0
contact:
name: Orgo Support
email: spencer@orgo.ai
url: https://orgo.ai
servers:
- url: https://www.orgo.ai/api
description: Production
security:
- bearerAuth: []
tags:
- name: Account
description: >-
Account capacity: how many computers an account may run, and adding or
giving back more.
- name: Clients
description: >-
Run Orgo for your clients from your own app: a workspace and scoped key
each, billed to you or to them.
- name: Workspaces
description: Organize computers into named workspaces
- name: Computers
description: Provision and manage virtual computers
- name: Computer Lifecycle
description: Start, stop, and restart computers
- name: Computer Actions
description: Control mouse, keyboard, and execute commands
- name: Screens
description: >-
More than one desktop on a single computer. Each screen is its own X
server with its own cursor and window manager, so an agent working on one
cannot disturb another.
- name: Files
description: Upload and download files
- name: Templates
description: Author, build, and launch reproducible computers from templates
paths:
/templates/run:
post:
tags:
- Templates
summary: Test-run a template
description: >-
Boots a short-lived, auto-reaped preview computer from a template ref -
the in-editor test run. Requires a Scale plan. For a persistent
computer, use POST /computers with template_ref instead.
operationId: testRunTemplate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- ref
properties:
ref:
type: string
example: default/my-template@1.0.0
responses:
'200':
description: Preview computer booted
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateRunResponse'
'400':
description: >-
The body is not valid JSON, `ref` is missing, or `ref` is not in
`namespace/name@version` form (the message starts with `invalid
ref`).
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateError'
examples:
json:
summary: Not JSON
value:
error: invalid JSON body
missing:
summary: No ref
value:
error: ref required
'401':
$ref: '#/components/responses/UnauthorizedTemplates'
'403':
description: >-
Below Scale, or your plan could not be verified (`UPGRADE_REQUIRED`;
the gate fails closed), or your account is on a custom plan that
does not include templates, or whose per-computer limit the
template's hardware exceeds (`PLAN_LIMIT`).
content:
application/json:
schema:
$ref: '#/components/schemas/QuotaError'
examples:
upgrade:
summary: Below Scale
value:
error: …
code: UPGRADE_REQUIRED
upgradeTier: scale_v2
plan-limit:
summary: A custom plan that does not include templates
value:
error: >-
Your plan doesn't include building templates. Contact us
to add them to your plan.
code: PLAN_LIMIT
upgradeTier: enterprise
plan-hardware:
summary: >-
The template's hardware exceeds a custom plan's per-computer
limit
value:
error: >-
This computer asks for 16GB RAM, but your plan allows 8GB
per computer. Pick a smaller size, or contact us to change
your plan.
code: PLAN_LIMIT
upgradeTier: enterprise
'409':
description: >-
The template's build is not `ready`, or the version does not exist.
Build it first.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateError'
example:
error: …
code: TEMPLATE_NOT_READY
'429':
description: >-
Run rate limit or concurrency cap reached, such as `vm_rate_limited`
or `tenant_vm_limit`. Back off and retry.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateError'
example:
error: …
code: tenant_vm_limit
'500':
description: >-
Unexpected server error, or the preview booted but its connection
record could not be stored, so it was torn back down. Retry.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateError'
examples:
internal:
summary: Unexpected
value:
error: internal error
connection:
summary: Connection record not stored
value:
error: could not prepare a preview connection for this run
'503':
description: >-
The fleet could not serve this run: `golden_unavailable` (the built
snapshot is missing), or `TEMPLATE_READINESS_UNAVAILABLE` (Orgo
could not determine whether the build is ready), which carries
`retryable: true`. A `503` with `error` alone means no fleet host
was available, or a custom plan's limits could not be read. Any
other failure from the fleet host is forwarded with the host's
status.
content:
application/json:
schema:
$ref: '#/components/schemas/BackendError'
examples:
golden:
summary: Snapshot missing
value:
error: …
code: golden_unavailable
readiness:
summary: Build readiness could not be determined
value:
error: …
code: TEMPLATE_READINESS_UNAVAILABLE
retryable: true
plan:
summary: A custom plan's limits could not be read
value:
error: Could not verify your plan. Try again.
components:
schemas:
TemplateRunResponse:
type: object
description: >-
A short-lived preview computer booted from a template ref: the fleet's
create-computer shape plus `desktop_id`, `desktop_api_token`, and
`public_host`. Connect to it like any computer; it is auto-reaped.
properties:
id:
type: string
description: >-
The preview's id on the fleet host. `DELETE /templates/run` also
accepts it.
desktop_id:
type: string
description: >-
The preview's identifier in Orgo. Use it as the `instance_id` in
connection URLs and pass it to `DELETE /templates/run?id=` to stop
the run.
status:
type: string
vnc_password:
type: string
public_host:
type: string
description: Public hostname of the fleet host the preview was placed on.
resolution:
type: string
desktop_api_token:
type: string
description: >-
Bearer token for the computer's Desktop API. Equal to
`vnc_password`.
ip:
type: string
description: The computer's address on the host's private network.
novnc_port:
type: integer
description: Host port serving noVNC / websockify.
api_port:
type: integer
description: Host port serving the Desktop API.
vcpus:
type: integer
mem_mb:
type: integer
disk_size_gb:
type: integer
bandwidth_limit_mbps:
type: integer
audio_enabled:
type: boolean
template_ports:
type: object
additionalProperties:
type: integer
description: >-
The template's public `internal` ports mapped to the host ports they
were published on. Absent when the template exposes none.
TemplateError:
type: object
description: >-
A failure from the template registry, relayed with the registry's own
status and code.
required:
- error
properties:
error:
type: string
code:
type: string
description: Machine-readable reason, when the registry supplied one.
details:
description: >-
Per-field validation errors, or the raw upstream body when it was
not JSON.
oneOf:
- type: array
items:
$ref: '#/components/schemas/ValidationError'
- type: string
QuotaError:
type: object
description: >-
The request was refused by the plan the workspace owner is on rather
than by ownership. See https://orgo.ai/pricing for what each plan
includes.
required:
- error
properties:
error:
type: string
code:
type: string
description: >-
Machine-readable reason. Values this API emits: `UPGRADE_REQUIRED`,
`DESKTOP_LIMIT`, `VM_SLOT_ADDON`, `RAM_ADDON`,
`PER_COMPUTER_RAM_CAP`, `VCPU_ADDON`, `PER_COMPUTER_CPU_CAP`,
`DISK_QUOTA_EXCEEDED`, `disk_exceeds_quota`,
`WINDOWS_REQUIRES_SCALE`, `GUEST_RESTRICTED`, `NOT_A_MEMBER`,
`CHANGE_PLAN`, `PLAN_LIMIT`, `upgrade_required`.
upgradeTier:
type: string
description: The plan that would allow the request.
canManageCapacity:
type: boolean
description: True when you own the workspace and can raise the limit yourself.
max_ram_gb:
type: integer
description: >-
On a RAM refusal from resize: the largest RAM a live resize can
reach for this computer.
max_disk_gb:
type: integer
description: 'On a storage refusal: the largest disk this computer may have.'
BackendError:
type: object
description: The fleet could not satisfy the request right now. Retry.
required:
- error
properties:
error:
type: string
code:
type: string
description: >-
`golden_unavailable`, `TEMPLATE_HOST_UNAVAILABLE`,
`TEMPLATE_READINESS_UNAVAILABLE`, `DEDICATED_CAPACITY_FULL`,
`FLEET_CAPACITY_FULL`, `GPU_HOST_UNAVAILABLE`, or
`BACKEND_UNAVAILABLE`.
retryable:
type: boolean
description: Present and `true` on the capacity failures a later retry can clear.
ValidationError:
type: object
properties:
field:
type: string
description: Dotted path to the offending field.
example: hardware.cpu
code:
type: string
example: invalid_enum
message:
type: string
hint:
type: string
Error:
type: object
description: >-
The base error body. Every failure carries `error`; individual endpoints
add the fields named in the schemas below.
required:
- error
properties:
error:
type: string
description: Human-readable message.
example: Access denied
code:
type: string
description: >-
Machine-readable reason. Present on the failures that define one,
absent otherwise.
responses:
UnauthorizedTemplates:
description: >-
No usable credential, or a workspace-scoped key. Template endpoints need
an account-wide key and answer a scoped one with `401`, not `403`. A
server-side fault while verifying the credential also returns `401`,
with a `Service temporarily unavailable` message. Retry that one; the
key is fine.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid-key:
summary: The key is not one of yours
value:
error: Invalid API key
no-credential:
summary: No key and no session
value:
error: Authentication required
account-wide-required:
summary: The API key is workspace-scoped
value:
error: >-
This endpoint requires an account-wide credential
(workspace_scope_mismatch).
service-unavailable:
summary: Server-side fault while verifying the credential. Retry.
value:
error: >-
Service temporarily unavailable. The database is not accepting
requests. Retry shortly.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your key at orgo.ai/workspaces
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.