Skip to main content
A secret is a named value, such as an API token or a login, stored encrypted in your workspace. A person can reveal its value. An agent can use it in a run but cannot read it. You manage secrets on the Keychain page in settings.

​
The Keychain returns names, not values

Pinework encrypts a secret’s fields on the server when you save them. After that, listing or opening a secret returns its details only. You see the name, type, description, URLs and who can use it. Revealing a value is a separate, audited action. In the dashboard, it is the Reveal value button on a secret. In a terminal, it is this command:
Without --json, the command prints the field labels but no values. Every reveal is logged, with your reason if you give one. If Pinework cannot log the reveal, it returns no value. Only a person can reveal a value. An agent that asks is refused, whatever access it has. An agent can store a new secret, such as a token it just created. It cannot read that value back afterwards.

​
A secret knows where it may be sent

Each secret has a type: API Key, Login, Identity or Custom. It can also list URLs, such as https://api.vercel.com. The URLs name the services the secret is meant for.
Only a person can set or change a secret’s URLs. An agent that tries is refused. So an agent cannot point a secret at a server it controls. A secret’s visibility decides which runs can use it:
  • private keeps it to its owner and workspace admins. No run ever receives it.
  • company lets any agent in the workspace use it. This is the default.
  • custom limits it to the people and agents you pick.

​
A cloud run gets a placeholder, not the value

A cloud run never holds the raw value of a secret. Pinework applies it at the network edge, outside the sandbox:
  1. Inside the sandbox, the agent sees a placeholder where the secret would be.
  2. The agent sends an HTTPS request to a host listed in the secret’s URLs.
  3. Pinework’s network edge adds the real value to that request’s header. The default header is Authorization: Bearer <value>.
Requests to any other host get nothing. A cloud run refuses to start in two cases:
  • A secret attached to the agent lists no HTTPS URL.
  • Two secrets would send the same header to the same host.

​
An MCP server can use a secret by name

An MCP server can take its key from a secret. You point it at the secret with a vault: reference:
The server receives the value in its Authorization header by default. --header-name picks another header. The reference works only if the agent’s run can see the secret. In a cloud run, Pinework adds that header at the network edge too. The sandbox holds the server’s URL with no key. A cloud run does not start MCP servers that run a local command, except Playwright.

​
On your own device, the value reaches your machine

A device run executes on your machine, outside Pinework’s network edge. When an MCP server there uses a vault: reference, Pinework sends the real value to your device. The value goes into that server’s settings or its startup variables. Processes on that machine, including the agent’s harness, can reach those settings. Treat a secret you use in a device run like any password on your own computer. For the strongest separation, use it from a cloud run instead.

​
Runs show names only

A run’s details list the names of its secret variables and the vault: references it used. The panel shows “Key names and Keychain references only.” Pinework does not store a variable’s value on the run.

​
The Keychain also lists provider keys and connections

The Keychain page lists your provider keys and connections next to your secrets. They reach runs by their own rules. See Add a provider key and Add a connection.

Add an MCP server

Connect a tool that uses a secret.

Cloud and your machine

Where a run executes and what it can reach.