Config File

Overview

The agentrust CLI creates a YAML config file at ~/.agentrust/config.yaml (or project-level .agentrust/config.yaml). It stores your API key, gateway URL, and onboarding metadata. Environment variables always override file values.

Why It Matters

The config file persists credentials across sessions so you don't re-export AGENTRUST_KEY in every terminal.

Prerequisites

pip install agentrust-py
agentrust init

Step-by-Step Guide

1. Initialize

agentrust init           # cloud auth flow
agentrust init --local   # offline/air-gap key generation

2. Resolution order

1. A key passed explicitly to AgentTrustClient(api_key=...) or @harness(api_key=...)
2. The AGENTRUST_KEY environment variable
3. .agentrust/config.yaml — searched from the current directory upwards through every parent
4. ~/.agentrust/config.yaml (user home)

No key at any level → OSS tier, schema validation only.

3. Typical structure

agentrust init writes exactly three keys. tier and org_id are decoded from the API key JWT and stored only so the file is readable by humans — the SDK re-decodes the key on every run rather than trusting them.

# ~/.agentrust/config.yaml — written by `agentrust init` (mode 0600)
api_key: at_team_xxxxxxxx
tier: team
org_id: org_xxxxxxxx

You may add control_plane_url by hand. It is the only gateway-URL key the SDK reads from this file, and it applies only when AGENTRUST_GATEWAY_URL is unset:

control_plane_url: https://agentrust.internal:8000

4. Save key programmatically

from agentrust_sdk import save_key_to_config

save_key_to_config("at_team_your_key")                   # ~/.agentrust/config.yaml
save_key_to_config("at_team_your_key", scope="project")  # ./.agentrust/config.yaml

The signature is save_key_to_config(api_key, scope="global") — there is no gateway_url argument. The file is written with mode 0600.

5. Resolve key programmatically

resolve_key() returns a KeyInfo object, not a string. It never raises — with no key found it falls back to the OSS tier.

from agentrust_sdk import resolve_key

info = resolve_key()          # explicit → env → project config → global config
print(info.key)               # the raw key, or None
print(info.tier.value)        # "oss" | "free" | "developer" | "team" | "enterprise"
print(info.org_id)            # decoded from the JWT `sub` claim
print(info.source)            # "env" | "project_config" | "global_config" | "explicit" | "none"

6. CLI management

agentrust whoami     # identity, tier, and capability matrix
agentrust status     # config file locations and resolved tier (does not call the gateway)

To remove stored credentials, delete the file — agentrust uninstall purges local databases and gateway records but leaves config.yaml in place:

rm ~/.agentrust/config.yaml

Examples

Project-level config for team repos:

my-agent-project/
├── .agentrust/
│   └── config.yaml    # shared gateway URL (not API key in git!)
├── agent.py
└── .gitignore         # add .agentrust/config.yaml if it contains secrets

Best Practices

• Never commit API keys to version control
• Use env vars in CI/CD; use config file for local dev
• Run agentrust whoami after changing keys to confirm the resolved tier
• Use agentrust init --local for air-gapped environments

Common Mistakes

• Committing ~/.agentrust/config.yaml with production keys
• Expecting the config file to override env vars — AGENTRUST_KEY always wins
• Expecting a gateway_url: key to be read — the key the SDK reads is control_plane_url
• Using config file without running agentrust init first

Troubleshooting

Related Resources

• Environment Variables
• CLI Reference
• Python Quickstart