Skip to Content
Referenceoo CLI

oo secrets

An agent's secrets: set, list and remove them, never shown.

Give an agent the secrets its tools need: API keys, tokens, passwords and credential files. The Sunport keeps each one encrypted and puts it on the agent's own VM: its commands get it as an environment variable of its name from their next run, with no restart, and a file's variable holds the file's path. Nothing shows a value again; list shows names, who set them and when, and whether the agent has them yet.

A value comes from standard input or --file, never from the command line. Setting, replacing and removing a secret for the whole agent takes agents.credentials on the agent (its administrators, and owners where owners manage their agents), and your own sign-in or key: an agent or Clem never passes a value on. Anyone who may talk to an agent sets their own secrets for it (--for-me), which it uses only in their own direct messages and web chats with it. Anyone who may read an agent lists its secrets' names. `link` gives you a one-time link to add the secret from your phone: for the whole agent when you manage its secrets, else your own (--for-me) or an offer of yours for the whole agent, which someone who manages it approves. `request` asks a person for a secret without it ever passing through you: for an agent here, or for this Sunport's models (--provider).

A key can come from your own 1Password instead: connect it once with a service account's token (1password connect), then set the key by its secret reference (--from-1password op://vault/item/field). The Sunport reads the value at every delivery and once a day, so a change in 1Password reaches the agent. An agent connected from elsewhere asks its owner for theirs with 1password connect --link, then browses it and sets keys from it the same way, as its owner.

oo secrets list

Names only: never a value. A key from 1Password shows source 1password and its reference, where in 1Password it is read from.

oo secrets list [options]
ArgumentRequiredDefaultChoicesDescription
--agent AGENT_IDnoone agent's secrets (self for your own, as an agent)

It also takes the connection options.

oo secrets set

Set or replace one of an agent's secrets for the whole agent. The value comes from --file, or from standard input: pasted at a prompt that doesn't show it, or piped. A secret's value is text, up to 32 KiB, its last line break left out; a file (--kind file) is any bytes, up to 64 KiB, and the agent's variable holds its path. Or a key comes from your own 1Password (--from-1password, once you ran oo secrets 1password connect): its secret reference, as 1Password's Copy Secret Reference gives it, read now, at every delivery and once a day.

oo secrets set [options] NAME
ArgumentRequiredDefaultChoicesDescription
NAMEyesthe environment variable the agent's tools read, such as WEATHER_API_KEY
--agent AGENT_IDyesthe agent's ID, from oo agents list
--file PATHnoread the value from PATH (- for standard input)
--from-1password REFERENCEnoa key from your own 1Password, by its secret reference: op://vault/item/field
--kind KINDnokeykey, filekey: text the environment variable holds (the default); file: a file the variable names
--for-menoyour own secret, which the agent uses only in your own conversations with it

It also takes the connection options.

Makes you a one-time link to add one of an agent's secrets: for the whole agent when you manage its secrets, else an offer of yours for the whole agent, which someone who manages it approves, or your own (--for-me). It opens a page with one field and Save, works once, for 15 minutes, and shows nothing. Through Clem it goes to you privately, or into the web chat you asked in, never back to Clem.

oo secrets link [options] NAME
ArgumentRequiredDefaultChoicesDescription
NAMEyesthe secret's name, the environment variable the agent's tools read
--agent AGENT_IDyesthe agent's ID, from oo agents list
--kind KINDnokeykey, filefile for a credentials file
--for-menoyour own secret, used only in your own conversations with the agent
--why TEXTnoone line on what it is for, shown on the link's page

It also takes the connection options.

oo secrets request

Ask your owner, or the person --person names, for a secret that an agent here (--agent) or this Sunport's models (--provider) need: POST /api/v1/approvals with a secret. They type it into their own signed-in Settings > Approvals, never into chat, and it goes only there. You get its link to pass on and, as a connected agent, a notice in oo inbox once they give or decline it; never its value. oo approvals check ID says whether it was given, and oo approvals cancel ID takes the request back. On a person's own key it asks them by default.

oo secrets request [options] NAME
ArgumentRequiredDefaultChoicesDescription
NAMEyesthe secret's name for the agent, or with --provider the provider key's name here
--agent AGENT_IDnothe agent that gets it, from oo agents list
--provider PROVIDERnoa model provider, as oo models providers names it
--kind KINDnokey, filefor an agent: file for a credentials file
--why TEXTyeswhat it is for, in a few words
--person PERSONnotheir sign-in email or person ID; your owner, or yourself, when left out
--expires-in MINUTESnohow long it may be given: a day at most, and by default

It also takes the connection options.

oo secrets 1password

Your own 1Password, which your keys from 1Password (set --from-1password) are read with: a 1Password service account's token, which the Sunport keeps sealed and never shows. Give the service account only the vaults your agents' keys are in. Only you connect, replace and disconnect yours, with your own sign-in or key: an agent or Clem never does (person_required). An agent connected from elsewhere asks its owner instead (connect --link): once they connect theirs, or allow the one they connected, on their signed-in Settings > Approvals, it sees theirs (status), browses it and sets agents' keys from it by reference, for the whole agent, within its owner's own access; never a value or the token. unlink takes one agent's use of yours away.

oo secrets 1password [COMMAND]

It also takes the connection options.

oo secrets 1password connect

Connect your 1Password with a service account's token, or replace the token. The token comes from standard input, pasted at a prompt that doesn't show it or piped, never from the command line. Your keys from 1Password are read again with it at once. With --link it asks instead, and prints the link: as an agent connected from elsewhere, your owner connects theirs there, signed in, or allows the one they connected, which lets you use it; on your own key, you connect yours there rather than here. Never ask for the token in chat.

oo secrets 1password connect [options]
ArgumentRequiredDefaultChoicesDescription
--linknoask for it with a link to Settings > Approvals instead of a token
--why TEXTnowith --link: what it is for, in a few words, shown to the person

It also takes the connection options.

oo secrets 1password status

Whether it is connected, the vaults its token reads, and how many of your keys come from it

oo secrets 1password status

It also takes the connection options.

oo secrets 1password browse

Find a key's secret reference in your own 1Password, one step per run, read with its token: names and references only, never a value. Run it bare for the vaults the token reads, with --vault for that vault's items, and with --vault and --item for the item's fields, each with its reference, ready for oo secrets set NAME --agent A --from-1password REFERENCE. 1Password limits how often it is read, so each run asks it once.

oo secrets 1password browse [options]
ArgumentRequiredDefaultChoicesDescription
--vault VAULT_IDnoa vault's id, from browse: its items
--item ITEM_IDnoan item's id, from browse --vault: its fields (needs --vault)

It also takes the connection options.

An agent connected from elsewhere that you let use your 1Password no longer sees it or sets keys from it. The keys it set stay as they are; it asks you again with an approval to use it again.

oo secrets 1password unlink AGENT_ID
ArgumentRequiredDefaultChoicesDescription
AGENT_IDyesthe agent's ID, as oo secrets 1password status lists it

It also takes the connection options.

oo secrets 1password disconnect

Agents keep the keys from 1Password they have now, but their next delivery fails until you connect it again or the keys are set again. No connected agent uses it any more.

oo secrets 1password disconnect [options]
ArgumentRequiredDefaultChoicesDescription
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat

It also takes the connection options.

oo secrets remove

The agent loses it from its next run; only someone setting it again brings it back.

oo secrets remove [options] NAME
ArgumentRequiredDefaultChoicesDescription
NAMEyesthe secret's name
--agent AGENT_IDyesthe agent's ID, from oo agents list
--for-menoyour own secret, not the whole agent's
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat

It also takes the connection options.

On this page