← All articles

Overview

When Paperclip runs an agent using the claude_local adapter, it:

1. Spawns a Claude Code subprocess
2. Passes the agent's API key as ANTHROPIC_API_KEY
3. The Claude Code process uses this key for all model calls

The key is stored encrypted in Paperclip's secrets store and injected at runtime — it never appears in plain text in your filesystem or logs.

Getting API keys

Anthropic (Claude):

1. Go to console.anthropic.com
2. Click API Keys → Create Key
3. Copy the key — it starts with sk-ant-

OpenAI (for codex_local adapter):

1. Go to platform.openai.com
2. Click API Keys → Create new secret key
3. Copy the key — it starts with sk-

Google (for gemini_local adapter):

1. Go to aistudio.google.com
2. Click Get API key

How Paperclip stores secrets

Paperclip uses an encrypted secrets store (configured via PAPERCLIP_SECRETS_PROVIDER). By default, secrets are encrypted with a master key stored at PAPERCLIP_SECRETS_MASTER_KEY_FILE.

Critical: Back up your master.key file. If you lose it, you lose access to all stored agent secrets and must re-enter them.

# Backup location
/opt/paperclip/secrets/master.key

# The master key is a 32-byte hex string
cat /opt/paperclip/secrets/master.key

Setting agent API keys in the dashboard

1. In the Paperclip dashboard, go to your agent's settings
2. Find the Secrets / API Keys section
3. Add the key:
   • Key name: ANTHROPIC_API_KEY
   • Value: Your API key (starts with sk-ant-)
4. Save

The key is encrypted immediately. You can't read it back after saving — only replace it.

Setting agent API keys via the API

curl -X POST "$PAPERCLIP_API_URL/api/agents/AGENT_ID/secrets" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "ANTHROPIC_API_KEY",
    "value": "sk-ant-your-key-here"
  }'

Key rotation

When you need to rotate an API key (good security practice, or after a key compromise):

1. Generate a new key in the provider's console
2. Update in Paperclip:

# Update via API
curl -X POST "$PAPERCLIP_API_URL/api/agents/AGENT_ID/secrets" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "ANTHROPIC_API_KEY",
    "value": "sk-ant-your-NEW-key-here"
  }'

3. Revoke the old key in the provider's console

Sharing keys across agents vs. per-agent keys

Option 1: One key per agent Each agent has its own Anthropic API key. Costs are tracked separately per key in the Anthropic console.

Option 2: Shared key All agents use the same key. Simpler to manage. You lose per-agent cost visibility in the provider console (though Paperclip still tracks costs internally).

For most deployments, a single shared Anthropic key is fine. Per-agent keys make sense if you need provider-level cost allocation by agent.

Checking API key validity

When an agent run fails with an authentication error, check:

# Test key directly
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-haiku-4-5-20251001", "max_tokens": 10, "messages": [{"role": "user", "content": "Hi"}]}'

A 401 response means the key is invalid or expired. A 403 means it's valid but lacks permissions.

API rate limits and multiple agents

Running many agents with the same API key can hit Anthropic's rate limits. Check your tier's limits at console.anthropic.com.

If you're running 10+ concurrent agents:

• Consider upgrading your Anthropic tier
• Spread agent heartbeat schedules to reduce concurrent API calls
• Use separate keys for high-priority vs. low-priority agents

Cost monitoring per agent

Paperclip tracks token usage and cost per agent run. View in the dashboard:

• Agent → Runs tab → each run shows token count and estimated cost
• Monthly summary in the company billing section

Set budget limits per agent (budgetMonthlyCents) to auto-pause agents that exceed their allocation. This prevents unexpected bills.

Environment variable alternative

For deployment environments where dashboard access is limited, inject API keys as environment variables before starting Paperclip:

# In your .env file
ANTHROPIC_API_KEY=sk-ant-your-key-here

Then reference them in agent adapter config. However, dashboard-based secrets management is more secure because keys are encrypted at rest and never appear in environment variable dumps.

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.