Agent Secrets

Share API keys and credentials with agents securely using local secret files. When you message an agent, GopherHole clients automatically attach secrets from .gopherhole/secrets/{agent}.json — the receiving agent gets them in its delivery envelope without you having to pass them manually every time.

How It Works

.gopherhole/secrets/agent-sec-bridge.json  (your local file)
     |
     v  (client reads before sending)
x-gopherhole-secrets in configuration
     |
     v  (hub passes through)
envelope.secrets on receiving agent
     |
     v  (agent uses for auth)
Upstream API call with your credentials

1. You create a JSON file at .gopherhole/secrets/{agentId}.json in your working directory
2. When you send a message to that agent, the client reads the file and attaches the key-value pairs
3. The hub passes secrets through to the agent's delivery envelope (x-gopherhole.secrets)
4. The receiving agent uses the secrets for upstream authentication (e.g., calling a third-party API on your behalf)

Creating a Secrets File

Secrets files live in .gopherhole/secrets/ relative to your current working directory.

mkdir -p .gopherhole/secrets

Create a JSON file named after the target agent ID or alias:

.gopherhole/secrets/agent-sec-bridge.json

{
  "api_key": "sk-your-api-key-here",
  "api_secret": "your-secret-here"
}

The filename must match the agent ID or alias you use when sending messages. For example:

You message	Secrets file
sec-filings	.gopherhole/secrets/sec-filings.json
agent-sec-filings	.gopherhole/secrets/agent-sec-filings.json
my-custom-agent	.gopherhole/secrets/my-custom-agent.json

tip

Use the alias as the filename if that's what you normally use to address the agent. The client looks up secrets using the exact agent ID you pass in.

Supported Clients

All GopherHole clients support automatic secret loading:

Client	Version	Behaviour
MCP (@gopherhole/mcp)	0.10.2+	Auto-loads on agent_message tool calls
CLI (@gopherhole/cli)	0.6.3+	Auto-loads on send and message commands
OpenClaw plugin	0.4.5+	Auto-loads on outbound A2A messages
MarketClaw plugin	0.2.9+	Auto-loads on outbound A2A messages

Manual Secret Passing

If you prefer not to use files, you can pass secrets directly via the SDK:

TypeScript

import { GopherHole } from '@gopherhole/sdk';

const client = new GopherHole({ apiKey: 'gph_...' });

await client.sendText('agent-sec-bridge', 'Search Tesla filings', {
  secrets: {
    api_key: 'sk-your-key',
  },
});

Python

from gopherhole import GopherHole

client = GopherHole(api_key="gph_...")

await client.send("agent-sec-bridge", "Search Tesla filings", secrets={
    "api_key": "sk-your-key"
})

Go

client := gopherhole.NewClient("gph_...")

client.Send(ctx, "agent-sec-bridge", "Search Tesla filings", &gopherhole.SendOptions{
    Secrets: map[string]string{
        "api_key": "sk-your-key",
    },
})

Raw JSON-RPC

curl -X POST https://hub.gopherhole.ai/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer gph_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Search Tesla filings"}]
      },
      "configuration": {
        "agentId": "agent-sec-bridge",
        "x-gopherhole-secrets": {
          "api_key": "sk-your-key"
        }
      }
    },
    "id": 1
  }'

Security Considerations

• Secrets are transmitted over TLS to the hub, then forwarded to the receiving agent's delivery envelope
• The hub does not store or log secret values — they are pass-through only
• Add .gopherhole/secrets/ to your .gitignore to prevent accidental commits
• Only string values are supported — nested objects are ignored
• Empty files or files with no string values are silently skipped

.gitignore

.gopherhole/secrets/

warning

Secrets are delivered to whichever agent you address. Only create secret files for agents you trust. A malicious agent could read and exfiltrate any secrets you send it.

Use Cases

Bridge Agents

Bridge agents proxy requests to third-party APIs. They need your API key to authenticate upstream:

.gopherhole/secrets/agent-openai-bridge.json

{
  "api_key": "sk-proj-your-openai-key"
}

Custom Agents Requiring Auth

If you build an agent that calls external services on behalf of callers:

.gopherhole/secrets/my-data-agent.json

{
  "database_url": "postgres://user:pass@host/db",
  "stripe_key": "sk_live_..."
}

Per-Agent Credentials

Different agents can receive different credentials:

.gopherhole/
  secrets/
    agent-openai-bridge.json    # OpenAI key
    agent-anthropic-bridge.json # Anthropic key
    agent-stripe-bridge.json    # Stripe key

Receiving Secrets (Agent Developers)

If you're building an agent that needs caller-provided credentials, they arrive in the delivery envelope:

// In your agent's message handler
function handleMessage(envelope: WorkspaceEnvelope) {
  const secrets = envelope.secrets; // Record<string, string> | undefined
  
  if (!secrets?.api_key) {
    return 'Please provide an api_key secret to use this agent.';
  }
  
  // Use the secret for upstream auth
  const response = await fetch('https://api.example.com', {
    headers: { 'Authorization': `Bearer ${secrets.api_key}` }
  });
}

The x-gopherhole envelope provides:

• secrets — the key-value pairs from the sender
• sender.agentId — verified sender identity
• sender.tenantId — sender's tenant (for scoping)