Orgo - Cloud computers for AI agents

POST

computers

{id}

exec

Execute Python

curl --request POST \
  --url https://www.orgo.ai/api/computers/{id}/exec \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "import os\nprint(os.getcwd())",
  "timeout": 10
}
'

import requests

url = "https://www.orgo.ai/api/computers/{id}/exec"

payload = {
    "code": "import os
print(os.getcwd())",
    "timeout": 10
}
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({code: 'import os\nprint(os.getcwd())', timeout: 10})
};

fetch('https://www.orgo.ai/api/computers/{id}/exec', 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/computers/{id}/exec",
  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([
    'code' => 'import os
print(os.getcwd())',
    'timeout' => 10
  ]),
  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/computers/{id}/exec"

	payload := strings.NewReader("{\n  \"code\": \"import os\\nprint(os.getcwd())\",\n  \"timeout\": 10\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/computers/{id}/exec")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"code\": \"import os\\nprint(os.getcwd())\",\n  \"timeout\": 10\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/computers/{id}/exec")

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  \"code\": \"import os\\nprint(os.getcwd())\",\n  \"timeout\": 10\n}"

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

{
  "success": true,
  "action": "exec",
  "output": "/home/user\n",
  "timeout": false,
  "error": null,
  "error_type": null
}

Runs Python code on the computer and returns its output. Each call is a fresh interpreter, so nothing carries over between requests. On Linux the code runs with python3 -c, HOME=/root, DISPLAY=:99, and PATH=/usr/local/bin:/usr/bin:/bin. On Windows, the code is written to a temporary file and run with C:\Python312\python.exe from the user’s Desktop folder. The response carries stdout, stderr, exit_code, and output instead of the fields listed under Response, plus error when the code could not run. Code that runs out of time returns 200 with exit_code: 124 and error: "timeout".

Path parameters

string

required

Computer ID (UUID).

Body parameters

string

required

Python code to run. Missing, empty, or not a string returns 400.

integer

default:"10"

How long the code may run, in seconds. Optional, and always clamped to 1-300: a larger value silently becomes 300, and 0 or a non-numeric value becomes 10. Out-of-range values are never rejected.

exec takes no ?screen= parameter. Unlike the pointer and keyboard actions, sending one here is silently ignored rather than rejected. The code always runs against the computer’s default display.

Response

boolean

true only when the interpreter exited zero. Code that raises returns 200 with success: false, not an error status.

string

Always exec.

string

Combined stdout and stderr, in that order, joined by a newline when both are non-empty. An uncaught exception’s traceback arrives here, and it is the only place it appears.

boolean

Always false. Code killed by the timeout also returns false, so this field carries no information. Infer a timeout from success: false with truncated output instead.

string | null

Always null on a 200, including when the code raises. Read output for the traceback.

string | null

Always null on a 200. It never carries a Python exception class. Parse output if you need the exception name.

Example

curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/exec \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import os\nprint(os.getcwd())",
    "timeout": 10
  }'

import requests

response = requests.post(
    f"https://www.orgo.ai/api/computers/{computer_id}/exec",
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={
        "code": "import os\nprint(os.getcwd())",
        "timeout": 10
    }
)

result = response.json()
# `output` carries the traceback on failure; `error` is always null here.
print(result["output"])
if not result["success"]:
    print("Script exited non-zero")

const response = await fetch(`https://www.orgo.ai/api/computers/${computerId}/exec`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'import os\nprint(os.getcwd())',
    timeout: 10
  })
});

const result = await response.json();
// `output` carries the traceback on failure; `error` is always null here.
console.log(result.output);
if (!result.success) {
  console.error('Script exited non-zero');
}

Successful response

{
  "success": true,
  "action": "exec",
  "output": "/home/user\n",
  "timeout": false,
  "error": null,
  "error_type": null
}

Response when the code raises

Still a 200. The exception is in output; error and error_type stay null.

{
  "success": false,
  "action": "exec",
  "output": "Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nNameError: name 'undefined_var' is not defined\n",
  "timeout": false,
  "error": null,
  "error_type": null
}

For shell commands, use Execute bash instead.

Errors

