Orgo - Cloud computers for AI agents

POST

computers

{id}

bash

Execute bash

curl --request POST \
  --url https://www.orgo.ai/api/computers/{id}/bash \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "ls -la /home/user"
}
'

import requests

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

payload = { "command": "ls -la /home/user" }
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({command: 'ls -la /home/user'})
};

fetch('https://www.orgo.ai/api/computers/{id}/bash', 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}/bash",
  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([
    'command' => 'ls -la /home/user'
  ]),
  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}/bash"

	payload := strings.NewReader("{\n  \"command\": \"ls -la /home/user\"\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}/bash")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"command\": \"ls -la /home/user\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"command\": \"ls -la /home/user\"\n}"

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

{
  "success": true,
  "action": "bash",
  "command": "ls -la /home/user",
  "output": "total 32\ndrwxr-xr-x 4 user user 4096 Jan 15 10:30 .\ndrwxr-xr-x 3 root root 4096 Jan 15 10:00 ..\n-rw-r--r-- 1 user user  220 Jan 15 10:00 .bashrc\ndrwxr-xr-x 2 user user 4096 Jan 15 10:30 Desktop\n",
  "exit_code": 0,
  "error": null,
  "error_type": null
}

On Linux, runs Bash and returns combined stdout and stderr. Linux commands run with HOME=/root, DISPLAY=:99, and PATH=/usr/local/bin:/usr/bin:/bin. :99 is the boot screen. To run on another screen, pass ?screen=, described in Query parameters. On Windows, this endpoint runs PowerShell, despite its name. Use PowerShell syntax. The command runs from the user’s Desktop folder and honors timeout the same way. The response carries stdout, stderr, exit_code, and output (stdout followed directly by stderr) instead of the fields listed under Response, plus error when the command could not run. A command that runs out of time returns 200 with exit_code: 124, error: "timeout", and the output captured so far.

Path parameters

string

required

Computer ID (UUID).

Query parameters

string

Which screen to run the command on. Optional. Omit it, or send default, to run on the screen the computer booted with. For any other screen, the command runs with DISPLAY set to that screen’s display, so a window it opens appears on that screen. An unknown id returns 404 and nothing runs. Only a Linux computer has more than one screen: on any other computer, every id except default returns 404.

For a screen other than default, Orgo first checks that the screen exists, then prefixes your command with export DISPLAY=:N; for that screen’s display: :100 for screen-100. The rest of the command runs exactly as you sent it, and the command echoed in the response is yours, without the prefix. The body is checked before the screen, so an invalid command returns 400 even when the screen does not exist.

Body parameters

string

required

A non-empty command string. Bash on Linux; PowerShell on Windows.

integer

default:"200"

How long the command may run, in seconds. Optional, and clamped to 1-300 when you send it: a larger value silently becomes 300, and 0 or a non-numeric value becomes 10. Omitting it entirely allows the command 200 seconds.

Omitting timeout allows 200 seconds. The API proxy waits 30 seconds longer than the command timeout. Send an explicit timeout up to 300 seconds for a longer command. This is synchronous execution; it does not return a background job ID.

Response

boolean

true whenever the command ran at all, regardless of what it exited with. Read exit_code to find out whether the command itself succeeded.

string

Always bash.

string

Echo of the command you sent. With ?screen=, the DISPLAY prefix Orgo adds is left out.

string

Combined stdout and stderr, in that order, joined by a newline when both are non-empty.

integer

The command’s exit status, or -1 when it was killed by a signal. A command killed by timeout returns -1. There is no separate timeout flag: a -1 with truncated output is the only signal that the time ran out.

string | null

Always null on a 200. A command that fails is reported through exit_code and output, not here.

string | null

Always null on a 200.

Example

curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/bash \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la /home/user"}'

# Run on a second screen, where $DISPLAY is :100
curl -X POST "https://www.orgo.ai/api/computers/$COMPUTER_ID/bash?screen=screen-100" \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "echo $DISPLAY"}'

import requests

response = requests.post(
    f"https://www.orgo.ai/api/computers/{computer_id}/bash",
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={"command": "ls -la /home/user"}
)

result = response.json()
print(result["output"])
print(f"Exit code: {result['exit_code']}")

const response = await fetch(`https://www.orgo.ai/api/computers/${computerId}/bash`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ command: 'ls -la /home/user' })
});

const { output, exit_code } = await response.json();
console.log(output);
console.log(`Exit code: ${exit_code}`);

