Orgo - Cloud computers for AI agents

POST

secrets

apply

curl --request POST \
  --url https://www.orgo.ai/api/secrets/apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "names": [
    "ANTHROPIC_API_KEY"
  ]
}
'

{
  "dry_run": false,
  "names": [
    "ANTHROPIC_API_KEY"
  ],
  "results": [
    {
      "computer_id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "name": "agent-1",
      "workspace_id": "6f1c2e7a-4b9d-4e2f-9a51-0c3d8e7b2f10",
      "outcome": "applied",
      "report": {
        "ok": true,
        "targets": [
          {
            "id": "hermes",
            "status": "updated",
            "names": [
              "ANTHROPIC_API_KEY"
            ]
          },
          {
            "id": "claude-code",
            "status": "shell"
          }
        ]
      }
    },
    {
      "computer_id": "c41f7a2e-1d3b-4c8e-b6a9-5e2d0f9c7b31",
      "name": "agent-2",
      "workspace_id": "6f1c2e7a-4b9d-4e2f-9a51-0c3d8e7b2f10",
      "outcome": "not_changed",
      "reason": "Asleep. Not changed."
    }
  ],
  "remaining": [],
  "next": []
}

Applies vault secrets to many running Linux computers in one call. With remove: true it takes them off instead, and with dry_run: true it changes nothing and says what each computer would get. Each computer gets what Apply secrets to a computer gives it: the same files, the same agent env files, and the same report. Values are never returned.

This call never wakes a computer. A computer that is asleep, in storage or on its host, is listed as not_changed. Start or wake it, then send its id again.

Body parameters

string[]

required

1 to 50 environment variable names from your vault: letters, digits, and underscores, not starting with a digit, up to 64 characters each. Duplicates are ignored. ORGO_API_KEY returns 422.

string[] | null

1 to 100 computers, each a computer UUID or instance_id. Orgo sends to exactly these computers. Duplicates are ignored. null is the same as leaving it out.

string | null

A workspace UUID, in lowercase as Orgo returns it. Without computer_ids, every computer in this workspace is in scope. With computer_ids, it does not choose computers, but it must still be a workspace you can change. Any other string, an id in capitals included, returns 403. null is the same as leaving it out.

boolean

default:"false"

true takes the names off the computers instead of writing them, as described in Remove secrets from a computer.

boolean

default:"false"

true changes nothing. Each computer answers what an apply, or with remove: true a removal, would change there, as described in Preview what would change.

remove and dry_run are each true, false, or left out. Any other value returns 400. Fields this endpoint does not take, such as wake, are ignored.

Which computers

You send	Computers in scope
`computer_ids`	Exactly those. A computer you can’t reach or can’t change is a `failed` or `not_changed` result, not a refusal of the whole call.
`workspace_id`	Every computer in that workspace. Running Linux computers get every name. The rest are `not_changed`, with why.
Neither	The computers where each name is saved, described below.

With neither, each name goes where it is saved:

An account secret goes to every workspace you own.
A secret saved only for a workspace goes to that workspace, whoever owns it.
A workspace someone else owns does not get account secrets, because its other members, and the agents they talk to, could read what you send. Name it in workspace_id, or its computers in computer_ids, to include it. Unless every name you send that has an account value also has its own value saved for that workspace, none of those names go there, not even the workspace’s own values. Names saved only for that workspace still go there. When nothing goes there, its running computers are listed as not_changed, with how to include them.
With remove: true, an account secret is taken off every workspace you own, except where a workspace has its own secret with that name. Its computers got the workspace’s value, so the name stays there. When that leaves nothing to remove in a workspace, its computers are listed as not_changed.
A removal leaves out a workspace someone else owns in the same way, because it takes the name off whatever its value, so it would also take another member’s value of that name. Name the workspace or its computers to include it. A secret saved only for that workspace is still taken off there.
A workspace you can only view is never changed. When a secret saved only for that workspace names it, its computers are listed as not_changed, saying you can only view it. Otherwise it is not listed.
Client workspaces you created under Invoicing are left out. Name them in workspace_id or computer_ids.
A name that is in none of your vaults returns 404 with code: "secret_not_found".

