Get API key

Secrets

View as Markdown

Store a password or API key once, attach it to the workspaces and jobs that need it, and read it from a file in your code.

Note

PrivateMind switches Secrets on one organisation at a time, and you need compute access to use it. If Secrets isn't in your Settings, ask your org admin or your account team.

A secret is a credential, such as a database password or an API token, that you store once in PrivateMind and attach by name to the workspaces and jobs that need it. Your code reads it from a file, so the value doesn't have to be pasted into a notebook cell or a .env file. When it changes you replace it in one place, and PrivateMind keeps it out of any workspace where someone who isn't allowed to read it could run code.

PrivateMind encrypts each value under a key used only for your organisation. A secret can also be brokered: it never enters the workspace, and PrivateMind adds it to the requests your code sends.

Where it lives

Secrets, in the Compute group of Settings (/settings/secrets), lists every secret you can use: your own, your teams' and your organisation's. Each team's page also has a Secrets tab. Org admins manage the organisation's secrets on the Secrets page of the organisation settings (/settings/org/secrets). You attach a secret where you set up the thing that uses it: a workspace's settings, the New workspace dialog or the Run a job form.

Whose secret it is

Every secret belongs to you, to a team or to the whole organisation, and never to a workspace. Attaching it to a workspace or job only links it there. Detaching removes the link and leaves the secret alone. Deleting the secret removes it from everywhere it's attached.

Owner Who sees it Who adds, replaces and deletes it
You You. Org admins see its name in the audit log and in the settings of any workspace it's attached to You
A team The team's members, and org admins on the team's page The team's owners and admins, and org admins
The organisation Everyone in it Org admins

You attach your own secrets, your teams' and your organisation's to your own workspaces and jobs. Org admins can also attach organisation secrets, and the secrets of teams they belong to, to another member's workspace, Personal ones included. They can detach any secret from any workspace. Every attachment still has to pass the rule below.

A name uses capital letters, digits and underscores and starts with a letter, such as DB_PASSWORD. Names are unique per owner, so DB_PASSWORD can exist as yours, a team's and the organisation's at once. A workspace or job holds only one of them, because the name becomes the file name.

A value can be text or a file, such as a certificate or a key file. Anyone who can see a secret can read its note, so keep values out of notes, and keep anything sensitive out of names. Once a secret exists you can replace its value, and under Edit details change its Type, how code uses it and its note. To rename it or give it to a team, add a new one and delete the old.

Where a secret can go

PrivateMind puts a secret's value only where everyone who can run code there is allowed to read it. Anyone who can open a workspace can run code in it. So can anyone who can write to a volume the workspace or job mounts, because they could change the code it runs.

A workspace is Personal when it mounts a personal volume. Nobody else in your organisation can open it, org admins included, and it can't be shared. Choose Personal when you create a volume, or use Make personal… on an existing one. Making a volume personal can't be undone.

  • Your own secrets go only into your own Personal workspaces and your own jobs, and only where nobody else can write to the home volume or any other volume they mount. A Private workspace won't do, because org admins can open it.
  • Team secrets go into a workspace or job only when its owner, and everyone else who can open it or write to its volumes, is in the team or is an org admin. That rules out every Shared workspace, which the whole organisation can open.
  • Organisation secrets go anywhere in the organisation, Shared workspaces included.

PrivateMind checks the rule when a secret is attached, and again whenever something changes who could run code there, as described below.

Who can read a secret

Once you've saved a value, the app never shows it again, to you or anyone else. People can still read it: anyone allowed to attach a secret can attach it to a workspace where they run code and read it there. So everyone in your organisation can read an organisation secret, and every member of a team can read that team's secrets.

Wherever a secret is attached, anything that runs code there can read it: everyone who can open the workspace, every program they run, and the coding agent. The agent follows instructions, including ones planted in a README or a web page it reads. Whatever reads a value can send it anywhere the workspace can reach. Encryption protects the saved value, and the rule above decides where it's delivered. Inside the workspace it's an ordinary file.

In the coding agent, a value that shows up in a tool's output or in your own message is replaced with [REDACTED:NAME] before the model sees it. That guards against accidents. The agent can still read the file.

So store the narrowest credential that does the job, such as a read-only database login or a token for one project. Attach it only where you'd accept everyone and everything above using it. A workspace on a restricted network has no route to the public internet, which limits where a value could be sent. If you think a value has leaked, get a new one from whoever issued it, then replace it here.

Reading a secret in your code

Each attached secret is a read-only file named after it:

Text
/var/run/privatemind-secrets/NAME

Read the file when you need the value:

Python
from pathlib import Path

token = Path("/var/run/privatemind-secrets/API_TOKEN").read_text()
cURL
curl -H "Authorization: Bearer $(cat /var/run/privatemind-secrets/API_TOKEN)" https://api.example.com/v1/items

To hand a value to one program as a variable, set it for that one command:

