Find the variable.
Build the env.

Configures base url.

Configures bot loop cooldown ms.

Breaks ping-pong loops between two bots talking to each other.

Useful when the user switches languages mid-conversation.

Configures expression style.

Configures hf token.

Prevents bot loops — after this many bot replies the bot goes quiet until a human sends a message.

Guards against runaway autonomous messaging.

Favorited memories are always loaded regardless of relevance score.

Configures max response tokens.

Configures max rp crossref.

Configures pgdatabase.

Individual PG connection params (Railway auto-provides these via linked variables — usually not needed)

Configures pghost private.

Configures pgpassword.

Configures pgport.

Configures pguser.

Configures pgusername.

Configures primary db url.

Configures primary user name.

Configures respond to bots.

Configures respond to dms.

Warning: very chatty. Combine with channel whitelisting.

Controls when and how often the bot responds — rate limiting and anti-spam.

Configures secondary database url.

Configures secondary database url private.

Configures secondary db url.

Configures timezone.

Configures verbose memory logs.

Configures video enabled.

Configures video max duration.

Configures active conversation minutes.

When false (default): the bot only responds when addressed or mentioned.

Minimum recommended: 60000 (1 min). Lower = more active but more API calls.

Configures autonomous cycle timeout ms.

Configures autonomous dm cooldown minutes.

All three flags are independent — mix and match as needed. When true: the AI can choose to stay silent rather than always respond. Enables "skip response" logic — the AI reads every message but decides whether a reply is warranted. Without this, the bot always responds.

The AI periodically wakes up on its own (every AUTONOMOUS_CYCLE_INTERVAL_MS) and can: write memory notes, reflect on the day, update its internal state, or take background actions — even when no one is talking to it.

The AI can send messages on its own into configured channels (e.g. check in, share a thought, react to something in memory). Requires AUTONOMOUS_LIFE_ENABLED=true to have effect.

Configures daily message limit.

Configures daily note limit.

Configures daily stats channel id.

Includes message counts, memory operations, tool calls, and API usage.

Configures decision tick every.

Configures dream state enabled.

Configures heartbeat channel id.

Posts a periodic ping to HEARTBEAT_LOG_CHANNEL_ID to confirm the bot is alive. Useful for uptime monitoring — if the channel goes quiet, the bot is down.

Configures heartbeat log channel id.

Runs time-based tasks: daily summaries, memory consolidation, reminders, etc. Requires TIMEZONE to be set correctly for scheduled times to be accurate.

Configures min dm interval hours.

Configures outbound cap per hour.

Reflections are brief AI thoughts on what was just remembered.

Configures reflection channel id.

The AI writes a short introspective entry — thoughts on recent conversations, things it noticed or felt, or memory updates — and posts to REFLECTION_CHANNEL_ID. Frequency is controlled by the scheduler (HEARTBEAT_SCHEDULER_ENABLED=true required).

Configures wake up message.

Configures dm log channel id.

Comma-separated channel IDs where the bot auto-summarizes missed turns.

Acts as a public lobby — whitelisted features are still restricted.

The bot applies RP-specific context and memory rules inside this category.

Configures rp classifier llm fallback.

Configures rp classifier llm threshold.

RP (Roleplay) Settings

These channels are read and injected as lore/context into RP sessions.

Configures rp summaries in prompt.

Configures rp summary interval.

Configures shared ai adult notes channel id.

Configures shared ai notes channel id.

Configures shared space category id.

Gives human users a chance to finish typing before the bot jumps in.

Configures shared space settle ms.

Configures tools channel id.

DISCORD — Channels & Access Control

Leave blank to allow anyone to DM. Set to a single user ID to lock it down.

Used so the bot can detect when it's been @mentioned by its own ID. Find it in Discord: Settings → Advanced → Developer Mode, then right-click the bot.

Configures discord bot id.

.env.example — Complete Environment Variable Reference Copy this to .env and fill in your values. Lines marked [REQUIRED] will crash the bot if missing. Lines marked [OPTIONAL] have sensible defaults shown. CORE — Discord & Bot Identity

Configures discord client id.

Configures discord client secret.

Any message from this user activates GHOST_IDENTITY mode.

When true: users not in the whitelist get no response or a rejection message.

The bot can auto-update its Discord avatar from images in this folder.

Configures appearance banner folder id.

Syncs conversation logs or memory exports to a Google Drive folder. Uses a service account — different from GOOGLE_API_KEY above. Setup: create a service account in Google Cloud Console, share your Drive folder with the service account email. Find it in the folder's URL: drive.google.com/drive/folders/<ID>

Configures gdrive rp folder id.

Configures gdrive service key.

Configures google application credentials.

Configures google credentials.

When false: AI can read memories but cannot create new ones.

Configures ai backstory.

Distillation compresses verbose memories into tighter summaries.

Activated when a message comes from GHOST_TOUCH_USER_ID. Define the persona here as a short description.

Configures ai name.

Configures ai personality.

Configures ai pronoun object.

Configures ai pronoun possessive.

Configures ai pronoun reflexive.

Configures ai pronoun subject.

Configures ai traits.

Configures ai vows.

