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]| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
--agent AGENT_ID | no | one 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| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
NAME | yes | the environment variable the agent's tools read, such as WEATHER_API_KEY | ||
--agent AGENT_ID | yes | the agent's ID, from oo agents list | ||
--file PATH | no | read the value from PATH (- for standard input) | ||
--from-1password REFERENCE | no | a key from your own 1Password, by its secret reference: op://vault/item/field | ||
--kind KIND | no | key | key, file | key: text the environment variable holds (the default); file: a file the variable names |
--for-me | no | your own secret, which the agent uses only in your own conversations with it |
It also takes the connection options.
oo secrets link
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| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
NAME | yes | the secret's name, the environment variable the agent's tools read | ||
--agent AGENT_ID | yes | the agent's ID, from oo agents list | ||
--kind KIND | no | key | key, file | file for a credentials file |
--for-me | no | your own secret, used only in your own conversations with the agent | ||
--why TEXT | no | one 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| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
NAME | yes | the secret's name for the agent, or with --provider the provider key's name here | ||
--agent AGENT_ID | no | the agent that gets it, from oo agents list | ||
--provider PROVIDER | no | a model provider, as oo models providers names it | ||
--kind KIND | no | key, file | for an agent: file for a credentials file | |
--why TEXT | yes | what it is for, in a few words | ||
--person PERSON | no | their sign-in email or person ID; your owner, or yourself, when left out | ||
--expires-in MINUTES | no | how 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]| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
--link | no | ask for it with a link to Settings > Approvals instead of a token | ||
--why TEXT | no | with --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 statusIt 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]| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
--vault VAULT_ID | no | a vault's id, from browse: its items | ||
--item ITEM_ID | no | an item's id, from browse --vault: its fields (needs --vault) |
It also takes the connection options.
oo secrets 1password unlink
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| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
AGENT_ID | yes | the 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]| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
--yes | no | confirm 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| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
NAME | yes | the secret's name | ||
--agent AGENT_ID | yes | the agent's ID, from oo agents list | ||
--for-me | no | your own secret, not the whole agent's | ||
--yes | no | confirm it now; an agent passes it only once the person confirmed it in chat |
It also takes the connection options.