Computers
Apply secrets to a computer
Write vault secrets onto one running Linux computer and into the env file of each agent there, take them off, or preview what either would change.
POST
Send
{"names":["ANTHROPIC_API_KEY"]} to apply those names from your vault to one running Linux computer. To reach many computers in one call, use Apply secrets to many computers. names takes 1 to 50 environment variable names made of letters, digits, and underscores, not starting with a digit, up to 64 characters each. Duplicates are ignored. Workspace values take precedence over account values. This requires write access to the computer’s workspace. Settings → Secrets calls this endpoint with dry_run: true for each ticked computer it would change, to show what each one would get, and again for each one when you apply.
wake, remove, and dry_run are each true, false, or left out. Any other value returns 400.
Where the values are written
An apply writes these files, all owned by root. Each file Orgo writes is readable by root only (mode0600). /root/.env, /root/.bashrc, and /root/.profile are written only when Orgo changes a line in them, so until then they keep the permissions they had. That is when the line that loads the next file is missing, and for /root/.env also when Orgo takes out a line from when the computer was created for a name it applies or removes.
Then each agent installed on the computer gets the values in its own env file. Orgo looks for the agent’s command in
/usr/local/bin, /usr/bin, /bin, and /root/.local/bin.
Hermes profiles under
/root/.hermes/profiles are not written. Each computer keeps its own chat bots: Hermes’ file never gets ORGO_TELEGRAM_BOT, names starting with TELEGRAM_, DISCORD_, SLACK_, WHATSAPP_, SIGNAL_, MATTERMOST_, MATRIX_, HASS_, EMAIL_, SMS_, TWILIO_, DINGTALK_, FEISHU_, WECOM_, WEIXIN_, BLUEBUBBLES_, QQ_, QQBOT_, YUANBAO_, IRC_, WEBHOOK_, MSGRAPH_, or GATEWAY_, or names ending in _ALLOWED_USERS, _ALLOW_ALL_USERS, or _HOME_CHANNEL. Those still reach /root/.env, which the Hermes gateway loads when it starts; a line in the computer’s own Hermes file wins over it.
In the agent files, every other line and comment stays as it was. A line for an applied name is replaced. A value containing a single quote, a backslash, ${, or a line break of any kind (including a form feed, a vertical tab, U+0085, U+2028, and U+2029) is left out of the agent files and still reaches /root/.env.
Remove secrets from a computer
Withremove: true, Orgo deletes the names from /root/.orgo-secrets.json and /root/.orgo-secrets.env. It removes a line from /root/.env only while that line holds your current vault value, and a line from an agent file only while it still holds the value Orgo wrote there. The /root/.env check never sends the computer your value, or any hash of it the computer did not compute itself: the computer answers an HMAC of its own line under a random key made for this request, Orgo compares it with your value, and only a line that matches is removed, in a second call to the computer that names the line by the computer’s own HMAC. A name no longer in your vault is still removed from Orgo’s files.
Preview what would change
Withdry_run: true, nothing on the computer changes. Orgo asks the computer which agents are installed and which of their files the call would change, and answers with the same report an apply or a removal gives, with would_update and would_clear in place of updated and cleared.
The computer is sent names only, never a value or a hash of one. Orgo works out on its side which values an agent file can’t hold, and sends the computer just those names.
- Apply preview. Every name must be in your vault for the computer’s workspace, or the request returns
404. - Removal preview (
remove: trueas well). Names that are not in your vault are allowed. For the names that are, the computer answers an HMAC of its/root/.envline from when it was created, under a random key made for this request, and Orgo compares it with your value, as a removal does. That takes one call to the computer, and the HMAC is never part of the response. - A computer asleep in storage returns
409withcode: "computer_asleep", even withwake: true. A preview never wakes a computer.
Response
An apply answerssuccess, names, restart_required: true, a message, and report. A removal answers success, names, removed: true, a message, and report. A preview answers success, dry_run: true, names, and report. Every answer carries Cache-Control: no-store. Secret values are never included in a response. Existing processes keep their current environment until they restart.
The report
report is null when no report line came back from the computer. Otherwise it holds ok, targets, and, for a removal or its preview, names and kept_in. It never holds a value.
targets has one entry for each installed agent the call reaches or would reach. Agents that are not installed are left out. Each entry has an id (hermes, openclaw, codex, claude-code, opencode, or agy, or agents for the agent step as a whole) and a status:
A
skipped entry’s reason is owner_managed (a Hermes whose gateway its owner runs on their own setup), unreadable (Orgo can’t read the file), or write_failed (Orgo couldn’t write it; not in a preview). On the agents entry, state_unreadable means /root/.orgo-secrets.agents.json does not parse, so no agent file was touched.
An entry’s skipped list names what was left out of that file, each with a reason:
value_format: the value has a single quote, a backslash,${, or a line break, so it can’t go in the agent’s file. It still reaches/root/.env.reserved(preview only): the agent keeps its own value for this name, such as Hermes’HERMES_HOME, names starting withAPI_SERVER_, and its chat app names; Codex’sCODEX_names; or OpenClaw’sOPENCLAW_names.
restart names the supervisord program to restart for the change to take effect: openclaw-gateway whenever OpenClaw’s file changes, and hermes-gateway when a line leaves Hermes’ file (a removal, or an apply that takes out the old line of a value Hermes’ file can’t hold).
For a removal, names says what happened to each name on the computer: cleared (at least one copy was taken out), kept (a copy stays and none was taken out), or none (there was no copy). A removal preview says would_clear, would_keep, or none. kept_in lists where a copy stays, or would stay: dotenv for a line in /root/.env from when the computer was created that does not hold your current vault value, or an agent id for a line in that agent’s file that was changed on the computer, or a file Orgo could not read or write.
Errors
An invalid body returns400 with { "error": "names must contain 1 to 50 environment variable names (letters, numbers, underscores; no leading number). wake, remove and dry_run are true or false." }. An apply whose values are too large to send to the computer in one call (the computer takes at most 128 KiB per call) returns 413 with code: "too_large"; apply fewer names per call. A name of ORGO_API_KEY returns 422 with code: "reserved_name", because that name holds the computer’s own key. A missing secret returns 404 with { "error": "A requested secret is not available in your vault for this workspace." } (an apply or its preview). A computer that is stopped, or suspended on its host, returns 409 with { "error": "Start the computer before applying secrets." }. A computer asleep in storage returns 409 with code: "computer_asleep" when wake is false or dry_run is true. With wake left at true, it is woken first: while it wakes, the request returns 409 with code: "computer_waking" and a Retry-After header, and a wake that fails returns 503 with code wake_failed, no_capacity, or saved_state_unavailable and a Retry-After header. A computer that does not run Linux returns 422 with code: "not_linux".
A failure to reach the computer returns 502 with { "error": "Could not apply secrets. Check the computer connection and try again." }, which says remove for a removal and check for a preview. When /root/.orgo-secrets.json on the computer cannot be parsed, nothing is changed and the request returns 502 with code: "secrets_state_unreadable", a preview included. A missing or invalid API key returns 401. An unknown computer returns 404: { "error": "Computer not found (computer_not_found).", "code": "computer_not_found" } with an API key, and { "error": "Desktop not found" } signed in. No access to the computer’s workspace, or an API key scoped to another workspace, returns 403. Can chat access returns 403 with code: "workspace_read_only". A trial computer whose trial has ended returns 402 with { "error": "Choose a plan to continue." }. Over the workspace owner’s plan rate limit for other API calls, the request returns 429 with code rate_limited, limit: "api_other_per_minute" and a Retry-After header with the seconds to wait, and nothing is written. See Plan rate limits. If Orgo cannot verify the credential because of a server-side fault, such as a database outage, the request returns 503 with { "error": "Service temporarily unavailable. …" } and Retry-After: 5. Retry after that delay; do not rotate the key.
Saving or deleting a vault entry does not change computers already running. Deleting a vault entry does not erase a copy already applied to a computer: remove it with remove: true first.Authorizations
API key authentication. Get your key at orgo.ai/workspaces
Path Parameters
Computer UUID or instance ID.
Body
application/json
The vault names to apply, remove, or preview. Duplicates are ignored.
Required array length:
1 - 50 elementsAn 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}$false answers 409 with code: "computer_asleep" for a computer asleep in storage instead of waking it.
true takes the names off the computer instead of writing them. A create-time line in /root/.env goes only while it holds your vault value, checked without sending the computer the value or any hash of it other than the one it computed itself, and an agent file line only while it holds the value Orgo wrote.
true changes nothing and answers what an apply, or with remove: true a removal, would do. The computer is sent names only, never a value or a hash of one. Never wakes a computer: one asleep in storage answers 409 with code: "computer_asleep", whatever wake says.
Response
Applied, removed with remove: true, or previewed with dry_run: true. Values are never returned. Open a new terminal or restart the agent to read the new environment; report names any program to restart. The answer carries Cache-Control: no-store.
Present and true when dry_run was true.
Present on an apply.
Present and true when remove was true and dry_run was not.
Present on an apply or a removal.
What happened, or would happen, to each agent's env file on the computer. Names, ids and statuses only, never a value. null when no report line came back from the computer.