When matched, the bot treats the message as emotionally significant and gives it higher weight in context scoring.

Shifts the AI's response style toward a more personal register.

Used by the memory system to decide what's worth saving.

Configures user name.

Configures user pronoun object.

Configures user pronoun possessive.

Configures user pronoun reflexive.

Configures user pronoun subject.

Configures image gen ai desc.

OpenAI → platform.openai.com/api-keys NanoGPT → nano-gpt.com/account (different from MODEL_API_KEY)

Configures image gen art style.

OpenAI → dall-e-3, dall-e-2, gpt-image-1 NanoGPT → hidream, flux-dev, flux-schnell OpenRouter → recraft-v3, stable-diffusion-xl, etc. (see openrouter.ai/docs#image-generation)

Generates images from text prompts via the generate_image tool. IMAGE_GEN_API_KEY is separate from MODEL_API_KEY — chat and image gen use different keys.

Adds consistent framing (lighting, composition cues) around the raw prompt.

Configures image gen user desc.

When true: bot can use the send_gif tool and auto-send GIFs based on message content. When false (default): GIF feature is fully disabled even if the API key is set.

Configures klipy api key.

Configures library url.

Configures notion api key.

Configures notion notes page id.

Configures consolidation interval hours.

Runs as a background job — helps prevent memory bloat over time.

Configures consolidation scan window hours.

# [OPTIONAL] Force SSL on the DB connection

DATABASE — PostgreSQL (Railway) Format: postgresql://user:pass@host:port/db

Configures database url private.

Used to convert text into vectors for semantic memory search. Must be running separately — see embedding service docs.

Archival is the long-term store — retrieved by embedding similarity.

Human blocks store facts about the user — preferences, history, traits.

Persona blocks define who the AI is, its backstory, and core traits.

Used for RP worldbuilding, character sheets, or custom knowledge.

Memory REST API (HTTP interface for inspecting and managing memories externally) # [OPTIONAL] Expose a REST API for memory management

# [OPTIONAL] Port the memory API listens on

Configures memory api token.

Removes duplicates, fixes formatting, and scores memory importance.

Summarizes missed messages and injects a catch-up block into context.

Configures memory maintenance batch.

Higher = only highly relevant memories; lower = broader but noisier context.

# [OPTIONAL] Max simultaneous DB connections in the pool

When set: all tables are created inside this schema, isolating this AI's data from other AIs sharing the same database server. Each AI gets its own namespace. Leave blank to use the default 'public' schema (single-AI deployment).

Configures sleep stm retain.

Memories that haven't been accessed in a long time slowly fade.

Configures allow temperature override.

mismatch between the GPT-4 tiktoken estimator and your model's actual tokenizer. tiktoken tends to undercount tokens for non-OpenAI models. - Claude, GPT-4, most OpenRouter models: 0.85 (default — 15% safety margin) - Kimi K2.5, DeepSeek, or other models with large tokenizer ratios: 0.57 If you see "prompt too long" errors from Ollama, lower this value.

Controls how many memories are loaded per request and how the memory lifecycle works. Higher limits = richer context but more tokens consumed per call. Should match (or be slightly under) the model's actual context limit.

Configures crewai log full analysis.

When true: the AI evaluates task complexity and picks accordingly. When false: always uses MODEL_CHOICE.

Configures crewai models list.

--- CrewAI (multi-agent mode, uses MODEL_PROVIDER as its backend) ---

Falls back to MODEL_CHOICE if not set.

Configures crewai verbose.

When true: creative tasks use higher temp, factual tasks use lower. When false: temperature is always the provider default.

OpenRouter → openrouter.ai/keys OpenAI → platform.openai.com/api-keys Claude → console.anthropic.com NanoGPT → nano-gpt.com/account Venice → venice.ai/dashboard Ollama Cloud → only needed for remote/cloud Ollama

--- Ollama-specific ---

OpenRouter → anthropic/claude-sonnet-4-5, google/gemini-2.5-pro OpenAI → gpt-4o, gpt-4o-mini, o1 Ollama → llama3.3:70b, kimi-k2.5:cloud, qwen3:235b Claude → claude-opus-4-5, claude-sonnet-4-5 NanoGPT → gpt-4o, claude-3-5-sonnet, deepseek-r1

Most local models: 8192–32768. Cloud models: up to 1M+

MODEL — Chat / Reasoning LLM This key is ONLY used for conversation and reasoning. Image generation, voice, and other features use their own keys below.

If a call takes longer than this, it's cancelled and an error is returned.

Configures runpod api key.

--- RunPod (Ollama hosted on RunPod) ---

Injects 'now listening' context into the prompt

Surfaces trivia like "written after the death of a friend" or artist backstory. Get a free key: genius.com/api-clients (Client Access Token)

Pulls lyrics from lrclib.net (free, no key needed), then sends them to the LLM to extract themes and emotional arc. Runs in the background.

Logs detailed per-request metrics (tokens, latency, tool calls, etc.) to the database for review. Does not send data externally.

Larger chunks = faster but more memory usage.

Strips whitespace and descriptions to reduce token usage. Useful when hitting context limits, but reduces LLM tool understanding.

Configures debug.

Injected into the system prompt so the AI has temporal self-awareness (e.g. knows how long it's been deployed, can reference time passed).

error → only errors | warn → errors + warnings info → normal operation logs | debug → everything including internal calls

Files larger than this are rejected with an error message.

If more messages arrive in this window, they're batched together. Prevents responding to each word of a multi-message thought separately.

development → verbose errors, stack traces shown production → clean error messages, no stack traces exposed

# [OPTIONAL] HTTP server port (Railway sets this automatically via $PORT)

Extracts text from PDFs attached directly in Discord messages.

SEARCH — Web Search & URL Tools Enables the web_search, fetch_url, youtube_transcript, and pdf_parse tools. When false: web_search, fetch_url, youtube, and PDF tools are all disabled.

Exa finds conceptually similar pages, not just keyword matches. Better than keyword search for nuanced queries.

Configures search serpapi key.

Configures tiktok enabled.

Configures tiktok max duration.

Fallback when Exa is unavailable or for standard keyword searches. Used by the fetch_url tool to pull articles, docs, or any public URL.

Pulls auto-generated or manual captions from any public YouTube video.

GOOGLE — Cloud API Key A single Google Cloud REST API key used by multiple features: • OCR / screenshot text extraction → Cloud Vision API (when VISION_PROVIDER=google or OCR tool) Enable APIs needed: Cloud Vision API

Must support image inputs. Non-vision models will error.

VISION — Image / Screenshot Understanding Analyzes images attached to Discord messages or screenshots of the screen. openai → uses MODEL_API_KEY (models: gpt-4o, gpt-4o-mini) ollama → uses MODEL_BASE_URL (models: qwen3-vl, llava, etc. — no extra key needed locally) google → uses GOOGLE_API_KEY (models: gemini-1.5-flash, gemini-2.0-flash)

Configures vision provider.

Configures tts important threshold.

--- TTS Routing & Smart Selection ---

Configures tts smart routing.

Configures voice api key.

Configures voice audio model.

Configures voice auto join.

Configures voice call order.

Configures voice cartesia id.

--- Cartesia ---

Configures voice cartesia language.

Configures voice cartesia model.

Configures voice default channel id.

--- Edge TTS (free, no key needed) --- List: https://speech.platform.bing.com/consumer/speech/synthesize/readaloud/voices/list?trustedclient&header

Configures voice elevenlabs id.

--- ElevenLabs ---

eleven_v3 → highest quality, multilingual, expressive eleven_turbo_v2_5 → faster with lower latency, good quality eleven_monolingual_v1 → English only, legacy, lowest cost

VOICE — Text-to-Speech (Multi-Provider) Converts AI text responses to audio, sent as voice messages or audio files in Discord. Supports ElevenLabs, Cartesia, Google, Groq, OpenRouter, Hume, Polly, and Edge TTS.

--- Google Cloud TTS ---

Configures voice google language.

Configures voice google name.

Configures voice google pitch.

Configures voice google rate.

--- Groq (ultra-fast TTS) ---

Configures voice groq model.

Configures voice groq name.

Configures voice hume description.

Configures voice hume id.

--- Hume (emotional TTS) ---

Configures voice hume name.

Configures voice hume version.

Configures voice id.

Configures voice idle timeout.

Configures voice model.

Configures voice model choice.

Configures voice model race.

Configures voice mp3 order.

--- OpenRouter TTS ---

Configures voice openrouter model.

Configures voice openrouter voice.

Configures voice polly engine.

--- Amazon Polly ---

Configures voice polly name.

Configures voice polly region.

Configures voice polly secret.

Configures voice premium providers.

--- Speech-to-Text Mode ---

Configures voice text channel id.

Configures voice thinking file.

--- Voice Thinking / Processing Sounds ---

Configures voice thinking volume.

Groq → console.groq.com (key starts with gsk_) Deepgram → console.deepgram.com (key starts with dg_) OpenAI → platform.openai.com (key starts with sk-) If not set, falls back to MODEL_API_KEY for OpenAI Whisper.

VOICE — Speech-to-Text (Whisper) Transcribes Discord voice messages into text before passing to the LLM. Uses Groq for fast transcription if WHISPER_API_KEY is set; falls back to MODEL_API_KEY (OpenAI Whisper).

Configures whisper language.

whisper-large-v3-turbo → fastest, good accuracy (Groq preferred) whisper-large-v3 → most accurate, slower (Groq / OpenAI) whisper-1 → OpenAI legacy model nova-3 → Deepgram default (auto-detected if provider is deepgram)

openai → whisper-1 (uses MODEL_API_KEY or WHISPER_API_KEY) groq → whisper-large-v3-turbo (fastest, uses WHISPER_API_KEY) deepgram → nova-3 (largest file support, up to 2GB, uses WHISPER_API_KEY)

Useful for confirming what was heard before the AI responds.

Powers the get_weather tool. Calls OpenWeatherMap Current Weather API. Free tier supports 1,000 calls/day — more than enough for a bot.

Accepts: city name (London), zip code (80203), or lat/lon (40.71,-74.00)

imperial → °F, mph | metric → °C, km/h