Configuration

Vouch stores all its local state under ~/.vouch/. This page explains every file, every config field, and how to customize your setup.

Download

Directory Layout

~/.vouch/
├── config.toml              # Main config file — all settings live here
├── keys/
│   ├── 0x<wallet>.json      # Identity key (role: "identity")
│   └── 0x<runtime>.json     # Runtime key (role: "runtime")
├── allowlist.toml           # Trusted senders list
└── agents/
    └── <agent-name>/        # Agent projects (created by vouch agent create)
        ├── vouch-agent.toml
        ├── handler.mjs
        └── ...

Config File: config.toml

The main config file is created automatically by vouch init. You can also create or edit it manually.

Location: ~/.vouch/config.toml (override with --config <path>)

Full reference

# ─── Network ────────────────────────────────────────────────
# Options: "base-sepolia" (testnet, default) or "base" (mainnet)
network = "base-sepolia"

# ─── Endpoints ──────────────────────────────────────────────
api_url = "https://api.vouch.directory"
rpc_url = "https://sepolia.base.org"

# ─── Chain ──────────────────────────────────────────────────
chain_id = 84532
vouch_hub_address = "0x4483508dE005fCD42B1060dB69556d2b8e2Cd18E"
forwarder_address = "0x98239780251e763F404d9F000A37978B0F029D65"

# ─── Identity ───────────────────────────────────────────────
wallet_address = "0x..."
x_handle = "your_x_handle"
github_handle = "your_github_handle"
domain = "example.com"

# ─── API Authentication ────────────────────────────────────
api_key = "vk_..."

# ─── Delegation (saved automatically after vouch delegate) ──
runtime_key_address = "0x..."
delegation_expires_at = 1760003600
delegation_scope = "messaging"
delegation_duration = "24h"

What each section does

Section	Purpose
Network	Loads a preset that fills in API URL, RPC URL, chain ID, and contract addresses
Endpoints	Where Vouch connects to query on-chain data and submit transactions
Chain	Chain ID and contract addresses — part of the EIP-712 domain separator (testnet signatures can’t replay on mainnet)
Identity	Your wallet address and cached linked account handles for display
API Authentication	API key for relay transactions and verification calls
Delegation	Tracks your current runtime key so `vouch sign` and `vouch delegate --renew` work without extra flags

Network Presets

Base Sepolia (testnet, default)

network = "base-sepolia"
chain_id = 84532
rpc_url = "https://sepolia.base.org"
api_url = "https://api.vouch.directory"

Base Mainnet (production)

network = "base"
chain_id = 8453
rpc_url = "https://mainnet.base.org"
api_url = "https://api.vouch.id"

Switch networks at runtime without changing your config:

terminal

vouch --network base whoami        # mainnet
vouch --network base-sepolia sign  # testnet

Environment Variable Overrides

Every config field can be overridden by an environment variable. Useful for CI/CD, containers, or testing.

Environment Variable	Config Field
`VOUCH_NETWORK`	`network`
`VOUCH_API_KEY`	`api_key`
`API_URL`	`api_url`
`RPC_URL`	`rpc_url`
`VOUCH_HUB_ADDRESS`	`vouch_hub_address`
`FORWARDER_ADDRESS`	`forwarder_address`
`CHAIN_ID`	`chain_id`
`VOUCH_WALLET_KEY`	(pipe mode wallet key)

RPC URL resolution order: RPC_URL → network-specific variable (BASE_MAINNET_RPC_URL or BASE_SEPOLIA_RPC_URL) → ALCHEMY_API_KEY auto-detection → config file value → network preset default.

Key Storage

Keys are stored as encrypted JSON files in ~/.vouch/keys/:

key file format

{
  "address": "0xABC123...",
  "ciphertext": "hex-encoded encrypted private key",
  "nonce": "hex-encoded 12-byte GCM nonce",
  "salt": "hex-encoded 32-byte salt",
  "role": "identity",
  "kdf": "argon2id"
}

Property	Detail
KDF	Argon2id (memory=64MB, iterations=1, parallelism=4)
Cipher	AES-256-GCM
Passphrase	Can be empty for agent automation
Permissions	`0600` (only you can read)

Roles: identity keys can link accounts, delegate, revoke, and publish. runtime keys can only sign payloads.

Allowlist File

Stored at ~/.vouch/allowlist.toml and managed by the vouch allowlist commands.

[[entries]]
type = "wallet"
value = "0xABC123..."
added_at = "2026-02-19T20:00:00Z"
note = "trusted partner"

[[entries]]
type = "handle"
value = "alice"
added_at = "2026-02-19T20:00:00Z"
note = "my friend"

When the allowlist has entries, vouch verify and vouch receive reject messages from senders not on the list. An empty allowlist (or no file) allows all senders.

Moving to a New Machine

Copy the entire ~/.vouch/ directory to the new machine and everything works.

terminal

# On the old machine
tar czf vouch-backup.tar.gz ~/.vouch/

# On the new machine
tar xzf vouch-backup.tar.gz -C ~/

# Verify it works
vouch whoami

If your runtime key delegation has expired (default 24h), just renew it:

terminal

vouch delegate --renew