Bardo Tools – Configuration [SPEC]

Version: 4.0.0 Last Updated: 2026-03-14

Crate: bardo-tools | Prerequisites: 01-architecture.md (ToolDef pattern, trust tiers, capability tokens, safety hooks, and profiles)

Environment variables, config file schema, startup validation, health checks, capability token configuration, and API key tiers.

Reader orientation: This document specifies the configuration system for bardo-tools: environment variables, TOML config file schema, startup validation, health checks, and API key tiers (Read/Feedback/Write). Configuration controls safety policies, wallet settings, chain RPC endpoints, and tool profiles. You should be comfortable with TOML configuration and environment variable precedence patterns. Bardo-specific terms are defined inline on first use; for a full glossary see prd2/shared/glossary.md.

Configuration hierarchy

CLI flags  >  Environment variables  >  Config file  >  Defaults

Environment variables always override config file values. Never put secrets in the config file – use env vars for all credentials.

Environment variables

All environment variables use the BARDO_ prefix.

Core

Pi runtime

Wallet

Capability token limits

Capability tokens gate every write operation. These env vars set the default limits baked into each token. The safety extension reads them once at boot and uses them when minting Capability<T> tokens for write tool handlers.

RPC overrides

External APIs and data

Uniswap Trading API

Uniswap API config is in the [uniswap_api] section of golem.toml (see full example above).

ERC-8004 identity

Memory (Grimoire)

x402 outbound

Startup validation

On startup, the tool library validates all configuration via serde deserialization with custom validation logic. Invalid or missing required values produce clear error messages with suggested fixes:

Profile "trader" requires a wallet, but none is configured.

Configure one of:
  - BARDO_WALLET_PRIVATE_KEY  (dev only)
  - BARDO_PRIVY_APP_ID + BARDO_PRIVY_APP_SECRET  (production)

Or switch to the data profile: BARDO_PROFILE=data

Cross-field validation: BARDO_IPFS_MODE=pinata requires BARDO_PINATA_JWT.

Structured startup log

Bardo Tools v4.0.0 starting...

   Profile:     trader
   Chains:      ethereum (1), base (8453), arbitrum (42161)
   Wallet:      Privy server wallet (0xAbCd...1234)
   Safety:      max $1,000/tx - $10,000/day - strict token allowlist
   Tools:       27 adapters loaded
   A2A:         disabled

   No custom RPCs configured -- using public endpoints.
   Set BARDO_RPC_ETHEREUM for better reliability.

Ready. Extension registered with Pi session.

When BARDO_LOG_FORMAT=json, a structured JSON line is emitted instead.

--health flag

bardo-tools --health

Checks connectivity to all configured services (RPCs, subgraph, wallet provider). Exit codes:

Config file schema (golem.toml)

Optional complement to environment variables. Useful for team-shared baseline configs (non-secret settings only). The config file is TOML format (golem.toml).

File locations searched (in order):

1. Path specified via --config CLI flag
2. golem.toml in the current directory
3. ~/.bardo/golem.toml

Full example

# golem.toml -- complete configuration reference

[tools]
profile = "trader"
enable = ["intel_compute_vpin"]
disable = ["uniswap_submit_uniswapx_order"]

[chains]
enabled = [1, 8453, 42161]

[chains.rpc_overrides]
1 = "https://my-rpc.example.com"

[custody]
# One of: "delegation", "embedded", "local_key"
mode = "delegation"

[custody.delegation]
smart_account = "0x..."
caveat_enforcers = ["GolemPhase", "MortalityTimeWindow", "DailySpendLimit"]

[custody.embedded]
privy_app_id = "..."
server_wallet_id = "..."

[custody.local_key]
private_key_path = ".bardo/session-key.json"
max_daily_spend_usd = 100.0
expires_days = 30

[safety]
token_allowlist_mode = "strict"
token_allowlist_source = "uniswap-default"

[safety.capability_limits]
max_value_per_tx_usd = 10000
max_value_per_day_usd = 100000
expiry_ticks = 3

[safety.slippage]
max_slippage_bps = 100
max_price_impact_bps = 300

[safety.rate_limit]
max_operations_per_window = 20
window_seconds = 3600

[safety.simulation]
enabled = true
divergence_tolerance_bps = 200

[trading]
default_deadline_seconds = 300
default_slippage_bps = 50
prefer_trading_api = true
enable_uniswapx = true
enable_cross_chain = true
confirmations = 1

[uniswap_api]
api_key = "your-key"
enable_lp = true
enable_limit_orders = true
enable_smart_wallet = false
universal_router_version = "2.0"
permit2_enabled = true
chain_ids = [1, 8453, 42161, 10, 137]

[a2a]
enabled = false
port = 3000

[logging]
level = "info"
format = "json"

Rust config struct

