Credential management

Agents reach external services with credentials you provide per agent. Credentials live inside the agent’s isolated container; they are never shared with other agents unless you inject them there too.

Where credentials live in an agent

.env                  # source of truth: KEY=VALUE
.mcp.json.template    # MCP servers with ${VAR} placeholders
.mcp.json             # rendered at start from the template and .env

When the agent starts, each MCP server declared in .mcp.json.template that is missing from .mcp.json is added with its ${VAR} placeholders filled from .env. A server whose values are missing is left out (with the reason in the logs) rather than written with blanks; servers you edited are never overwritten.

The setup checklist

Open the agent’s Settings → Storage → Credentials. The checklist lists:

• What the agent needs — from the credentials declaration in its template.yaml;
• Whether each is set — key names only; values are never read back;
• Where to get it — the setup link the template author provided.

Fill in the values and submit. The checklist works even while the agent is stopped.

Declaring credentials in a template

credentials:
  env_file:
    - OPENAI_API_KEY
  mcp_servers:
    slack:
      env_vars:
        - SLACK_BOT_TOKEN
credential_setup:
  - name: OPENAI_API_KEY
    title: OpenAI API key
    description: Lets the agent call OpenAI models directly.
    required: true
    secret: true
    setup_url: https://platform.openai.com/api-keys

Adding credentials

Method	Use it for
Setup checklist	Per-variable inputs with descriptions and links
Quick Inject	Pasting KEY=VALUE lines, merged into .env
Upload credential file	Service-account JSON (.config/gcloud/), kubeconfig, TLS certificates and keys, SSH key pairs
Import from Git	Decrypting a .credentials.enc backup from the agent’s repository

Changes to .env apply on the agent’s next run — no restart needed. Values you inject survive restarts. To change an MCP server’s credential on a running agent, inject an updated .mcp.json.

Files that run at startup (shell profiles), instruction files and authorized_keys can never be injected.

Who can read credentials

Only the agent’s owner or an admin, as a person, can read or write an agent’s credential files. People the agent is shared with and agent keys cannot. Every access is audited. Inside the container, guardrails stop the agent from editing credential files and scan output for leaked keys.

Encrypted backups

Export to Git writes the agent’s full credential set to .credentials.enc, encrypted with AES-256-GCM using your instance’s encryption key, so it can be committed with the agent’s repository. Import from Git restores it. The file is useless without the instance key.

Credential vault

The vault stores named credentials once and grants them to specific agents, so a shared secret is not copied into many .env files.

• Admins open Settings → Integrations → Agent credential vault, click Add a credential, then Grant it to the agents that may read it (and Revoke later).
• Agents read a granted value at runtime with the fetch_credential MCP tool; nothing is written to disk.

The vault is an instance module and a feature of the Scale and Enterprise plans (Plans & pricing).

API

Endpoint	Method	Purpose
/api/agents/{name}/credentials/status	GET	Which credential files exist
/api/agents/{name}/credentials/inject	POST	Write credential files (files, or base64 files_b64 for binaries)
/api/agents/{name}/credentials/export	POST	Write .credentials.enc
/api/agents/{name}/credentials/import	POST	Restore from .credentials.enc

All are owner/admin only.