Essential Environment Variables for Running the Heurist Agent: Complete Configuration Guide

To run a Heurist agent, you must set HEURIST_API_KEY, HEURIST_BASE_URL, LARGE_MODEL_ID, and SMALL_MODEL_ID; production deployments additionally require AWS/DynamoDB credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, DYNAMODB_TABLE_NAME) and Cloudflare R2 storage variables (R2_ENDPOINT, R2_ACCESS_KEY, R2_SECRET_KEY).

The heurist-network/heurist-agent-framework provides a modular Mesh architecture for building AI agents. Before any agent can execute, the framework validates a specific set of environment variables that control authentication, model selection, persistence, and third-party service integration. This guide maps every essential variable to its source file and functional purpose.

Core Heurist Configuration Variables

The framework bootstrap process, implemented in mesh/mesh_agent.py, clears the inherited environment and immediately reads four critical variables. These form the minimal viable configuration for any Heurist deployment.

• HEURIST_API_KEY – Authenticates every request to the Heurist API. This key is used by the Mesh manager, individual agents, and the public MCP client.
• HEURIST_BASE_URL – The root endpoint for the Heurist API (e.g., https://api.heurist.network).
• LARGE_MODEL_ID – Identifier for the large LLM used for complex reasoning tasks.
• SMALL_MODEL_ID – Identifier for the small LLM used for cost-effective, high-speed inference.

These variables are referenced in mesh/mesh_agent.py during agent initialization and in interfaces/twitter_reply.py and interfaces/farcaster_reply.py for front-end integrations.

Storage and Persistence Variables

Production-grade agents require persistent storage for usage tracking, rate limiting, and media assets. The framework splits persistence across AWS DynamoDB and Cloudflare R2.

AWS and DynamoDB Configuration

The Mesh API handler in mesh/mesh_api.py expects the following variables to establish DynamoDB connections for logging and token-bucket rate limiting:

• AWS_ACCESS_KEY_ID – AWS credential for DynamoDB and S3/R2 clients.
• AWS_SECRET_ACCESS_KEY – Companion secret for AWS authentication.
• AWS_REGION – Region identifier for DynamoDB and S3 resources.
• DYNAMODB_TABLE_NAME – Name of the table storing usage tracking and token-bucket data.

Cloudflare R2 Object Storage

Agents that generate or manipulate media (e.g., mesh/agents/wan_video_gen_agent.py) upload assets to Cloudflare R2. The uploader utility in mesh/utils/r2_image_uploader.py requires:

• R2_ENDPOINT – URL endpoint for the R2 bucket (e.g., https://<account>.r2.cloudflarestorage.com).
• R2_ACCESS_KEY – Access key for R2 authentication.
• R2_SECRET_KEY – Secret key for R2 authentication.

Optional LLM and Proxy Configuration

Alternative LLM Providers

While Heurist provides default LLM routing, agents can request alternative providers. In mesh/mesh_agent.py, the framework checks for:

• GEMINI_API_KEY – API key for Google Gemini, used when an agent explicitly requests Gemini instead of the default LLM.

Network Proxy Settings

For production deployments requiring traffic routing through proxy servers, mesh/utils/proxy_client.py reads:

• PROXY_ENABLED – Boolean flag (true/false) enabling the internal mesh proxy layer.
• MESH_PROXY_URLS or PROXY_SERVERS – Comma-separated list of proxy server URLs.
• PROTOCOL_V2_API_KEY – API key for the V2 mesh protocol used by the proxy.
• PROXY_TIMEOUT – Timeout in seconds for proxy calls.

Agent-Specific Third-Party API Keys

The modular architecture loads third-party credentials only when specific agents are instantiated. Each agent class stores its key in an instance attribute at __init__ time (e.g., self.api_key = os.getenv("FIRECRAWL_API_KEY")). Missing keys raise exceptions only when the agent attempts an external API call.

Common agent-specific variables include:

• FIRECRAWL_API_KEY – For mesh/agents/firecrawl_search_agent.py web scraping.
• EXA_API_KEY – For mesh/agents/exa_search_agent.py search services.
• COINGECKO_API_KEY – For mesh/cron/fetch_coingecko_binance_tokens.py market data.
• UNIFAI_API_KEY – For mesh/agents/unifai_token_analysis_agent.py AI services.
• APIDANCE_API_KEY – For mesh/agents/twitter_info_agent.py social media APIs.
• BITQUERY_API_KEY, TOKENMETRICS_API_KEY, HELIUS_API_KEY, etc. – Additional specialized data providers.

Configuration Examples

Minimal Local Deployment

import os
from mesh.mesh_agent import MeshAgent

# Essential variables only

os.environ.update({
    "HEURIST_API_KEY": "sk-your-heurist-key",
    "HEURIST_BASE_URL": "https://api.heurist.network",
    "LARGE_MODEL_ID": "gpt-4o",
    "SMALL_MODEL_ID": "gpt-4o-mini",
})

agent = MeshAgent()
print("Mesh initialized:", agent.version)

Production Deployment with Persistence and Storage

# Core Heurist

export HEURIST_API_KEY="sk-your-heurist-key"
export HEURIST_BASE_URL="https://api.heurist.network"
export LARGE_MODEL_ID="gpt-4o"
export SMALL_MODEL_ID="gpt-4o-mini"

# AWS DynamoDB for persistence

export AWS_ACCESS_KEY_ID="your-aws-key"
export AWS_SECRET_ACCESS_KEY="your-aws-secret"
export AWS_REGION="us-east-1"
export DYNAMODB_TABLE_NAME="heurist-usage-tracking"

# Cloudflare R2 for media storage

export R2_ENDPOINT="https://<account>.r2.cloudflarestorage.com"
export R2_ACCESS_KEY="r2-access-key"
export R2_SECRET_KEY="r2-secret-key"

# Optional proxy

export PROXY_ENABLED="true"
export MESH_PROXY_URLS="http://proxy1.example.com,http://proxy2.example.com"
export PROTOCOL_V2_API_KEY="proxy-api-key"

Running a Specific Third-Party Agent

import os
from mesh.agents.firecrawl_search_agent import FirecrawlSearchAgent

# Agent-specific key

os.environ["FIRECRAWL_API_KEY"] = "fc-your-key"

agent = FirecrawlSearchAgent()
result = agent.search("latest AI research")
print(result)

Summary

• Core variables (HEURIST_API_KEY, HEURIST_BASE_URL, LARGE_MODEL_ID, SMALL_MODEL_ID) are mandatory for all deployments and are validated at bootstrap in mesh/mesh_agent.py.
• Persistence variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, DYNAMODB_TABLE_NAME) enable usage tracking and rate limiting via mesh/mesh_api.py.
• Storage variables (R2_ENDPOINT, R2_ACCESS_KEY, R2_SECRET_KEY) are required for media-heavy agents using mesh/utils/r2_image_uploader.py.
• Proxy variables (PROXY_ENABLED, MESH_PROXY_URLS, PROTOCOL_V2_API_KEY) configure the optional network proxy layer in mesh/utils/proxy_client.py.
• Agent-specific keys (e.g., FIRECRAWL_API_KEY, EXA_API_KEY) are loaded on-demand by individual agents in mesh/agents/*_agent.py.

Frequently Asked Questions

What happens if I forget to set HEURIST_API_KEY?

The framework will raise an authentication error during initialization. In mesh/mesh_agent.py, the bootstrap process attempts to read HEURIST_API_KEY immediately after clearing the environment; if the variable is missing or empty, subsequent API calls to the Heurist mesh will fail with a 401 Unauthorized response.

Do I need AWS credentials if I'm only running a simple text-based agent?

No. The AWS and DynamoDB variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, DYNAMODB_TABLE_NAME) are only required if your deployment uses the persistence layer in mesh/mesh_api.py for usage tracking or rate limiting. A minimal agent running locally with mesh/mesh_agent.py does not require these credentials.

How do I configure the proxy layer for production traffic?

Set PROXY_ENABLED to true and provide a comma-separated list of proxy URLs in MESH_PROXY_URLS (or the legacy PROXY_SERVERS). You must also supply PROTOCOL_V2_API_KEY for proxy authentication and optionally PROXY_TIMEOUT to control call timeouts. These variables are consumed by mesh/utils/proxy_client.py to route all outbound HTTP traffic through your proxy infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}