Vault for API keys and secrets

The Vault is where you keep API keys, tokens and passwords in Granular. It stores them encrypted on your computer and hands them to your sessions' terminals by name, so the agent can use a service, such as OpenAI or Stripe, without the key appearing in the chat. You'll find it in Settings → Key Vault.

An API key is a long password that lets software use your account with another company's service.

How the agent uses a secret

When a secret is switched on for sessions, Granular gives it to each new session's terminal as an environment variable: a named setting that programs can read, such as MY_API_KEY. The agent then writes commands that refer to the name, for example $MY_API_KEY, and the terminal fills in the value. The key does its job, but it isn't typed into the chat or saved in your files.

The agent is instructed to use secrets only by name and never to print, paste or save their values. Granular also removes your saved secret values from its own log files and diagnostic reports. One thing it can't hide: if a command itself prints a key, that output appears in the terminal like any other. So don't ask the agent to show you a key; use Copy in the Vault instead.

Before you start

• The key or secret from the service's website.
• A name for the environment variable. If the service or your code expects a particular name, such as STRIPE_SECRET_KEY, use that. Otherwise any name in capitals works, such as MY_API_KEY.

Add a secret

1. Click the Settings button (the gear icon).
2. Click Key Vault.
3. In Name, type a label for yourself, for example OpenAI.
4. In the box next to it (it shows OPENAI_API_KEY as an example), type the environment variable name, for example MY_API_KEY. Lowercase letters are turned into capitals for you.
5. In The key itself, paste the secret.
6. Click Add, or press Enter.

What you'll see

Granular says Saved. The secret is encrypted and will not be shown again. The entry appears in the list with:

• its Name,
• its environment name and encrypted,
• an In sessions checkbox, already ticked if you gave it an environment name,
• a Copy button and a ✕ button.

Every new session's terminal now has the secret. If a session was already open, it offers to reload its terminal (see When changes take effect).

What decides whether a session gets a secret

Exactly three things, and nothing else:

1. In sessions is ticked for the entry.
2. The entry has an environment name.
3. The session's project is allowed to use it. New entries are allowed in all projects.

The name you give an entry doesn't matter. Some people end their environment names with a marker such as _GRANULAR to spot them later, but that is only a habit: Granular never looks for it, and you never need to rename a key to make it reach a session.

Choose which projects get a secret

Every entry starts out available to all projects. To limit it:

1. Click the ⋮ button next to the project's name (its tooltip says Project settings).
2. Under Vault keys in this project, tick the keys this project's sessions should get, and untick the ones they shouldn't. Each key shows all projects or how many projects have it.

Each tick takes effect as soon as you click it; you don't need to press Save for these.

Be careful with a key marked all projects: unticking it in one project turns it off for every project. Then tick it in each project that should keep it. Ticking a key here also switches on In sessions for it.

After changing a project's keys, start a new session in that project, so its terminal picks up the change.

When changes take effect

A terminal receives its secrets when it starts. So:

• New sessions get your changes straight away.
• Sessions already open keep what they started with. When you add, switch on, switch off or delete a secret, their terminal shows New secret available, and the chat shows A Vault secret changed. Reload the terminal so the agent can use it. Click Reload.

Reloading restarts that session's terminal with the new set of secrets. Anything running in the terminal stops, so Granular won't reload while the agent's command is still running; wait for it to finish, then click Reload. Click Dismiss or ✕ to leave it for now.

Changing a key's projects in Project settings doesn't show this offer. Start a new session instead.

Change or undo it

• Stop sessions getting a secret: untick In sessions. The secret stays saved.
• Replace a key, or add or change its environment name: there is no edit button. Add the entry again with exactly the same Name, the new or same key, and the environment name you want. It replaces the old one and keeps its project choices.
• Copy a key: click Copy. The value goes to your clipboard and stays there until you copy something else.
• Delete: click ✕. There is no confirmation; the secret is deleted from this computer. Open sessions offer to reload so their terminal drops it.

Where secrets are stored

• On this computer only. Vault secrets are not uploaded to your Granular account and don't follow you to another computer. Add them again there.
• Encrypted with your computer's built-in secure storage, the same protection your operating system uses for saved passwords (the Keychain on a Mac). The row says encrypted when this worked.
• If secure storage isn't available, Granular still saves the secret but can't encrypt it, and the row says stored (keychain unavailable). Treat that as not protected.
• Granular never shows a value again after you add it. Only Copy reads it back, to your clipboard.

If your computer's secure storage is reset, Granular can no longer read secrets saved before, and they behave as if empty. Add them again.

Vault keys and AI connection keys

The Vault is for keys your projects use: a payment service, an email service, an image generator that your code or the agent's commands call.

Keys that run Granular's agent go elsewhere:

• Anthropic, OpenAI and Gemini keys go in the connection menu under the message box, in Add by API key. See Connect an AI model.
• Custom provider keys go in Add custom provider. See Add a custom AI provider.
• Keys for connectors are pasted in Settings → Connectors. A built-in connector such as GitHub can use a matching Vault key instead. See Built-in connectors.

Those keys are stored encrypted in the same protected storage, but they are not listed in the Vault, and a key in the Vault doesn't power the agent's AI model. One overlap: a connector that asks for a key by environment name can use a Vault entry with that same name, as long as In sessions is ticked, so you don't need to paste it twice.

Limits

• Names: up to 40 characters, starting with a letter or number, using letters, numbers, spaces, dots, dashes and underscores.
• Environment names: up to 50 characters, starting with a capital letter, using capitals, numbers and underscores.
• Secrets: up to 10,000 characters.
• No per-session choice. A session gets every secret that is switched on and allowed in its project.
• No editing in place. Re-add with the same Name to change an entry.

Troubleshooting

If the agent says the key isn't set, or a command can't find it

1. In Settings → Key Vault, check In sessions is ticked and the entry shows an environment name.
2. Check the name the command uses matches the environment name exactly, including capitals.
3. In Project settings → Vault keys in this project, check the key is ticked for this project.
4. Click Reload on the notice in the chat or terminal, or start a new session. You never need to rename the key or add a suffix.

If "In sessions" is greyed out
The entry has no environment name (the row says no environment name). Add it again with the same Name, the key and an environment name.

If you see "Give the entry a short name (letters, numbers, spaces, dots, dashes)."
The Name is empty, too long (over 40 characters) or has other symbols. Shorten it or remove the symbols.

If you see "Environment names look like OPENAI_API_KEY - capitals and underscores."
The environment name has spaces, dashes or other symbols, or starts with a number. Use only capitals, numbers and underscores, starting with a letter, for example MY_API_KEY.

If you see "A new entry needs the secret itself."
Paste the key in The key itself before clicking Add.

If you see "That secret is suspiciously long."
The value is over 10,000 characters. You may have pasted a whole file instead of the key.

If the row says "stored (keychain unavailable)"
Your computer's secure storage wasn't available, so the secret is saved without encryption. Check your computer isn't blocking Granular's access to saved passwords, delete the entry, and add it again.

If Copy says "Nothing stored there."
Granular can't read that secret, usually because your computer's secure storage was reset. Delete the entry and add it again.

If Reload doesn't seem to work
The agent's command may still be running. Wait for it to finish and click Reload again, or start a new session.

If a key works in one project but not another
Check Vault keys in this project in the other project's settings.

If a key shows up on screen
Treat it as exposed. Create a new key with the service, cancel the old one, and add the new one with the same Name.

Related