cURL
PGPASSWORD="$(cat /var/run/privatemind-secrets/DB_PASSWORD)" psql -h db.example.com -U analyst sales

If a tool wants a key file, give it the file's path.

In a workspace, the file always holds the current value. When someone replaces a value, a running workspace sees the new one within about a minute, with no restart. A stopped workspace gets it when it next starts. Code that opens the file each time it needs the value picks up a replacement by itself. Code that read it once at startup keeps the old value until you restart it.

Taking a secret away. Detaching or deleting a secret, or turning Secrets off, removes its file from running workspaces within about a minute. Code that opens the file after that finds nothing there. A terminal or notebook kernel that already had the secret as a variable keeps the value until you close or restart it. If you're containing a leak, restart those, or the whole workspace, and get a new value from whoever issued it.

As a variable. Each attachment to a workspace has a Variable switch, off by default. Turn it on and $NAME is also set in terminals and notebook kernels you start from then on. A variable is a copy taken when the terminal or kernel starts, so one that was already running keeps the old value until you restart it. Every program started there inherits the variable without asking and can print it or pass it on by accident, so turn it on only for a program that expects one.

Some secrets arrive only as files:

  • names that change how programs run, such as PATH, LD_PRELOAD or anything starting with GIT_ or SSH_
  • values too large for a variable
  • values containing a zero byte, as most binary files do

Older workspaces. A workspace started before Secrets was available needs one restart the first time you attach a secret to it, and the app tells you before it restarts. The restart closes running sessions and moves the workspace to its template's newest image, unless it's pinned to a version. A stopped workspace, or one started more recently, needs no restart. After that one restart, no change to a workspace's secrets needs another.

Brokered secrets

A brokered secret is never in the workspace. Code sends its request to PrivateMind's vault relay instead of the service, and the relay adds the credential and calls the service over HTTPS. There is no file and no variable to read, copy or leak by accident. It suits a credential that code only ever sends to a known service: an API token, a web login or an OAuth client.

Choose Brokered under How code uses it when you add the secret or edit its details, then set:

  • Sent as: Bearer token, API key in a header (name the header), Username and password, or OAuth client credentials. With OAuth, the relay trades the client secret for a short-lived token at the token URL you give.
  • Allowed hosts: where the credential may go, such as api.example.com, or *.example.com for every host under a domain. The relay speaks HTTPS to services on the public internet, on port 443 unless the allowed host names another, such as api.example.com:8443.
  • Allowed methods: GET and HEAD unless you allow more. Allow POST, PUT, PATCH or DELETE only when code has to change something.

In the workspace, pm-secrets list prints the address for each allowed host. Send plain HTTP there, with the service's path after it and no credential:

cURL
curl "$PRIVATEMIND_VAULT_RELAY_URL/v1/CRM_TOKEN/api.crm.example.com/v1/accounts"

Any HTTP client works the same way: use that address as its base URL. If pm-secrets list shows no addresses, the workspace's image is older than brokered secrets, so restart it to move it to its template's newest image.

pm-secrets git NAME HOST sends git's HTTPS traffic for that host through the relay. Git sends POST to clone and fetch, so the secret needs POST allowed, and that also lets git push with it.

The relay refuses a host or method you didn't allow with a 403, and its X-Pm-Vault-Refused header names the reason. The relay doesn't follow redirects. Replacing, detaching or deleting the secret reaches calls within about five minutes. Jobs use brokered secrets the same way.

A brokered secret goes only where the rule above allows, and two more apply:

  • It works only where PrivateMind runs the relay. Attaching it anywhere else, or switching an attached secret to brokered, is refused with a message saying so.
  • On a restricted network it can only read: a secret that allows POST, PUT, PATCH or DELETE can't be attached there. Reads still work, because the relay, not the workspace, makes the call.

A brokered secret can still be used where it's attached. Anyone and anything that can run code there, the coding agent included, can send requests with it to the hosts and methods you allow, and keep what comes back. So store the narrowest credential the service offers.

Database logins

The relay speaks HTTPS only, so a database password is always a file in the workspace, readable by everything described above. Make the login itself do the limiting, on the database side:

  • A login for this use only. Not a person's own login, and never one with administrator rights.
  • Read only, unless the code must write. Grant it the schemas or tables it needs and nothing else.
  • Only from where it's used. If the database can limit where a login connects from, allow only the addresses your workspaces connect from. A copied password is then no use anywhere else.
  • An expiry. Give the password an end date on the database, such as VALID UNTIL in PostgreSQL or PASSWORD EXPIRE INTERVAL in MySQL, and replace the secret here when you renew it. Running workspaces pick up the new value within about a minute.

Build the connection in code from the file. Don't write a connection string into a notebook or a config file, and don't print it. A connection error that dumps the full connection string is the usual way a database password ends up in a notebook's saved output.

In jobs

