Orgo - Cloud computers for AI agents

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

import requests

url = "https://www.orgo.ai/api/templates/run"

payload = { "ref": "default/my-template@1.0.0" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({ref: 'default/my-template@1.0.0'})
};

fetch('https://www.orgo.ai/api/templates/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.orgo.ai/api/templates/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ref' => 'default/my-template@1.0.0'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.orgo.ai/api/templates/run"

	payload := strings.NewReader("{\n  \"ref\": \"default/my-template@1.0.0\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.orgo.ai/api/templates/run")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ref\": \"default/my-template@1.0.0\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/templates/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ref\": \"default/my-template@1.0.0\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "desktop_id": "<string>",
  "status": "<string>",
  "vnc_password": "<string>",
  "public_host": "<string>",
  "resolution": "<string>",
  "desktop_api_token": "<string>",
  "ip": "<string>",
  "novnc_port": 123,
  "api_port": 123,
  "vcpus": 123,
  "mem_mb": 123,
  "disk_size_gb": 123,
  "bandwidth_limit_mbps": 123,
  "audio_enabled": true,
  "template_ports": {},
  "launch": {
    "hypervisor": "<string>",
    "cpu": "<string>",
    "host_cpu": {},
    "qemu": "<string>",
    "machine": "<string>",
    "boot": "<string>",
    "fallback": "<string>",
    "state": {}
  }
}

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 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 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

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. 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 four added fields: desktop_id, desktop_api_token, public_host and launch.

string

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.

string

Bearer token for the computer’s Desktop API: /bash, /terminal, /events. Send it verbatim. Equal to vnc_password.

string

Public hostname of the fleet host this preview was placed on.

object

What the preview runs on: the host’s launch record (hypervisor, cpu, host_cpu, qemu, machine, boot, fallback, state), without the host’s name or the source its state was restored from. Absent when the host does not report one.

string

The preview’s id on the fleet host. DELETE also accepts this value.

string

Current status.

string

VNC / WebSocket token for the preview.

string

The computer’s address on the host’s private network.

integer

Host port serving noVNC / websockify.

integer

Host port serving the Desktop API.

string

Display resolution, WIDTHxHEIGHTxDEPTH.

integer

vCPU count the preview booted with.

integer

RAM in MB.

integer

Disk in GB.

integer

Network bandwidth cap in Mbps.

boolean

Whether the audio device is enabled.

object

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 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 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.
`403`	`{ "error": "This endpoint requires an account-wide credential (workspace_scope_mismatch).", "code": "workspace_scope_mismatch" }`	The key is workspace-scoped. Template endpoints need an account-wide key.
`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 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.
`503`	`{ "error": "Service temporarily unavailable. …" }`	Orgo could not verify the key because of a server-side fault. The key is fine. Retry. The response carries `Retry-After: 5`.
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": "golden_unavailable" }`	The built snapshot is missing. Build it again.
`503`	`{ "error": string, "code": "TEMPLATE_HOST_UNAVAILABLE" }`	No host that runs templates could take this run. Retry.
`503`	`{ "error": string, "code": "FLEET_CAPACITY_FULL" \| "DEDICATED_CAPACITY_FULL", "retryable": true }`	The fleet, or your dedicated pool, is full. Retry.
`503`	`{ "error": string, "code": "TEMPLATE_READINESS_UNAVAILABLE", "retryable": true }`	Orgo could not determine whether the build is ready. Retry.
`503`	`{ "error": string }`	No fleet host was available, or a custom plan’s limits could not be read. 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: 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.

string

The preview's id on the fleet host. DELETE /templates/run also accepts it.

desktop_id

string

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

string

vnc_password

string

public_host

string

Public hostname of the fleet host the preview was placed on.

resolution

string

desktop_api_token

string

Bearer token for the computer's Desktop API. Equal to vnc_password.

string

The computer's address on the host's private network.

novnc_port

integer

Host port serving noVNC / websockify.

api_port

integer

Host port serving the Desktop API.

vcpus

integer

mem_mb

integer

disk_size_gb

integer

bandwidth_limit_mbps

integer

audio_enabled

boolean

template_ports

object

The template's public internal ports mapped to the host ports they were published on. Absent when the template exposes none.

Show child attributes

launch

object

How the host launched the preview, without the host's name. Absent when the host does not report it.

Show child attributes

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

import requests

url = "https://www.orgo.ai/api/templates/run"

payload = { "ref": "default/my-template@1.0.0" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({ref: 'default/my-template@1.0.0'})
};

fetch('https://www.orgo.ai/api/templates/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.orgo.ai/api/templates/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ref' => 'default/my-template@1.0.0'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.orgo.ai/api/templates/run"

	payload := strings.NewReader("{\n  \"ref\": \"default/my-template@1.0.0\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.orgo.ai/api/templates/run")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ref\": \"default/my-template@1.0.0\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/templates/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ref\": \"default/my-template@1.0.0\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "desktop_id": "<string>",
  "status": "<string>",
  "vnc_password": "<string>",
  "public_host": "<string>",
  "resolution": "<string>",
  "desktop_api_token": "<string>",
  "ip": "<string>",
  "novnc_port": 123,
  "api_port": 123,
  "vcpus": 123,
  "mem_mb": 123,
  "disk_size_gb": 123,
  "bandwidth_limit_mbps": 123,
  "audio_enabled": true,
  "template_ports": {},
  "launch": {
    "hypervisor": "<string>",
    "cpu": "<string>",
    "host_cpu": {},
    "qemu": "<string>",
    "machine": "<string>",
    "boot": "<string>",
    "fallback": "<string>",
    "state": {}
  }
}

Overview

API keys

Support

Account

Agent accounts

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Test-run a template

Request body

Response

Example

Stop a test-run

Errors

Authorizations

Body

Response

​Request body

​Response

​Example

​Stop a test-run

​Errors

Authorizations

Body

Response

Request body

Response

Example

Stop a test-run

Errors