Where a workspace has its own value for a name and Orgo sends that name there, its computers get that value rather than the account’s.

How the call runs

Orgo works on four computers at a time, and never wakes one. A computer whose secrets are too large to send in one call is sent them in halves. No computer starts after 45 seconds, and a computer sent its secrets in halves starts no next half after that. Computers already under way finish, so the answer can take longer than 45 seconds. Orgo starts no step on a computer that could still be running 90 seconds into the call. A removal leaves out its second step on /root/.env when time is short, and that computer’s report says the line stays. The computers that did not start are in remaining, and next holds the calls that finish the job.

Response

boolean

Whether this was a preview.

string[]

The names sent, without duplicates.

object[]

One entry per computer, in the order of the computers in scope, followed by the computers found not_changed while choosing them.

Show properties

string

The computer’s UUID when Orgo could read the computer, else the id as you sent it.

string | null

The computer’s name. null when it is not known, such as for a computer that was not found.

string | null

The computer’s workspace. null when it is not known.

string

applied, removed, previewed, not_changed, or failed.

string

On not_changed and failed: why, as a sentence you can show people.

object | null

On applied, removed, and previewed: what the computer reported, described in The report. null when no report came back.

string[]

The computers that did not start before the time ran out: the ids as you sent them in computer_ids, or computer UUIDs otherwise. Empty when every computer ran.

object[]

The calls that finish the job: the computers in remaining, each call with the names those computers were due. Send each one to this endpoint as it is. Empty when remaining is.

Show properties

string[]

The names these computers were due. With neither computer_ids nor workspace_id, a workspace can be due fewer names than you sent.

string[]

Up to 100 of the computers in remaining.

boolean

true when this call was a removal. Left out otherwise.

boolean

true when this call was a preview. Left out otherwise.

The answer carries Cache-Control: no-store.

Outcomes

`outcome`	Meaning
`applied`	The names were written. `report` says what each agent got.
`removed`	The removal ran. `report.names` says, for each name, whether a copy was taken out or stays.
`previewed`	`dry_run: true`. Nothing changed, and `report` says what would.
`not_changed`	The computer was not sent to, or answered that it can’t be changed now. `reason` says why.
`failed`	The computer could not be changed. `reason` says why.

Common reasons:

`outcome`	`reason`	When
`failed`	`Computer not found.`	No such computer, or one you are not a member of. The two read the same, so the answer does not tell which ids exist.
`failed`	`You can view this workspace but not change its computers.`	You can only view the computer’s workspace, and you named it in `computer_ids`.
`failed`	`A requested secret is not available in your vault for this workspace.`	A name is not in your vault for the computer’s workspace. Apply and its preview only.
`failed`	`Could not apply secrets. Check the computer connection and try again.`	The computer did not answer. It says `remove` for a removal and `check` for a preview.
`failed`	`This computer’s secrets file could not be read, so nothing was changed.`	`/root/.orgo-secrets.json` on the computer does not parse.
`failed`	`These secrets are too large to apply in one request. Apply fewer at a time.`	One name’s value alone is too large to send to the computer.
`failed`	`Couldn’t check this computer. Try again.`	Orgo could not look the computer up.
`failed`	Why Orgo refused the computer, such as `Choose a plan to continue.`	The computer’s trial or payment has lapsed, or Orgo locked it.
`not_changed`	`Asleep. Not changed.`	The computer is suspended, in storage or on its host, or went to sleep while Orgo reached it. Start or wake it, then send its id again.
`not_changed`	`Stopped. Not changed.`, `Not reachable. Not changed.`, or `Not running. Not changed.`	The computer was not running when Orgo chose the computers.
`not_changed`	`Start the computer before applying secrets.`	A computer you named in `computer_ids` is not running, or is suspended on its host.
`not_changed`	`Windows computers can’t get secrets yet.` (or Mac, Android, iPhone, or `This kind of computers can’t get secrets yet.` for any other system)	Only Linux computers get secrets.
`not_changed`	`Applying secrets currently requires a Linux computer.`	A computer you named in `computer_ids` is not a Linux computer.
`not_changed`	`Someone else owns this workspace. Name it in workspace_id or computer_ids to include it.`	The default scope left out a workspace someone else owns.
`not_changed`	`This workspace has its own value. Not changed.`	A removal with the default scope left out a workspace with its own secret of that name.
`not_changed`	`You can view this workspace but not change its computers.`	The default scope found a secret saved for a workspace you can only view.