A workspace job reads its secrets from the same folder, /var/run/privatemind-secrets, and gets files only, never variables. Pick them in the Run a job form. A scheduled job, or one that an automation runs, can't take secrets.

A job copies its file secrets when it starts and keeps the copy until it ends. Replacing or deleting a secret, or turning Secrets off, doesn't touch the files of a job that's already running. To take a value away from a running job, delete the job. A brokered secret stops working in a running job within about five minutes, as in a workspace.

When people and workspaces change

When a change would let someone run code where they aren't allowed to read a secret, PrivateMind detaches the secret or removes that person's access. The workspace's Secrets section lists what it changed and why for seven days.

  • Sharing more widely. If you share a workspace or a volume with someone who isn't allowed to read one of its secrets, PrivateMind asks first and names the secrets. If you go ahead, it detaches them and makes the share at once. In a running workspace the old file can stay readable for up to a minute. If the people you're adding must never see it, stop the workspace first, or replace the value afterwards.
  • Leaving a team. When someone leaves a team, PrivateMind removes any share that names them personally on colleagues' workspaces and volumes holding the team's secrets, so those workspaces keep their secrets. Where they can still open such a workspace another way, such as through another team, the team's secrets are detached from it instead. The team's secrets are also detached from their own workspaces. None of this happens when the person is an org admin, because org admins can read every team's secrets. Anyone who leaves might already have read a value, so replace any they should no longer have.
  • Joining a team. PrivateMind re-checks the workspaces the team can open or write to, and detaches any other team's secret the newcomer isn't allowed to read.
  • Deleting a team. Its secrets are detached everywhere and deleted.
  • Leaving the organisation. When someone is removed from the organisation or moved to another, PrivateMind removes the shares that name them on workspaces holding secrets and detaches their own secrets everywhere.
  • Demoting an org admin. PrivateMind re-checks where secrets sit, because org admins count as readers of team and organisation secrets.
  • Reassigning a workspace. PrivateMind asks the workspace to stop if it's running, detaches every secret attached to it, and then changes the owner, without waiting for the workspace to finish stopping. If the secrets can't be detached, the owner stays as it was. The new owner attaches their own. The home volume goes with the workspace, so anything a value left there, such as shell history or notebook output, goes to the new owner too.

Turning Secrets on and off

Secrets stays off for an organisation until PrivateMind turns it on, so ask your account team if you want it. An org admin can't turn it on, but can turn it off at any time with the Secrets switch on the Workspaces card of Org settings.

Turning it off removes every secret's file from every workspace within about a minute. Terminals and notebook kernels that already had a secret as a variable keep it until they restart, and jobs already running keep their files until they end. Brokered secrets stop working within about five minutes. The secrets and their attachments are kept, but nobody can add or attach a secret until PrivateMind turns Secrets back on.

What is recorded

Secrets actions go into your organisation's audit log under the secret's name, never with its value:

  • adding, replacing and deleting a secret, and editing its details, such as its allowed hosts and methods
  • attaching and detaching, including turning Variable on or off, and the detaches PrivateMind makes, with the reason
  • turning Secrets on or off
  • each delivery, when PrivateMind decrypts a value to put it into a workspace or job, or hands a brokered one to the relay
  • each brokered call, counted per minute, with the host and method, and each refusal
  • each refused attempt to add, change or attach a secret, with the secret's name and the reason

A delivery that can't be recorded doesn't happen, and neither does adding, replacing, editing or attaching a secret. When PrivateMind removes someone's access to a workspace to protect a secret, that shows in the workspace's Secrets section, not in the audit log. Reading the file inside a workspace isn't recorded.

Troubleshooting

What you see What it means
A secret is greyed out when you attach It can't go there under the rule. The reason beside it says why, usually who else can open the workspace or write to its volumes.
A secret's file has gone from a workspace It was detached or deleted, or Secrets was turned off for your organisation. The workspace's Secrets section lists what PrivateMind detached and why.
$NAME holds an old value The terminal or kernel started before the change. Restart it, or read the file, which is always current.
$NAME is empty in a job Jobs never get variables. Read the file.
A brokered call returns 403 If it has an X-Pm-Vault-Refused header, the relay refused it and the header says why, usually a host or method the secret doesn't allow, or a secret that isn't attached to this workspace. Without that header, the service itself refused it.
pm-secrets git says git sends POST The secret allows only GET and HEAD, and git can't clone or fetch without POST.
[REDACTED:NAME] in the coding agent A secret's value appeared in tool output or your message and was replaced before the model saw it. Nothing is broken; the agent can still use the file.

Where next

  • Workspaces: visibility, sharing and the coding agent.
  • Workspace jobs: run one command on your home volume, with secrets as files.
  • Org settings: the switch that turns Secrets off for your organisation.
  • Users & teams: team roles, and who manages a team's secrets.
  • Audit logs: where Secrets actions are recorded.