Runtime Vault

Runtime Vault stores values that bots may need during execution: service tokens, MCP server credentials, repository credentials, customer-specific API keys, or configuration that should not live in a bot workspace.

Use provider credentials for Botyard-managed provider calls. Use Runtime Vault when the bot or an MCP server needs an application secret at runtime.

Create a Runtime Vault variable

1. Sign in to app.botyard.io.
2. Open Credentials.
3. Select the Runtime Vault tab.
4. Click Add variable.
5. Enter a dot-delimited key path, display name, value, max TTL, sensitivity, and bot access policy.

The key path is the stable reference bots and MCP templates use, for example github.tokens.read_only or mcp.snowflake.client_id.

Policy controls

Each Runtime Vault variable has a policy:

Secrets are encrypted with the same per-organization age/X25519 storage model used for provider credentials. Plaintext values are not returned by the API after creation or update.

How bots obtain secrets

Runtime Vault uses short-lived leases:

1. A bot requests a lease for a key path and provides a justification.
2. Botyard checks the secret policy for that bot.
3. If allowed, Botyard creates a lease with a bounded TTL and maximum redemption count.
4. The bot receives an opaque secret reference, not the plaintext value.
5. The runtime redeems the lease when the value is actually needed.
6. Redemption decrypts the value, records the access, and marks one redemption as used.

This separates authorization from plaintext delivery. A bot cannot mint a lease for another bot's unshared secret, and an expired or already-used lease cannot be redeemed again.

MCP server secret references

MCP setup templates can reference Runtime Vault key paths through env_secret_refs.

For example:

{
  "env_secret_refs": {
    "SNOWFLAKE_CLIENT_ID": "mcp.snowflake.client_id"
  }
}

When an MCP server is provisioned, Botyard resolves the key path through the secrets service instead of storing the plaintext in the MCP template. That lets an organization rotate the vault value without editing every template that references it.

Use env_secret_refs for durable MCP credentials. Use pasted plaintext only for non-sensitive or one-off setup values.

Who may add a secret reference

A running MCP server receives its referenced secrets with organization scope, so adding a reference is effectively granting that server the secret. The rules depend on who makes the change:

• People and API keys in the organization can reference any organization vault variable.
• Bots can only add a reference (in env_secret_refs, secret_file_mounts, or secret_headers) to a variable they could lease themselves. That means Allow all bots is on, or the bot is a linked bot, and the variable has not expired. Otherwise the change is refused with the standard "This secret is not available to this bot." error. The error is the same whether the variable is missing, unlinked, or expired.

A bot's change is checked only for references it adds. It can still edit other fields, or rename an environment variable that points at a secret the server already receives, without being linked to that secret.

The check runs when the server is created or updated. It is not re-evaluated later: unlinking a bot or turning off Allow all bots afterwards does not remove references that are already saved. To revoke a server's access, edit or delete the server's references.

Safety pattern

Runtime Vault follows a brokered secret access pattern with just-in-time leases:

• the policy decides which bots may request a secret
• the lease limits how long a grant is useful
• redemption limits how often it can be used
• audit events record request, grant, denial, redemption, and expiry
• sensitive values are included in exfiltration scanning

This gives bots access to credentials without making the workspace a permanent secret store.

Related docs

• Exfiltration scanning

• Audit logs

• MCP setup templates

• Manage Botyard with Terraform to declare vault secrets as code

For a product overview, see Runtime Vault on botyard.io.