Skip to main content

​
Overview

Beacon supports extensive configuration through environment variables and runtime parameters. This guide covers all available configuration options for both CLI and server deployments.

​
Environment Variables

​
AI Provider Configuration

Beacon supports multiple AI providers for inferring repository capabilities. Configure your preferred provider using these variables: 
GEMINI_API_KEY=your_gemini_api_key_here
The default provider is Gemini (gemini-2.5-flash). You can override this with the --provider flag or provider field in API requests.

​
Database Configuration

Beacon uses Supabase (PostgreSQL) for tracking runs and payments when using Beacon Cloud: 
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your_service_role_key
The SUPABASE_SERVICE_KEY should be the service role key, not the anon key. This key has elevated permissions and should be kept secure.

​
Redis Configuration

Redis is required for rate limiting when running the Beacon server: 
REDIS_URL=redis://localhost:6379
# or for Redis Cloud
REDIS_URL=rediss://default:password@your-redis-host:6379
See the Rate Limiting page for more details on Redis-based rate limiting.

​
Payment Configuration

When running Beacon Cloud with payment verification: 
# Payment amount in USDC (default: 0.09)
PAYMENT_AMOUNT_USDC=0.09

# Wallet addresses for receiving payments
BEACON_WALLET_BASE=0x1234567890abcdef1234567890abcdef12345678
BEACON_WALLET_SOLANA=YourSolanaWalletAddressHere123456789

# Blockchain RPC endpoints
BASE_RPC_URL=https://mainnet.base.org
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
Payment verification uses on-chain transaction validation. See Payment Verification for implementation details.

​
Beacon Cloud Endpoint

Override the default Beacon Cloud endpoint: 
BEACON_CLOUD_URL=https://beacon-latest.onrender.com
This is useful for:
  • Self-hosting a Beacon Cloud instance
  • Development and testing
  • Using a custom AI provider endpoint

​
Logging Configuration

Beacon uses tracing for structured logging: 
# Log levels: trace, debug, info, warn, error
RUST_LOG=info

# Module-specific logging
RUST_LOG=beacon=debug,tower_http=warn

​
CLI Configuration

​
Generate Command

beacon generate <target> [OPTIONS]
OptionDescriptionDefault
--output, -oOutput file pathAGENTS.md
--providerAI provider (gemini, claude, openai, beacon-ai-cloud)gemini
--api-keyAPI key for the chosen providerFrom env var
Examples: 
beacon generate ./my-project --output docs/AGENTS.md

​
Validate Command

beacon validate <file> [OPTIONS]
OptionDescriptionDefault
--check-endpointsVerify endpoint reachabilityfalse
--providerUse AI-powered validationnone
Examples: 
# Basic validation
beacon validate AGENTS.md

# With endpoint checking
beacon validate AGENTS.md --check-endpoints

# Cloud validation
beacon validate AGENTS.md --provider beacon-ai-cloud

​
Serve Command

beacon serve [OPTIONS]
OptionDescriptionDefault
--port, -pServer port8080
Example: 
beacon serve --port 3000
The serve command requires REDIS_URL to be configured for rate limiting.

​
Register Command

beacon register [repo_path] [OPTIONS]
OptionDescriptionDefault
--chainBlockchain network (base, solana)base
--agencyAgency identifiernone
Example: 
beacon register ./ --chain base --agency my-agency

​
Configuration File

Beacon automatically loads environment variables from a .env file in the current directory:
.env
# AI Providers
GEMINI_API_KEY=...
CLAUDE_API_KEY=...

# Infrastructure
REDIS_URL=redis://localhost:6379
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=...

# Payment
PAYMENT_AMOUNT_USDC=0.09
BEACON_WALLET_BASE=0x...
BEACON_WALLET_SOLANA=...

# Logging
RUST_LOG=info
Never commit .env files to version control. Add .env to your .gitignore.

​
Docker Configuration

When running Beacon in Docker, pass environment variables via -e flags or an env file: 
# Using individual environment variables
docker run -e GEMINI_API_KEY=your_key \
           -e REDIS_URL=redis://redis:6379 \
           -p 8080:8080 \
           beacon:latest

# Using an env file
docker run --env-file .env \
           -p 8080:8080 \
           beacon:latest

​
Production Checklist

Before deploying Beacon to production:
  • Set appropriate RUST_LOG level (recommend info or warn)
  • Configure Redis with persistence and replication
  • Use managed database services (Supabase, Render Postgres)
  • Set up monitoring for rate limit metrics
  • Rotate API keys regularly
  • Enable TLS for Redis connections (rediss://)
  • Configure proper CORS headers if needed
  • Set resource limits (CPU, memory) in container orchestration
  • Enable request logging and distributed tracing

​
Advanced Tuning

​
Rate Limit Configuration

Rate limits are hardcoded in src/main.rs:36-37:
src/main.rs:36-37
const RATE_LIMIT_WINDOW_SECONDS: u64 = 60;
const RATE_LIMIT_MAX_REQUESTS: usize = 20;
To customize, modify these constants and rebuild. For dynamic configuration, consider using environment variables: 
let rate_limit_max = std::env::var("RATE_LIMIT_MAX")
    .unwrap_or("20".to_string())
    .parse::<usize>()
    .unwrap_or(20);

​
AI Provider Models

The AI models are defined in src/inferrer.rs:
  • Gemini: gemini-2.5-flash (line 19)
  • Claude: claude-sonnet-4-5 (line 97)
  • OpenAI: gpt-4o (line 124)
To use different models, modify the respective functions and rebuild.

​
Payment Amount

The default payment amount is 0.09 USDC. Override with: 
PAYMENT_AMOUNT_USDC=0.05
Payment verification occurs in src/verifier.rs with a tolerance of 0.001 USDC.

​
Next Steps

Payment Verification

Deep dive into blockchain payment verification

Rate Limiting

Redis-based rate limiting implementation

Custom Deployment

Production deployment strategies

Build docs developers (and LLMs) love

Get started for freeTalk to us