The config file deserializes into a ToolConfig struct:

#![allow(unused)]
fn main() {
use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct ToolConfig {
    #[serde(default)]
    pub tools: ToolsConfig,
    #[serde(default)]
    pub chains: ChainsConfig,
    #[serde(default)]
    pub custody: CustodyConfig,
    #[serde(default)]
    pub safety: SafetyConfig,
    #[serde(default)]
    pub trading: TradingConfig,
    #[serde(default)]
    pub a2a: A2aConfig,
    #[serde(default)]
    pub logging: LoggingConfig,
}

#[derive(Debug, Deserialize)]
#[serde(tag = "mode")]
pub enum CustodyConfig {
    #[serde(rename = "delegation")]
    Delegation {
        smart_account: String,
        caveat_enforcers: Vec<String>,
    },
    #[serde(rename = "embedded")]
    Embedded {
        privy_app_id: String,
        server_wallet_id: String,
    },
    #[serde(rename = "local_key")]
    LocalKey {
        private_key_path: String,
        max_daily_spend_usd: f64,
        expires_days: u32,
    },
}

#[derive(Debug, Deserialize)]
pub struct SafetyConfig {
    pub token_allowlist_mode: AllowlistMode,
    pub capability_limits: CapabilityLimits,
    pub slippage: SlippageConfig,
    pub rate_limit: RateLimitConfig,
    pub simulation: SimulationConfig,
}

#[derive(Debug, Deserialize)]
pub struct CapabilityLimits {
    /// Max USD value a single Capability<T> token authorizes.
    pub max_value_per_tx_usd: f64,
    /// Max cumulative USD value per day across all capability tokens.
    pub max_value_per_day_usd: f64,
    /// Capability tokens expire after this many heartbeat ticks.
    pub expiry_ticks: u64,
}
}

Configuration loading merges env vars over file values over defaults. The merge follows serde’s #[serde(default)] pattern – env var overrides are applied after deserialization via a merge_env_overrides() pass.

Three-tier API key model

Tiered access control for A2A endpoint connections. Governs what any external agent can do based on key scope.

Key tiers

Key generation

Keys are generated at first boot (if none exist) or via the CLI:

bardo-tools setup

Keys are cryptographically random, 256-bit, base64url-encoded. Total key length including prefix: ~55 characters.

Enforcement middleware

#![allow(unused)]
fn main() {
fn authorize_tool_call(api_key: &str, tool_name: &str) -> bool {
    let tier = get_key_tier(api_key);
    match tier {
        KeyTier::Write => true,
        KeyTier::Feedback => is_read_tool(tool_name) || is_feedback_tool(tool_name),
        KeyTier::Read => is_read_tool(tool_name),
    }
}
}

Rejection response

When a tool call is rejected due to insufficient key tier:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"error\":\"INSUFFICIENT_KEY_TIER\",\"message\":\"Tool 'execute_swap' requires Write key. Current key tier: Read.\",\"requiredTier\":\"write\",\"currentTier\":\"read\"}"
    }
  ]
}

Key rotation

bardo-tools setup --rotate-keys              # Rotate all keys
bardo-tools setup --rotate-keys --grace-period 15  # 15-min grace period
bardo-tools setup --rotate-key read           # Rotate one tier only

Transport security

• HTTPS required for remote connections (non-localhost)
• HTTP allowed for localhost only
• Keys transmitted as Authorization: Bearer headers
• Keys never logged, never in URLs, never in error responses

Data sources

Primary data source matrix

Caching strategy

The caching layer uses moka (a Rust concurrent cache) with per-tier TTL configuration. Circuit breaker logic wraps each external dependency with a 50% error threshold and 30s reset timeout. Fallback returns cached data with staleness indicators.

Error taxonomy

Performance requirements

Throughput: 1 write/s sustained, 5 reads/s sustained. Single-agent use (one wallet, sequential operations). Cold start targets are lower than the TypeScript predecessor because binary startup eliminates JIT warmup.

Dependencies

Core

TypeScript sidecar

Uniswap’s official SDKs (@uniswap/sdk-core, @uniswap/v3-sdk, @uniswap/v4-sdk, @uniswap/universal-router-sdk, @uniswap/permit2-sdk, @uniswap/uniswapx-sdk) are TypeScript-only. A thin Node.js sidecar process exposes SDK math and calldata encoding over local IPC. The sidecar is started lazily when a tool first needs SDK computation. Tools that only do RPC reads or subgraph queries never start the sidecar.

Runtime

• Target: x86_64-unknown-linux-gnu, aarch64-apple-darwin
• Rust edition: 2024
• MSRV: 1.80
• No external services required for basic operation (all data from RPC + subgraph)
• Optional: Uniswap Trading API key, The Graph API key, TypeScript sidecar (for SDK-dependent tools)