Configuration Guide

Configuration Guide

Aden Hive is a Python-based agent framework. Configuration is handled through environment variables and agent-level config files. There is no centralized config.yaml or Docker Compose setup.

Configuration Overview

~/.hive/configuration.json  (global defaults: provider, model, max_tokens)
Environment variables        (API keys, runtime flags)
Agent config.py              (per-agent settings: model, tools, storage)
pyproject.toml               (package metadata and dependencies)
.mcp.json                    (MCP server connections)

Global Configuration (~/.hive/configuration.json)

The quickstart.sh script creates this file during setup. It stores the default LLM provider, model, and max_tokens used by all agents unless overridden in an agent's own config.py.

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 8192,
    "api_key_env_var": "ANTHROPIC_API_KEY"
  },
  "created_at": "2026-01-15T12:00:00+00:00"
}

The default max_tokens value (8192) is defined as DEFAULT_MAX_TOKENS in framework.graph.edge and re-exported from framework.graph. Each agent's RuntimeConfig reads from this file at startup. To change defaults, either re-run quickstart.sh or edit the file directly.

Environment Variables

LLM Providers (at least one required for real execution)

# Anthropic (primary provider)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI (optional, for GPT models via LiteLLM)
export OPENAI_API_KEY="sk-..."

# Cerebras (optional, used by output cleaner and some nodes)
export CEREBRAS_API_KEY="..."

# Groq (optional, fast inference)
export GROQ_API_KEY="..."

The framework supports 100+ LLM providers through LiteLLM. Set the corresponding environment variable for your provider.

Search & Tools (optional)

# Web search for agents (Brave Search)
export BRAVE_SEARCH_API_KEY="..."

# Exa Search (alternative web search)
export EXA_API_KEY="..."

Runtime Flags

# Run agents without LLM calls (structure-only validation)
export MOCK_MODE=1

# Fernet encryption key for credential store at ~/.hive/credentials
export HIVE_CREDENTIAL_KEY="your-fernet-key"

# Custom agent storage path (default: /tmp)
export AGENT_STORAGE_PATH="/custom/storage"

Agent Configuration

Each agent package in exports/ contains its own config.py:

# exports/my_agent/config.py
CONFIG = {
    "model": "anthropic/claude-sonnet-4-5-20250929",  # Default LLM model
    "max_tokens": 8192,  # default: DEFAULT_MAX_TOKENS from framework.graph
    "temperature": 0.7,
    "tools": ["web_search", "pdf_read"],   # MCP tools to enable
    "storage_path": "/tmp/my_agent",       # Runtime data location
}

If model or max_tokens are omitted, the agent loads defaults from ~/.hive/configuration.json.

Agent Graph Specification

Agent behavior is defined in agent.json (or constructed in agent.py):

{
  "id": "my_agent",
  "name": "My Agent",
  "goal": {
    "success_criteria": [...],
    "constraints": [...]
  },
  "nodes": [...],
  "edges": [...]
}

See the Getting Started Guide for building agents.

MCP Server Configuration

MCP (Model Context Protocol) servers are configured in .mcp.json at the project root:

{
  "mcpServers": {
    "agent-builder": {
      "command": "uv",
      "args": ["run", "-m", "framework.mcp.agent_builder_server"],
      "cwd": "core"
    },
    "tools": {
      "command": "uv",
      "args": ["run", "mcp_server.py", "--stdio"],
      "cwd": "tools"
    }
  }
}

The tools MCP server exposes tools including web search, PDF reading, CSV processing, and file system operations.

Storage

Aden Hive uses file-based persistence (no database required):

{storage_path}/
  runs/{run_id}.json          # Complete execution traces
  indexes/
    by_goal/{goal_id}.json    # Runs indexed by goal
    by_status/{status}.json   # Runs indexed by status
    by_node/{node_id}.json    # Runs indexed by node
  summaries/{run_id}.json     # Quick-load run summaries

Storage is managed by framework.storage.FileStorage. No external database setup is needed.

IDE Setup

VS Code

Add to .vscode/settings.json:

{
  "python.analysis.extraPaths": [
    "${workspaceFolder}/core",
    "${workspaceFolder}/exports"
  ]
}

PyCharm

1. Open Project Settings > Project Structure
2. Mark core as Sources Root
3. Mark exports as Sources Root

Security Best Practices

1. Never commit API keys - Use environment variables or .env files
2. .env is git-ignored - Copy .env.example to .env at the project root and fill in your values
3. Use real provider keys in non-production environments - validate configuration with low-risk inputs before production rollout
4. Credential isolation - Each tool validates its own credentials at runtime

Troubleshooting

"ModuleNotFoundError: No module named 'framework'"

Install the core package:

cd core && uv pip install -e .

API key not found

Ensure the environment variable is set in your current shell session:

echo $ANTHROPIC_API_KEY  # Should print your key

On Windows PowerShell:

$env:ANTHROPIC_API_KEY = "sk-ant-..."

Agent not found

Run from the project root with PYTHONPATH:

PYTHONPATH=exports uv run python -m my_agent validate

See Environment Setup for detailed installation instructions.