Skip to main content
POST
/
templates
/
run
Test-run a template
curl --request POST \
  --url https://www.orgo.ai/api/templates/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ref": "default/my-template@1.0.0"
}
'
{
  "id": "<string>",
  "desktop_id": "<string>",
  "status": "<string>",
  "vnc_password": "<string>",
  "public_host": "<string>",
  "resolution": "<string>"
}
Boots a short-lived, auto-reaped computer from a template ref — the same in-editor “Run” that the dashboard uses to test a template before sharing it. The preview is reclaimed automatically after a period of inactivity.
Test-runs require a Scale plan. For a persistent computer, use Create computer with template_ref instead — that’s the durable path and it counts toward your plan’s computer quota.

​
Request body

​
ref
string
required
Template ref to boot, in namespace/name@version form. Your own (default/…) or a curated (system/…) ref. The template’s build must be ready.

​
Response

Returns a short-lived computer you connect to exactly like any other. The key fields:
​
desktop_id
string
The preview’s identifier. Build its connection URLs the same way as any computer (https://www.orgo.ai/desktops/{desktop_id}/…), and pass it back to stop the run.
​
id
string
The underlying VM id.
​
status
string
Current status.
​
vnc_password
string
VNC / WebSocket token for the preview.
See Create computer for the full connection model.

​
Example

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"}'

​
Stop a test-run

DELETE /templates/run?id={desktop_id} stops the preview and reclaims the VM. Previews are also reaped automatically, so a missed stop won’t leak a computer.

​
Errors

StatusMeaning
401Missing or invalid API key.
403Test-runs require a Scale plan or higher.
409The template’s build isn’t ready. Build it first.
429Run-VM rate limit or concurrency cap reached. Back off and retry.

Authorizations

​
Authorization
string
header
required

API key authentication. Get your key at orgo.ai/workspaces

Body

application/json
​
ref
string
required
Example:

"default/my-template@1.0.0"

Response

Preview computer booted

A short-lived preview computer booted from a template ref. Connect to it like any computer; it is auto-reaped.

​
id
string

Underlying VM id.

​
desktop_id
string

Ephemeral desktop id. Use it for same-origin connection URLs and to stop the run via DELETE /templates/run?id=.

​
status
string
​
vnc_password
string
​
public_host
string
​
resolution
string