AgentTrust Docs

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-sdk
agentrust init

Step-by-Step Guide

1. Initialize

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

2. File locations (resolution order)

AGENTRUST_KEY env var (highest priority)
.agentrust/config.yaml in project directory
~/.agentrust/config.yaml (user home)

3. Typical structure

# ~/.agentrust/config.yaml (example — actual fields may vary)
api_key: at_team_xxxxxxxx
gateway_url: http://localhost:8000
tier: team
org_id: org_xxxxxxxx
created_at: "2026-01-15T10:00:00Z"

4. Save key programmatically

from agentrust_sdk import save_key_to_config
save_key_to_config("at_team_your_key", gateway_url="http://localhost:8000")

5. Resolve key programmatically

from agentrust_sdk import resolve_key
key = resolve_key()  # env → project config → home config

6. CLI management

agentrust whoami     # show identity from config
agentrust status     # tier + gateway reachability
agentrust uninstall  # remove config files

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 status after changing gateway URL
Use agentrust init --local for air-gapped environments

Common Mistakes

Committing ~/.agentrust/config.yaml with production keys
Expecting config file to override env vars (env always wins)
Using config file without running agentrust init first

Troubleshooting

Issue	Fix
Key not found	Run `agentrust init` or set `AGENTRUST_KEY`
Wrong gateway	Edit config or set `AGENTRUST_GATEWAY_URL`
Stale tier info	Run `agentrust whoami` to refresh

Config File