Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration Reference

Koyal is configured via environment variables and a .env file in the working directory. All variables are optional — only configure the providers and chains you use.

Core

VariableDefaultDescription
KOYAL_DATA_DIR./trading_agentsRoot directory for agent vaults
KOYAL_LOG_LEVELinfoLog level: trace, debug, info, warn, error
KOYAL_GATEWAY_HOST127.0.0.1Gateway bind address
KOYAL_GATEWAY_PORT8790Gateway bind port

AI Providers

VariableDescription
AI_GATEWAYActive provider ID: openai, anthropic, gemini, deepseek, groq, openrouter, etc.
AI_MODELModel name for the active provider
OPENAI_API_KEYOpenAI API key
ANTHROPIC_API_KEYAnthropic API key
GEMINI_API_KEYGoogle Gemini API key
GROQ_API_KEYGroq API key
TOGETHER_API_KEYTogether AI API key
OPENROUTER_API_KEYOpenRouter API key
DEEPSEEK_API_KEYDeepSeek API key
MISTRAL_API_KEYMistral API key
PERPLEXITY_API_KEYPerplexity API key
XAI_API_KEYxAI Grok API key
FIREWORKS_API_KEYFireworks AI API key
COHERE_API_KEYCohere API key
REPLICATE_API_TOKENReplicate API token
HUGGINGFACE_API_KEYHuggingFace Inference API key

AWS Bedrock

VariableDescription
AWS_ACCESS_KEY_IDAWS access key
AWS_SECRET_ACCESS_KEYAWS secret key
AWS_REGIONAWS region (default: us-east-1)
AWS_SESSION_TOKENOptional session token for temporary credentials

Solana

VariableDefaultDescription
SOLANA_RPC_URLMainnet public RPCSolana RPC endpoint
SOLANA_KEYPAIR_PATH—Path to keypair JSON file (Ed25519)
SOLANA_COMMITMENTconfirmedCommitment level: processed, confirmed, finalized

EVM

VariableDescription
ETH_RPC_URLEthereum mainnet RPC URL
ARBITRUM_RPC_URLArbitrum RPC URL
BASE_RPC_URLBase RPC URL
POLYGON_RPC_URLPolygon RPC URL
ETH_PRIVATE_KEYEVM private key (hex, 0x-prefixed)

Hyperliquid

VariableDefaultDescription
HYPERLIQUID_USE_TESTNETfalseUse testnet instead of mainnet
HYPERLIQUID_PRIVATE_KEY—Wallet private key for signing

Telegram

VariableDescription
TELEGRAM_BOT_TOKENBot token from @BotFather

Example .env

AI_GATEWAY=anthropic
AI_MODEL=claude-sonnet-4-6
ANTHROPIC_API_KEY=sk-ant-...

SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_KEYPAIR_PATH=/home/user/.config/solana/id.json

KOYAL_GATEWAY_PORT=8790
KOYAL_LOG_LEVEL=info

Runtime Settings

Some settings can be changed at runtime without restart via koyal settings or PATCH /api/settings:

KeyDescription
ai.gatewayOverride active AI provider
ai.modelOverride active model
halt.enabledGlobal halt state
halt.reasonHalt reason string
 
koyal settings set ai.gateway openai
koyal settings set ai.model gpt-4o