Continue with remaining

When remaining is not empty, send each body in next to this endpoint as it is, and do the same with each answer until next is empty. Running the same apply on a computer twice is safe: the values are merged, not added twice. Each body in next names the computers in computer_ids, up to 100 a call, which is the most computer_ids takes. Its names are what those computers were due. With the default scope that can be fewer than you sent: a workspace with its own value for a name keeps it on a removal, and a secret saved for one workspace goes to that workspace only. Sending every name to those computers instead fails where a name is not in your vault for the computer’s workspace, and a removal would take off a name the workspace keeps its own value for.

Errors

Status	`code`	When
`400`	none	The body is not valid: `names must contain 1 to 50 environment variable names (letters, numbers, underscores; no leading number). computer_ids holds 1 to 100 computer ids, workspace_id is a workspace id, and remove and dry_run are true or false.` A `workspace_id` that is not a string returns this too.
`401`	none	No usable credential.
`401`, `403`	`key_expired`, `key_permission`, `computer_key`, `computer_scope`, and others	The key itself was refused before the call ran. A restricted key needs Secrets write. A computer’s own key and a key for one computer can’t call this endpoint. Listed in Codes any endpoint can return to a key.
`403`	`workspace_scope_mismatch`	A key scoped to one workspace: `This endpoint requires an account-wide credential (workspace_scope_mismatch).` Use a key for your whole account.
`403`	none	`workspace_id` is not the id of a workspace you are a member of, such as a string that is not a UUID or a UUID in capitals: `You do not have access to this workspace.`
`403`	`workspace_read_only`	`workspace_id` names a workspace you can only view: `This workspace is view-only. Ask the owner for write access (workspace_read_only).`
`404`	`secret_not_found`	With neither `computer_ids` nor `workspace_id`, a name is in none of your vaults: `NAME is not in your vault.` For a removal: `NAME is not in your vault, so Orgo can’t tell which computers have it. Name them in computer_ids, or a workspace in workspace_id.`
`422`	`reserved_name`	A name is `ORGO_API_KEY`: `ORGO_API_KEY is each computer’s own key. Orgo sets it, so it can’t be applied or removed here.`
`500`	none	An unexpected failure, such as a database error while Orgo chooses the computers: `Could not apply secrets. Try again.`, `Could not remove secrets. Try again.`, or for a preview `Could not check your computers. Try again.`
`503`	none	Orgo could not verify the credential because of a server-side fault: `Service temporarily unavailable. …`, with `Retry-After: 5`. Retry after that delay; do not rotate the key.

A refusal for one computer never fails the call. It is that computer’s failed or not_changed result.

Example

The cURL call previews what applying ANTHROPIC_API_KEY would change on every computer in a workspace. The Python one applies it, then sends each body in next until every computer has run. Set $WORKSPACE_ID to the workspace’s id.

curl -X POST https://www.orgo.ai/api/secrets/apply \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"names": ["ANTHROPIC_API_KEY"], "workspace_id": "'"$WORKSPACE_ID"'", "dry_run": true}'

import os
import requests

url = "https://www.orgo.ai/api/secrets/apply"
headers = {"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"}

# Apply to every computer in the workspace, then to any the time ran out for.
calls = [{"names": ["ANTHROPIC_API_KEY"], "workspace_id": os.environ["WORKSPACE_ID"]}]
while calls:
    response = requests.post(url, headers=headers, json=calls.pop(0))
    response.raise_for_status()
    answer = response.json()
    for result in answer["results"]:
        print(result["name"], result["outcome"], result.get("reason", ""))
    calls.extend(answer["next"])

Response

