Skip to main content
Autonome uses T3Env with Zod validation to provide type-safe environment variable access. All configuration is defined in src/env.ts and validated at startup.
Never commit real API keys or secrets to version control. Use .env.local for local development and secure environment variable management in production.

​
Setup

Copy the example environment file and fill in your values: 
cp .env.example .env
Edit .env with your configuration. The application will automatically load .env and .env.local files on startup.

​
Using Environment Variables

Never access process.env directly. Always import from src/env.ts to ensure type safety and validation.
Correct Usage: 
import { env, TRADING_MODE, IS_SIMULATION_ENABLED } from "@/env";

// Access validated environment variables
const dbUrl = env.DATABASE_URL;
const port = env.PORT;
const isSimulated = IS_SIMULATION_ENABLED;
Incorrect Usage: 
// ❌ Don't do this - no validation or type safety
const dbUrl = process.env.DATABASE_URL;

​
Server Configuration

Variables for backend API server configuration.
​
PORT
number
default:"8081"
Port number for the backend API server. The frontend will proxy /api/* requests to this port during development.
​
SERVER_URL
string (URL)
Public server origin URL. Used for callbacks and external integrations.Example: https://autonome.app
​
API_URL
string (URL)
default:"http://localhost:8081"
Internal API base URL used by the server for self-referencing endpoints.
​
CORS_ORIGINS
string
Comma-separated list of allowed frontend origins for CORS. No trailing slashes.Example: https://autonome.app,https://autonome.vercel.app

​
Database

​
DATABASE_URL
string (URL)
PostgreSQL connection string. Required for backend operation but optional for frontend-only deployments on Vercel.Format: postgres://user:password@localhost:5432/autonome
The database URL contains sensitive credentials. Never expose this in client-side code or commit it to version control.

​
Trading Configuration

Controls trading mode and simulator behavior. See Trading Mode for detailed information.
​
TRADING_MODE
enum
default:"simulated"
Trading execution mode. Controls whether orders are sent to the real exchange or simulated locally.Values:
  • simulated - Use local simulator (safe for testing)
  • live - Execute real trades via Lighter API
​
SIM_INITIAL_CAPITAL
number
default:"10000"
Starting capital for the trading simulator in quote currency (USDT).
​
SIM_QUOTE_CURRENCY
string
default:"USDT"
Quote currency for simulator positions and P&L calculations.
​
SIM_REFRESH_INTERVAL_MS
number
default:"10000"
Interval in milliseconds for simulator to refresh market data and recalculate positions.

​
Lighter API

Configuration for zkLighter exchange integration (required for live trading).
​
LIGHTER_API_KEY_INDEX
number
default:"2"
Credential slot index in your zkLighter account. Each account can have multiple API key indexes.
​
LIGHTER_BASE_URL
string (URL)
default:"https://mainnet.zklighter.elliot.ai"
Base URL for the Lighter REST API endpoint.
Lighter API credentials provide access to your exchange account. Keep your LIGHTER_API_KEY_INDEX secure and never share it publicly.

​
AI Provider Keys

Autonome supports multiple AI providers with automatic key rotation for rate limit management.

​
NVIDIA NIM

​
NIM_API_KEY
string
Primary NVIDIA NIM API key for SQL query planning and data analysis.
​
NIM_API_KEY1
string
Additional NIM API key for round-robin rotation.
​
NIM_API_KEY2
string
Additional NIM API key for round-robin rotation.
​
NIM_API_KEY3
string
Additional NIM API key for round-robin rotation.

​
OpenRouter

​
OPENROUTER_API_KEY
string
Primary OpenRouter API key for accessing various AI models through a unified API.
​
OPENROUTER_API_KEY1
string
Additional OpenRouter API key for round-robin rotation.

​
AIHubMix

​
AIHUBMIX_API_KEY
string
Primary AIHubMix API key.
​
AIHUBMIX_API_KEY1
string
Additional AIHubMix API key for round-robin rotation.
​
AIHUBMIX_API_KEY2
string
Additional AIHubMix API key for round-robin rotation.
​
AIHUBMIX_API_KEY3
string
Additional AIHubMix API key for round-robin rotation.
​
AIHUBMIX_API_KEY4
string
Additional AIHubMix API key for round-robin rotation.
​
AIHUBMIX_API_KEY5
string
Additional AIHubMix API key for round-robin rotation.

​
Mistral AI

​
MISTRAL_API_KEY
string
Mistral AI API key for additional AI model access.

​
API Key Rotation

The system automatically rotates through multiple API keys using round-robin cycling to avoid rate limits: 
import { 
  getNextNimApiKey, 
  getNimApiKeyCount,
  getNextOpenRouterApiKey,
  getNextAihubmixApiKey 
} from "@/env";

// Get next available key (automatically rotates)
const apiKey = getNextNimApiKey();

// Check how many keys are configured
const keyCount = getNimApiKeyCount();
The rotator will throw an error if no keys are configured for a provider when you attempt to get the next key.

​
Technical Indicators

​
TAAPI_API_KEY
string
TAAPI.io API key for supplementary technical indicator calculations.

​
Frontend Variables

Client-side environment variables that are exposed to the browser. These must be prefixed with VITE_.
​
VITE_APP_TITLE
string
Optional application title override for the UI.
​
VITE_API_URL
string (URL)
API base URL accessible from the browser. Required for production deployments where frontend and backend are on different domains.Development: Leave empty to use Vite’s proxy (/api/* → http://localhost:8081)Production: Set to your backend API URL (e.g., https://api.autonome.app)
Only VITE_ prefixed variables are exposed to the browser. Never put sensitive API keys in VITE_ variables.

​
T3Env Configuration

Autonome uses T3Env’s emptyStringAsUndefined option, which means:
  • Empty strings in .env are treated as undefined
  • Default values will be applied for empty strings
  • Type validation happens after empty string handling
Example: 
# .env file
PORT=           # Treated as undefined, defaults to 8081
TRADING_MODE=   # Treated as undefined, defaults to "simulated"

​
Validation

All environment variables are validated using Zod schemas at application startup. Invalid configurations will cause the application to fail fast with detailed error messages. Validation Features:
  • Type coercion (e.g., PORT string → number)
  • URL format validation
  • Enum validation for TRADING_MODE
  • Required vs. optional field enforcement
  • Default value application
To validate your environment configuration without starting the full application: 
bun run scripts/validate-env.ts

​
Environment File Loading

The application loads environment files in this order:
  1. .env - Base configuration (committed to repo as .env.example)
  2. .env.local - Local overrides (gitignored, for development)
Later files override earlier ones. This allows you to:
  • Keep shared defaults in .env.example
  • Use .env.local for personal API keys and local settings
  • Override everything in production with platform environment variables

​
Best Practices

Do:
  • Use .env.local for local development secrets
  • Always import from src/env.ts for type safety
  • Use the provided key rotation functions for AI APIs
  • Validate environment on deployment with scripts/validate-env.ts
  • Set appropriate CORS origins in production
Don’t:
  • Never commit .env.local or .env with real secrets
  • Don’t access process.env directly
  • Don’t put sensitive keys in VITE_ prefixed variables
  • Don’t skip validation by using optional types for required fields

Build docs developers (and LLMs) love

Get started for freeTalk to us