Three-layer configuration system -- global API keys, per-agent credentials, and agent YAML files.

Configuration

Supyagent uses a three-layer configuration system that separates concerns between global settings, per-agent secrets, and agent behavior.

Configuration Layers

Layer	Location	Encrypted	Scope
Global config	`~/.supyagent/config/`	Yes (Fernet)	All agents on the machine
Per-agent credentials	`.supyagent/credentials/{agent}.enc`	Yes (Fernet)	Single agent in the workspace
Agent YAML	`agents/{name}.yaml`	No	Agent behavior and settings

Layer 1: Global Config (`~/.supyagent/config/`)

Stores API keys and global settings encrypted with Fernet. These are loaded into environment variables at agent startup, making them available to LiteLLM and other libraries.

# Interactive key selection menu
supyagent config set

# Set a specific key (prompts for value)
supyagent config set ANTHROPIC_API_KEY

# Set with value directly (visible in shell history -- use with caution)
supyagent config set MY_KEY --value "sk-..."

# List all stored keys
supyagent config list

# Delete a key
supyagent config delete ANTHROPIC_API_KEY

# Import from .env file
supyagent config import .env
supyagent config import secrets.env --filter OPENAI   # Only keys matching prefix

# Export to .env file (with 0600 permissions)
supyagent config export backup.env
supyagent config export backup.env --force   # Overwrite existing

The config set command without arguments presents an interactive menu of common API keys:

Select an API key to configure:
  1. ANTHROPIC_API_KEY
  2. OPENAI_API_KEY
  3. OPENROUTER_API_KEY
  4. GOOGLE_API_KEY
  5. Other (enter name)

Layer 2: Per-Agent Credentials (`.supyagent/credentials/`)

Each agent can have its own encrypted credential store. These are workspace-local and loaded only for that agent.

Credentials can be declared in the agent YAML:

credentials:
  - name: GITHUB_TOKEN
    description: "GitHub personal access token"
    required: true
  - name: SLACK_WEBHOOK
    description: "Slack webhook URL"
    required: false

At runtime, declared credentials are checked. If a required credential is missing, the agent can prompt the user via the built-in request_credential tool.

Manage credentials in chat:

/creds list              # Show stored credentials
/creds set GITHUB_TOKEN  # Set a credential
/creds delete MY_SECRET  # Remove a credential

Layer 3: Agent YAML (`agents/`)

Agent configuration files define behavior, model settings, tool permissions, and all the advanced features. These files are not encrypted and should be committed to version control (they contain no secrets).

agents/myagent.yaml

name: myagent
description: An AI assistant
version: "1.0"
type: interactive          # interactive | execution | daemon

model:
  provider: anthropic/claude-sonnet-4-5-20250929
  temperature: 0.7
  max_tokens: 4096
  max_retries: 3
  retry_delay: 1.0
  retry_backoff: 2.0
  fallback:
    - openrouter/google/gemini-2.5-flash
  cache: true

system_prompt: |
  You are a helpful AI assistant.

tools:
  allow: ["*"]
  deny: []

delegates:
  - planner
  - coder

credentials:
  - name: API_KEY
    description: "External API key"
    required: false

will_create_tools: true

context:
  auto_summarize: true
  max_messages_before_summary: 30
  max_tokens_before_summary: 128000
  min_recent_messages: 6
  response_reserve: 4096

supervisor:
  default_timeout: 60
  on_timeout: background
  max_background_processes: 10

delegation:
  share_credentials: true
  share_summary: true
  default_mode: subprocess
  default_timeout: 300

memory:
  enabled: true
  extraction_threshold: 5
  retrieval_limit: 10
  auto_extract: true

sandbox:
  enabled: false
  image: python:3.12-slim
  runtime: auto
  network: bridge
  memory_limit: 2g

service:
  enabled: true
  url: https://app.supyagent.com

schedule:
  interval: 5m
  max_events_per_cycle: 10
  prompt: null

workspace: null

limits:
  max_tool_calls_per_turn: 100
  circuit_breaker_threshold: 3

Environment Variable Fallback

When a key is not found in the encrypted config, supyagent falls back to environment variables. This means you can use standard env vars in CI/CD or Docker environments:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
supyagent chat myagent

The lookup order is:

Encrypted global config (~/.supyagent/config/)
Environment variables
Per-agent credentials (.supyagent/credentials/)
Runtime prompting (via request_credential tool)

Config Schema Reference

Use supyagent schema to see the full configuration schema with all fields, types, defaults, and descriptions:

supyagent schema

This outputs every available YAML field organized by section (top-level, model, tools, context, supervisor, limits).

Validation

Use supyagent validate to check an agent configuration:

supyagent validate myagent

This performs:

YAML parsing -- Checks syntax and required fields
Pydantic validation -- Type checking, value ranges, enum constraints
Deep validation -- Model provider recognition, delegate existence, tool pattern validity
Tool discovery -- Counts available local and service tools
Service connectivity -- Checks if the cloud service is reachable (if enabled)

Common Configuration Patterns

Minimal Agent

name: simple
model:
  provider: anthropic/claude-sonnet-4-5-20250929
system_prompt: |
  You are a helpful assistant.
tools:
  allow: ["*"]

High-Temperature Creative Agent

name: writer
model:
  provider: anthropic/claude-sonnet-4-5-20250929
  temperature: 1.2
  max_tokens: 8192
system_prompt: |
  You are a creative writing assistant.
tools:
  allow: []   # No tools needed

Multi-Provider Failover

name: resilient
model:
  provider: anthropic/claude-sonnet-4-5-20250929
  fallback:
    - openai/gpt-4o
    - openrouter/google/gemini-2.5-flash
  max_retries: 3
  retry_delay: 1.0
  retry_backoff: 2.0
system_prompt: |
  You are a reliable assistant.

Restricted Tool Access

name: readonly
model:
  provider: anthropic/claude-sonnet-4-5-20250929
system_prompt: |
  You can read and search files but cannot modify them.
tools:
  allow:
    - "files__read_*"
    - "search__*"
    - "find__*"
  deny:
    - "files__write_*"
    - "shell__*"
    - "edit__*"

Security -- Encryption details and sandbox configuration
Context Management -- Context window settings
Process Management -- Supervisor configuration
CLI Reference -- Config CLI commands

Configuration

On this page