Status	Meaning
`400`	`code` is missing, empty, or not a string: `{"error": "Code is required and must be a string"}`. Also returned when the computer has no VM attached: `{"error": "Desktop instance not available"}`.
`401`	Invalid API key: `{"error": "Invalid API key"}`. A request with no `Authorization` header returns `{"error": "Authentication required"}`. Access failures also return `401` on this endpoint, not `403`: `{"error": "You do not have access to this workspace."}` when you are neither the owner nor a member of the computer’s workspace, `{"error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)."}` for a view-only member, and `{"error": "This API key cannot access this workspace (workspace_scope_mismatch)."}` for a workspace-scoped key used outside its workspace. A server-side fault while verifying the credential also returns `401`, with `{"error": "Service temporarily unavailable. The database is not accepting requests. Retry shortly."}`. Retry that one; the key is fine.
`402`	The computer is a trial computer whose trial is not active: `{"error": "Choose a plan to continue."}`.
`404`	No computer with this id: `{"error": "Desktop not found"}`, plus a `hint` explaining that computer ids do not survive a rebuild.
`500`	The interpreter could not be started at all (with `upstream_status: 500`), or the request body is not valid JSON (with the parser’s message in `error`).
`501`	The computer is an iPhone, or a Mac whose agent has no `/exec`: `{"error": "…", "code": "EXEC_UNSUPPORTED_ON_DEVICE"}`. On a Mac, `error` says how to run the code through Execute bash instead.
`503`	The computer could not be reached. The body is `{"error": "Could not reach the desktop. Try again in a moment."}` with a `code` and a diagnostic: `vm_status`, `desired_status`, `host_reachable`, `desktop_api_reachable`, and a `hint`. Safe to retry. Also returned when the computer never finished provisioning: `{"error": "Computer not ready"}`.
`504`	The call outlived the time the API hop allows: `{"error": "The command exceeded the allowed time and was aborted.", "code": "timeout"}`. No output comes back.

Code that raises is not an error status: it is a 200 with success: false. Every failure raised after the request leaves the API layer carries a request_id. Quote it in support requests. When the computer agent itself answered non-2xx, the body additionally carries upstream_status.

{
  "error": "Code is required and must be a string"
}

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

Computer ID

Body

application/json

code

string

required

Python code to execute

timeout

integer

default:10

How long the code may run, in seconds. Always clamped to 1-300: a larger value becomes 300, and 0 or a non-numeric value becomes 10. Out-of-range values are never rejected.

Required range: 1 <= x <= 300

Response

The code ran. Code that raises is still a 200, with success: false and the traceback in output.

success

boolean

true only when the interpreter exited zero. Code that raises returns 200 with success: false.

action

enum<string>

Available options:

exec

output

string

Combined stdout and stderr. An uncaught exception's traceback arrives here.

timeout

enum<boolean>

Always false, even when the code was killed by the timeout. Infer a timeout from success: false with truncated output.

Available options:

false

error

null

Always null on a 200, including when the code raises.

error_type

null

Always null on a 200. It never carries a Python exception class.

Execute Python

curl --request POST \
  --url https://www.orgo.ai/api/computers/{id}/exec \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "import os\nprint(os.getcwd())",
  "timeout": 10
}
'

import requests

url = "https://www.orgo.ai/api/computers/{id}/exec"

payload = {
    "code": "import os
print(os.getcwd())",
    "timeout": 10
}
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({code: 'import os\nprint(os.getcwd())', timeout: 10})
};

fetch('https://www.orgo.ai/api/computers/{id}/exec', 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/computers/{id}/exec",
  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([
    'code' => 'import os
print(os.getcwd())',
    'timeout' => 10
  ]),
  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/computers/{id}/exec"

	payload := strings.NewReader("{\n  \"code\": \"import os\\nprint(os.getcwd())\",\n  \"timeout\": 10\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/computers/{id}/exec")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"code\": \"import os\\nprint(os.getcwd())\",\n  \"timeout\": 10\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/computers/{id}/exec")

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  \"code\": \"import os\\nprint(os.getcwd())\",\n  \"timeout\": 10\n}"

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

{
  "success": true,
  "action": "exec",
  "output": "/home/user\n",
  "timeout": false,
  "error": null,
  "error_type": null
}

Overview

Account

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Execute Python

Path parameters

Body parameters

Response

Example

Successful response

Response when the code raises

Errors

Authorizations

Path Parameters

Body

Response

​Path parameters

​Body parameters

​Response

​Example

​Successful response

​Response when the code raises

​Errors

Authorizations

Path Parameters

Body

Response

Path parameters

Body parameters

Response

Example

Successful response

Response when the code raises

Errors