> ## Documentation Index > Fetch the complete documentation index at: https://docs.pinework.ai/llms.txt > Use this file to discover all available pages before exploring further. # Secrets > A secret is an encrypted value in the workspace Keychain that only a person can reveal, and a cloud run uses it through Pinework's network edge without the value entering the sandbox. 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: ```bash theme={null} pinework secret read --reason "Rotating the Vercel token" --json ``` 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. ```bash theme={null} pinework secret create --name vercel-token --template api_key \ --field "token=password=" --url https://api.vercel.com ``` 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 `. 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: ```bash theme={null} pinework mcp create --name vercel --type http \ --url https://mcp.vercel.com --secret-ref vault:vercel-token ``` 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](/guides/add-a-provider-key) and [Add a connection](/guides/add-a-connection). ```text theme={null} person ──▶ Reveal value (audited) │ secret ── Keychain (encrypted) ──▶ agent: names and details only │ cloud run ─▶ sandbox holds a placeholder network edge adds the value, only for the secret's URLs device run ─▶ value sent to your machine for the MCP server that names it ``` Connect a tool that uses a secret. Where a run executes and what it can reach. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.