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

> Configure your Heurist agent successfully. Discover the essential environment variables like HEURIST_API_KEY, LARGE_MODEL_ID, and DYNAMODB_TABLE_NAME for optimal performance and production deployment.

- Repository: [Heurist/heurist-agent-framework](https://github.com/heurist-network/heurist-agent-framework)
- Tags: getting-started
- Published: 2026-03-03

---

**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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/mesh/mesh_agent.py) during agent initialization and in [`interfaces/twitter_reply.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/interfaces/twitter_reply.py) and [`interfaces/farcaster_reply.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/mesh/agents/wan_video_gen_agent.py)) upload assets to Cloudflare R2. The uploader utility in [`mesh/utils/r2_image_uploader.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/mesh/agents/firecrawl_search_agent.py) web scraping.
- **`EXA_API_KEY`** – For [`mesh/agents/exa_search_agent.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/mesh/agents/exa_search_agent.py) search services.
- **`COINGECKO_API_KEY`** – For [`mesh/cron/fetch_coingecko_binance_tokens.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/mesh/cron/fetch_coingecko_binance_tokens.py) market data.
- **`UNIFAI_API_KEY`** – For [`mesh/agents/unifai_token_analysis_agent.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/mesh/agents/unifai_token_analysis_agent.py) AI services.
- **`APIDANCE_API_KEY`** – For [`mesh/agents/twitter_info_agent.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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

```python
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

```bash

# 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

```python
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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/mesh/mesh_api.py) for usage tracking or rate limiting. A minimal agent running locally with [`mesh/mesh_agent.py`](https://github.com/heurist-network/heurist-agent-framework/blob/main/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`](https://github.com/heurist-network/heurist-agent-framework/blob/main/mesh/utils/proxy_client.py) to route all outbound HTTP traffic through your proxy infrastructure.