{
  "dry_run": true,
  "names": ["ANTHROPIC_API_KEY"],
  "results": [
    {
      "computer_id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "name": "agent-1",
      "workspace_id": "6f1c2e7a-4b9d-4e2f-9a51-0c3d8e7b2f10",
      "outcome": "previewed",
      "report": {
        "ok": true,
        "targets": [
          { "id": "hermes", "status": "would_update", "names": ["ANTHROPIC_API_KEY"] },
          { "id": "openclaw", "status": "would_update", "names": ["ANTHROPIC_API_KEY"], "restart": "openclaw-gateway" },
          { "id": "claude-code", "status": "shell" }
        ]
      }
    },
    {
      "computer_id": "c41f7a2e-1d3b-4c8e-b6a9-5e2d0f9c7b31",
      "name": "agent-2",
      "workspace_id": "6f1c2e7a-4b9d-4e2f-9a51-0c3d8e7b2f10",
      "outcome": "not_changed",
      "reason": "Asleep. Not changed."
    }
  ],
  "remaining": [],
  "next": []
}

Authorizations

Authorization

string

header

required

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

Body

application/json

names

string[]

required

The vault names to apply, remove, or preview. Duplicates are ignored. ORGO_API_KEY answers 422.

Required array length: 1 - 50 elements

An environment variable name: letters, digits, and underscores, not starting with a digit, up to 64 characters.

Pattern: ^[A-Za-z_][A-Za-z0-9_]{0,63}$

computer_ids

string[] | null

Exactly these computers. Duplicates are ignored. null is the same as leaving it out.

Required array length: 1 - 100 elements

A computer UUID or instance_id.

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$

workspace_id

string<uuid> | null

Without computer_ids: every computer in this workspace. With computer_ids it does not choose computers, but it must still be a workspace you can change. A string that is not the id of a workspace you are a member of, a UUID in capitals included, answers 403. null is the same as leaving it out.

remove

boolean

default:false

true takes the names off the computers instead of writing them.

dry_run

boolean

default:false

true changes nothing. Each computer answers what an apply, or with remove: true a removal, would change there.

Response

Each computer's outcome. The answer carries Cache-Control: no-store.

dry_run

boolean

required

names

string[]

required

The names sent, without duplicates.

results

object[]

required

One entry per computer, in the order of the computers in scope, followed by the computers found not_changed while choosing them.

Show child attributes

remaining

string[]

required

The computers that did not start before the time ran out: the ids as sent in computer_ids, or computer UUIDs otherwise. next holds the calls that finish them.

object[]

required

The calls that finish the job: the computers in remaining, grouped by the names each was due, up to 100 a call. Send each one to this endpoint as it is. With neither computer_ids nor workspace_id, a workspace can be due fewer names than were sent. Empty when remaining is.

Show child attributes

curl --request POST \
  --url https://www.orgo.ai/api/secrets/apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "names": [
    "ANTHROPIC_API_KEY"
  ]
}
'

{
  "dry_run": false,
  "names": [
    "ANTHROPIC_API_KEY"
  ],
  "results": [
    {
      "computer_id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "name": "agent-1",
      "workspace_id": "6f1c2e7a-4b9d-4e2f-9a51-0c3d8e7b2f10",
      "outcome": "applied",
      "report": {
        "ok": true,
        "targets": [
          {
            "id": "hermes",
            "status": "updated",
            "names": [
              "ANTHROPIC_API_KEY"
            ]
          },
          {
            "id": "claude-code",
            "status": "shell"
          }
        ]
      }
    },
    {
      "computer_id": "c41f7a2e-1d3b-4c8e-b6a9-5e2d0f9c7b31",
      "name": "agent-2",
      "workspace_id": "6f1c2e7a-4b9d-4e2f-9a51-0c3d8e7b2f10",
      "outcome": "not_changed",
      "reason": "Asleep. Not changed."
    }
  ],
  "remaining": [],
  "next": []
}

Overview

API keys

Support

Account

Agent accounts

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Apply secrets to many computers

Body parameters

Which computers

How the call runs

Response

Outcomes

Continue with remaining

Errors

Example

Response

Authorizations

Body

Response

​Body parameters

​Which computers

​How the call runs

​Response

​Outcomes

​Continue with remaining

​Errors

​Example

​Response

Authorizations

Body

Response

Body parameters

Which computers

How the call runs

Response

Outcomes

Continue with remaining

Errors

Example

Response