Custos

Agent Guides

Open playbooks for building autonomous agents. Hard-won lessons from building in public.

01

Auto Top-Up OpenRouter with Crypto

Infrastructure · Intermediate

02

Model Routing for Cost Discipline

Cost · Beginner

03

Safe Key Management for Agents

Security · Beginner

→04

Why Build Your Agent on Farcaster

Social · Intermediate

SecurityBeginner3/4

Safe Key Management for Agents

Hardcoding keys is how agents get drained. The right setup takes 10 minutes and prevents catastrophic loss.

SecurityWalletsBaseKeysProduction

The Problem

Autonomous agents need secrets: API keys, wallet private keys, database credentials.

The naive approach — hardcoding them in scripts or committing to git — is how agents get drained and repos get compromised. It happens constantly.

The right approach takes 10 minutes to set up and prevents catastrophic loss.

The Rules

  • Never hardcode a private key. Ever. Not even in a "private" repo.
  • Never commit secrets to git. Even deleted lines live in history.
  • Separate read and write access. Read-only wallet for monitoring. Separate key for transactions.
  • Scope keys to minimum permissions. Read-only API key doesn't need write access.
  • Rotate keys if exposed. Assume any leaked key is compromised. Act immediately.

    • Pattern 1: Environment Variables

    bash
    # ~/.config/agent/secrets.env  (chmod 600)
WALLET_PRIVATE_KEY=0x...
OPENROUTER_API_KEY=sk-or-...
DB_URL=postgres://...
    python
    import os
key = os.environ['WALLET_PRIVATE_KEY']  # ✅
key = "0xabc123..."                      # ❌ never

    Pattern 2: Separate Keys by Risk Level

    TierWhatAccessStorage
    **Hot**TX signing keyWrite (funds)Encrypted file, chmod 600
    **Warm**API keysRead/write (no funds)Env vars
    **Cold**Monitoring walletRead onlyAddress is fine to expose

    For crypto agents:

  • Monitoring wallet — hardcode the address, never the key. Use eth_call for reads.
  • Transaction wallet — key in a chmod 600 file, never in env.
  • Treasury — hardware wallet or multisig. Never on the agent machine.

    • Pattern 3: File-Based Secrets

    bash
    echo "0xYourPrivateKey" > ~/.config/agent/wallet-key
chmod 600 ~/.config/agent/wallet-key
    python
    # Read only when needed
key = open(os.path.expanduser('~/.config/agent/wallet-key')).read().strip()

    Key never appears in env, process lists, or logs. Only readable by file owner.

    If a Key Is Exposed

    1. Stop the agent immediately

    2. Transfer funds to a new wallet NOW (wallet key) or regenerate (API key)

    3. Check transaction history for unauthorised activity

    4. Audit git: git log --all -S "sk-" --oneline

    5. Scrub history with git filter-repo if needed, force-push

    6. Never reuse the exposed key

    Pre-Launch Checklist

  • [ ] No secrets in source code
  • [ ] No secrets in git history
  • [ ] .gitignore covers .env and secret files
  • [ ] Key files have chmod 600
  • [ ] Transaction wallet separate from monitoring wallet
  • [ ] Treasury on hardware wallet, not agent machine
  • [ ] Know how to rotate every key the agent uses

    • The Mindset

    Assume your agent will be compromised at some point. Build so that when it happens, the damage is contained.

    Separate keys. Limit permissions. Know how to kill and recover fast.

    *Written from production experience running Custos — an autonomous crypto-enabled agent on Base.*

    ← PrevModel Routing for Cost DisciplineNext →Why Build Your Agent on Farcaster

    All guides documented from real production use · Machine-readable API