Skip to main content
Superserve provides encrypted secret storage for environment variables. Secrets are injected into your agent’s runtime environment and proxied through a credential proxy so they never appear in LLM context, logs, or tool outputs.

​
Setting Secrets

Set secrets using the secrets set command: 
superserve secrets set my-agent KEY=VALUE
Set multiple secrets at once: 
superserve secrets set my-agent \
  ANTHROPIC_API_KEY=sk-ant-... \
  DATABASE_URL=postgresql://...
Secrets are encrypted at rest and transmitted over HTTPS. They are only decrypted inside the isolated sandbox environment at runtime.

​
Listing Secrets

View the secret keys (not values) configured for an agent: 
superserve secrets list my-agent
Output: 
Secrets for agent 'my-agent':

Key
────────────────────
ANTHROPIC_API_KEY
DATABASE_URL
Secret values are write-only. You cannot retrieve secret values after setting them. If you need to update a secret, set it again with the new value.

​
Deleting Secrets

Remove a secret from an agent: 
superserve secrets delete my-agent ANTHROPIC_API_KEY

​
Required Secrets

Declare required secrets in your superserve.yaml: 
name: my-agent
command: python agent.py
secrets:
  - ANTHROPIC_API_KEY
  - DATABASE_URL
Superserve will:
  • Warn you after deployment if required secrets are missing
  • Prevent runs from starting if required secrets are not set
Example workflow: 
# Deploy the agent
superserve deploy

# CLI reminds you to set secrets
# Set your secrets before running:
#   superserve secrets set my-agent ANTHROPIC_API_KEY=...

# Set the required secrets
superserve secrets set my-agent ANTHROPIC_API_KEY=sk-ant-...

# Now you can run the agent
superserve run my-agent

​
Accessing Secrets in Your Agent

Secrets are available as environment variables in your agent’s runtime: Python: 
import os

api_key = os.environ["ANTHROPIC_API_KEY"]
db_url = os.environ["DATABASE_URL"]
TypeScript/Node.js: 
const apiKey = process.env.ANTHROPIC_API_KEY;
const dbUrl = process.env.DATABASE_URL;
Bun: 
const apiKey = Bun.env.ANTHROPIC_API_KEY;
const dbUrl = Bun.env.DATABASE_URL;

​
Credential Proxy

Superserve includes a credential proxy that intercepts API requests and injects credentials at the network level. This means:
  • API keys never appear in LLM context or prompts
  • Keys are not visible in logs or tool outputs
  • Agents can’t accidentally leak credentials to users
The proxy works transparently for HTTP requests made from your agent. No code changes are required. Supported patterns: 
# All of these work with the credential proxy
import anthropic
import openai
import requests

# Claude Agent SDK
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

# OpenAI
client = openai.OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Direct HTTP
response = requests.get(
    "https://api.example.com/data",
    headers={"Authorization": f"Bearer {os.environ['API_TOKEN']}"}
)
The credential proxy operates at the network layer, so it works with any HTTP client library.

​
Secret Naming Conventions

While you can use any naming convention, we recommend following these patterns: API Keys:
  • ANTHROPIC_API_KEY
  • OPENAI_API_KEY
  • STRIPE_SECRET_KEY
Database URLs:
  • DATABASE_URL
  • POSTGRES_URL
  • REDIS_URL
OAuth/Auth:
  • GITHUB_TOKEN
  • GOOGLE_CLIENT_SECRET
  • JWT_SECRET
Cloud Provider Credentials:
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • GCP_SERVICE_ACCOUNT_KEY

​
Common Patterns

​
Multi-Environment Secrets

Deploy separate agents for different environments: 
# Development agent
superserve deploy --name my-agent-dev
superserve secrets set my-agent-dev \
  ANTHROPIC_API_KEY=sk-ant-dev... \
  DATABASE_URL=postgresql://dev...

# Production agent
superserve deploy --name my-agent-prod
superserve secrets set my-agent-prod \
  ANTHROPIC_API_KEY=sk-ant-prod... \
  DATABASE_URL=postgresql://prod...

​
Rotating Secrets

Update secrets without redeploying your agent: 
# Rotate an API key
superserve secrets set my-agent ANTHROPIC_API_KEY=sk-ant-new...

# Agent automatically uses the new key on next run
superserve run my-agent

​
Shared Secrets Across Agents

Set the same secret for multiple agents: 
for agent in agent-1 agent-2 agent-3; do
  superserve secrets set $agent SHARED_API_KEY=sk-...
done

​
Security Best Practices

Never commit secrets to version control. Use .env.example to document required keys without exposing values:
# .env.example
ANTHROPIC_API_KEY=
DATABASE_URL=
Use read-only credentials when possible. If your agent only needs to read data, create credentials with read-only permissions.
Additional recommendations:
  1. Rotate secrets regularly - Update API keys and credentials on a regular schedule
  2. Use least-privilege access - Grant only the permissions your agent needs
  3. Monitor secret usage - Check logs for unauthorized access attempts
  4. Delete unused secrets - Remove secrets when agents are decommissioned

​
Troubleshooting

​
Missing Required Secrets

If you try to run an agent without required secrets: 
superserve run my-agent
Error: 
Error: Missing required secret(s): ANTHROPIC_API_KEY
Set them with:
  superserve secrets set my-agent ANTHROPIC_API_KEY=...
Solution: Set the missing secrets before running.

​
Secret Not Available in Runtime

If your agent can’t find an environment variable: 
KeyError: 'ANTHROPIC_API_KEY'
Check:
  1. Verify the secret is set: superserve secrets list my-agent
  2. Ensure the key name matches exactly (case-sensitive)
  3. Check your agent code is reading from environment variables

​
Invalid Secret Format

The secrets set command expects KEY=VALUE format: 
# ❌ Wrong
superserve secrets set my-agent ANTHROPIC_API_KEY sk-ant-...

# ✅ Correct
superserve secrets set my-agent ANTHROPIC_API_KEY=sk-ant-...

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us