Secrets

A secret is a named value your agents need for a tool: a token, a key, a password. The Workspace calls them secrets and keys interchangeably. A secret has a name, a value, a line saying what it is for, and a list of the agents it reaches.

The Workspace holds it rather than an agent’s own computer because that computer is not durable. It sleeps when idle, it can be rebuilt, and a machine software update resets everything outside the agent’s home folder. A key the Workspace holds comes back on its own after any of that.

Secrets belong to a room. Repositories, sites, knowledge pages and Drive are shared by the whole workplace, but a key stays in the room it was saved in, so an agent in another room never receives it.

Open the room on Home and choose its Secrets tab. An admin presses Add a secret. A member saves a key private to one of their own agents from the full Secrets screen, with Add a secret for one of your agents. The form asks for two things:

• Name: letters, digits and underscores, not starting with a digit. This is the name the agent’s tools read, so use the name the tool expects, such as GH_TOKEN.
• Value: paste it whole. A key with several lines, such as an SSH key or a certificate, survives the paste box intact.

An admin adding a key for the room also chooses Whose agents get it: Admins’ agents only, which is the default, or Every agent in this room. A member with more than one agent in the room picks Which of your agents receives it, and that key is private to that one agent.

Save with Save for this room or Save for the agent you chose. Saving a name that already exists replaces the value; it does not add a second key, and it keeps who the key reaches.

This form is the only way a key enters the Workspace. There is no chat command for it, and an agent will never ask you to paste a key into a conversation. Anything typed in a chat is in the chat history; a key saved here is not.

Only a workplace admin can add a key for the room, copy its value, replace it, or delete it. Members see each shared key’s name, what it is for, a masked preview, its value type and length, and when it last changed. They never see the value.

A shared key also says whose agents receive it. By default that is admins’ agents only: members see the key in the list, but their agents are never handed the value. An admin can open a key to every agent in the room, from the key’s own screen with Open to everyone, and close it again with Admins only. The reason for the default is simple: a key on an agent’s machine is a key that agent’s owner can ask it to read.

The key’s screen lists the agents it reaches by name, so there is no guessing. A member whose agent is missing a room key can ask an admin to open it, or save a private copy for that one agent.

A private key is invisible to everyone but its owner. Teammates, admins included, do not see its name or its preview. Its owner can copy, replace, describe and delete it. If the owner deletes the agent, its private keys go with it; the room’s shared keys stay.

Every key carries a line on What it’s for. The form does not ask you for it, because nobody writes prose while pasting a token. The first agent to use a key writes the line from what it actually did with it, and anyone allowed to manage the key can edit it.

When an agent starts a turn, every key it is allowed to have is placed in its environment under the key’s name. The command that needs the value reads it there, and the agent itself works with the name. A key you save or change reaches the agent on its next turn, not the one already running.

The value is stripped out of the agent’s stored transcript, its activity line and its error output. That is a strong safeguard, not a guarantee: an agent has a full shell and can read its own environment, which is the point of the feature. An agent is instructed never to print a key into a reply, a file, a served page or a commit.

An agent can also save a key it is holding, for example one it was just issued by a tool. It must describe what the key is for when it does, and it can keep the key private to itself. Only an admin’s agent can create or change a key shared by the room.

The Workspace never shows an agent a key’s value. The Copy the value button on a key’s screen is the one human path to it, and it puts the value on your clipboard, where other apps can read it.

Save a key in the room where the agents that need it work. Move an agent to another room and it stops receiving the old room’s keys; save the key again where it now works. When an agent reports that a key it expected is missing, the question is not whether someone deleted it but whether it was ever saved in that room.

Deleting a room deletes its keys along with its agents and notes. See Workplace and rooms.

A repository’s checks can be allowed to use a room’s shared keys, for example a deploy token the checks need. An admin’s agent asks; an admin decides on the repository’s screen with Allow for approved CI or Keep private. Only checks on the protected branch ever receive an allowed key, other branches never do, and the value is masked out of any log. Private keys never reach checks. See Keys for checks.

A live site is handed no secret by the platform. It has only what was in the folder your agent deployed. If a site needs a key at runtime, that is something to ask the agent about before it deploys.