Response

{
  "success": true,
  "action": "bash",
  "command": "ls -la /home/user",
  "output": "total 32\ndrwxr-xr-x 4 user user 4096 Jan 15 10:30 .\ndrwxr-xr-x 3 root root 4096 Jan 15 10:00 ..\n-rw-r--r-- 1 user user  220 Jan 15 10:00 .bashrc\ndrwxr-xr-x 2 user user 4096 Jan 15 10:30 Desktop\n",
  "exit_code": 0,
  "error": null,
  "error_type": null
}

For Python code execution, use Execute Python instead.

Errors

Status	Meaning
`400`	The computer has no VM attached: `{"error": "Desktop instance not available"}`. A body that is not JSON returns `{"error": "Expected a JSON object"}`. A missing, empty, or non-string `command` returns `{"error": "command must be a non-empty string"}`.
`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. Also returned when `?screen=` names a screen this computer does not have, and then nothing runs: `{"error": "no screen \"screen-101\"", "request_id": "…", "upstream_status": 404}`.
`500`	The command could not be started at all, with the computer’s own message in `error` and `upstream_status: 500`.
`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 command outlived the time the API hop allows: `{"error": "The command exceeded the allowed time and was aborted.", "code": "timeout"}`. No output comes back.

A command that merely exits non-zero is not an error status: it is a 200 with a non-zero exit_code. 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": "The command exceeded the allowed time and was aborted.",
  "request_id": "9f2b7c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "code": "timeout"
}

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

Computer ID

Query Parameters

screen

string

Which screen to run the command on. Omit it, or send default, for the boot screen. For any other screen the command runs with DISPLAY set to that screen's display. An unknown id returns 404 and nothing runs. Only Linux computers have more than one screen; on any other computer every id but default returns 404.

Body

application/json

command

string

required

Bash command to execute

timeout

integer

default:200

How long the command may run, in seconds, on Linux and Windows alike. Omitted, 200. When sent it is clamped to 1-300: a larger value becomes 300, and 0 or a non-numeric value becomes 10. A Windows command that runs out of time returns 200 with exit_code 124 and error "timeout".

Required range: 1 <= x <= 300

Response

The command ran. A non-zero exit is still a 200; read exit_code. On Windows the body carries stdout, stderr, exit_code, and output instead, and a command that ran out of time is also a 200.

success

boolean

true whenever the command ran at all, regardless of its exit status. Read exit_code.

action

enum<string>

Available options:

bash

command

string

Echo of the command you sent. With ?screen=, the DISPLAY prefix Orgo adds is left out.

output

string

Combined stdout and stderr, joined by a newline when both are non-empty.

exit_code

integer

The command's exit status, or -1 when it was killed by a signal, including by the timeout.

error

null

Always null on a 200.

error_type

null

Always null on a 200.

Execute bash

curl --request POST \
  --url https://www.orgo.ai/api/computers/{id}/bash \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "ls -la /home/user"
}
'

import requests

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

payload = { "command": "ls -la /home/user" }
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({command: 'ls -la /home/user'})
};

fetch('https://www.orgo.ai/api/computers/{id}/bash', 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}/bash",
  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([
    'command' => 'ls -la /home/user'
  ]),
  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}/bash"

	payload := strings.NewReader("{\n  \"command\": \"ls -la /home/user\"\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}/bash")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"command\": \"ls -la /home/user\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"command\": \"ls -la /home/user\"\n}"

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

{
  "success": true,
  "action": "bash",
  "command": "ls -la /home/user",
  "output": "total 32\ndrwxr-xr-x 4 user user 4096 Jan 15 10:30 .\ndrwxr-xr-x 3 root root 4096 Jan 15 10:00 ..\n-rw-r--r-- 1 user user  220 Jan 15 10:00 .bashrc\ndrwxr-xr-x 2 user user 4096 Jan 15 10:30 Desktop\n",
  "exit_code": 0,
  "error": null,
  "error_type": null
}

Overview

Account

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Execute bash

Path parameters

Query parameters

Body parameters

Response

Example

Response

Errors

Authorizations

Path Parameters

Query Parameters

Body

Response

​Path parameters

​Query parameters

​Body parameters

​Response

​Example

​Response

​Errors

Authorizations

Path Parameters

Query Parameters

Body

Response

Path parameters

Query parameters

Body parameters

Response

Example

Response

Errors