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

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 three added fields.

string

The preview’s identifier in Orgo. Use it as the instance_id in connection URLs (https://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.

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. The call is scoped to you, so an id you don’t own is a no-op. 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" \| "ref required" \| "invalid ref" }`	Unparseable body, no `ref`, or a `ref` that isn’t `namespace/name@version`.
`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": string, "code": "UPGRADE_REQUIRED", "upgradeTier": "scale_v2" }`	Below Scale, or your plan could not be verified. The gate fails closed.
`409`	`{ "error": string, "code": "TEMPLATE_NOT_READY" }`	The template’s build isn’t `ready`. Build it first.
`429`	`{ "error": string, "code": string }`	Run rate limit or concurrency cap reached, e.g. `vm_rate_limited` or `tenant_vm_limit`. Back off and retry.
`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), `TEMPLATE_HOST_UNAVAILABLE` (no template-capable host), or `FLEET_CAPACITY_FULL` / `DEDICATED_CAPACITY_FULL`, which carry `retryable: true`. A `503` with `error` alone means no fleet host was available at all.

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.

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

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

Overview

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