Environment Variables
Complete inventory of the environment variables the bot reads. They configure infrastructure, not dashboard settings — no env var currently locks a UI field, and most dashboard settings cannot be set from env at all.
Two configuration surfaces
The bot is configured from two independent surfaces. The dashboard covers everything operators change day-to-day — API keys, the model router, channels, Auto Mode, memory, MCP, webhook config — and writes its state to files under preferences/. Environment variables cover infrastructure you decide before you start the bot — filesystem paths, the self-updater, marketplace repositories, dashboard logging buffers.
These two surfaces control mostly disjoint things. This page lists every environment variable the bot actually reads today, its default, and what it does. If a setting is not on this page, the dashboard is the only way to change it.
The lock-vs-default question
Setting an env var does not lock a dashboard field
There is no environment variable in the current bot that disables, hides, or makes read-only a setting in the dashboard UI. Every variable on this page either configures infrastructure the dashboard does not expose at all, or seeds a first-boot value that the persisted file then takes over. API keys, channel tokens, the model router, Auto Mode, memory, the MCP catalog and webhook config are dashboard-only — setting an env var will not pre-populate them. If you need them on a fresh install, mount a prepared preferences/ directory into the workspace instead.
Two categories
Every variable on this page falls into one of two categories. There is no third tier.
Startup
Read when the bot starts up. The dashboard does not expose the same value anywhere. Changing the env var takes effect after a restart.
Bootstrap
Read only on the very first boot, when the target settings file does not yet exist. The value is written to disk once; subsequent boots ignore the env var entirely. Rotate by editing the persisted value in the dashboard.
Workspace and sandbox
The base workspace directory and the sandbox root used by the file and shell tools. Set these when you need to move bot state or tool sandbox onto a specific volume.
| Variable | Default | Description |
|---|---|---|
STORAGE_PATH | ~/.golemcore/workspace | Base workspace directory — holds |
TOOLS_WORKSPACE | ~/.golemcore/sandbox | Sandbox root for the file and shell tools. Both tools share this one path, so anything the agent writes through one tool is visible to the other. Keep it on a different directory from |
UPDATE_PATH | ${STORAGE_PATH}/updates | Where the self-updater stages downloaded releases before swapping them in on the next restart. |
BOT_STORAGE_DIRECTORIES_SESSIONS / _MEMORY / _SKILLS | sessions / memory / skills | Subdirectory names under |
BOT_MEMORY_DIRECTORY, BOT_SKILLS_DIRECTORY, BOT_SKILLS_WORKSPACE_PATH | memory / skills / workspace/skills | Finer-grained overrides for the memory store, the skills store, and the per-workspace skills path. The defaults live inside |
Dashboard and logging
The dashboard HTTP surface, its in-memory log buffer, and the first-boot admin credential.
| Variable | Default | Description |
|---|---|---|
DASHBOARD_ENABLED | true | Master switch for the dashboard. When |
BOT_DASHBOARD_ADMIN_PASSWORD | (empty) | Bootstrap-only. On the very first boot, if no admin credential has been saved yet and this variable is non-empty, the bot hashes it and stores it as the admin password. On every subsequent boot the persisted file wins and this variable is ignored — changing it does not reset the password. Rotate from Settings → Security in the dashboard. |
BOT_DASHBOARD_LOGS_ENABLED | true | Enables the in-memory log buffer that backs the dashboard Logs view. Turn off if you already ship logs off-box through stdout and do not want the extra memory cost. |
BOT_DASHBOARD_LOGS_MAX_ENTRIES | 10000 | How many log entries the ring buffer keeps. |
BOT_DASHBOARD_LOGS_DEFAULT_PAGE_SIZE | 200 | Default page size when the Logs view queries the buffer. |
BOT_DASHBOARD_LOGS_MAX_PAGE_SIZE | 1000 | Upper bound on a single Logs-view page request. |
BOT_DASHBOARD_LOGS_MAX_MESSAGE_CHARS | 8000 | Per-entry truncation limit for the log message body (characters). |
BOT_DASHBOARD_LOGS_MAX_EXCEPTION_CHARS | 16000 | Per-entry truncation limit for attached exception stack traces (characters). |
Tune the five LOGS_* caps up on big boxes with plenty of memory, down on small containers.
Self-update
The self-updater downloads new releases in the background and swaps them in on the next restart. None of its settings live in the dashboard.
| Variable | Default | Description |
|---|---|---|
BOT_UPDATE_ENABLED | true | Turns the self-updater on or off. Disable on pinned-version deployments where the container image is the source of truth. |
BOT_UPDATE_CHECK_INTERVAL | PT1H | How often the updater checks for new releases. ISO-8601 duration — |
BOT_UPDATE_MAX_KEPT_VERSIONS | 3 | How many previous releases to keep on disk for rollback. Each kept release is a full jar, so avoid setting this high on small volumes. |
Skill and plugin marketplaces
Skills and plugins both ship with a marketplace pointed at a public GitHub repository. These variables redirect the marketplace to a private fork, pin a branch, target a GitHub Enterprise Server instance, or disable the marketplace entirely. Skills and plugins have parallel sets of variables that behave identically.
| Variable | Default | Description |
|---|---|---|
BOT_SKILLS_MARKETPLACE_ENABLED | true | Master switch for the skill marketplace. When off, skills come only from the bundled set and from files under your workspace. |
BOT_SKILLS_MARKETPLACE_REPOSITORY_URL | github.com/alexk-dev/golemcore-skills | Git repository URL backing the skill marketplace. |
BOT_SKILLS_MARKETPLACE_BRANCH | main | Git branch to read from. Pin to a release branch or a fork for stability. |
BOT_SKILLS_MARKETPLACE_API_BASE_URL | api.github.com | GitHub REST API base URL. Override for GitHub Enterprise Server. |
BOT_SKILLS_MARKETPLACE_RAW_BASE_URL | raw.githubusercontent.com | GitHub raw-content base URL. Override alongside the API URL on Enterprise Server. |
BOT_SKILLS_MARKETPLACE_REMOTE_CACHE_TTL | PT5M | How long a marketplace listing is cached before the bot re-fetches it. ISO-8601 duration. |
BOT_SKILLS_MARKETPLACE_REPOSITORY_DIRECTORY | (empty) | Optional local directory where marketplace content is cloned. Empty means the bot picks a path under the workspace. |
BOT_SKILLS_MARKETPLACE_SANDBOX_PATH | (empty) | Sandbox directory for skill evaluation. Skills-only — there is no plugin equivalent. |
The plugin side exposes the same six marketplace variables with BOT_PLUGINS_MARKETPLACE_* names and the same defaults — except the repository URL is github.com/alexk-dev/golemcore-plugins. Plus a few plugin-runtime variables:
| Variable | Default | Description |
|---|---|---|
BOT_PLUGINS_ENABLED | true | Master switch for the plugin system. When off, no plugin tools load and the plugin marketplace is unreachable. |
BOT_PLUGINS_AUTO_START | true | Start installed plugins on boot. When off, plugins start lazily on first use. |
BOT_PLUGINS_AUTO_RELOAD | true | Reload plugins when their files change on disk — useful for plugin development. |
BOT_PLUGINS_POLL_INTERVAL | PT5S | File-watcher poll interval used when auto-reload is on. |
BOT_PLUGINS_DIRECTORY | ${STORAGE_PATH}/plugins | Directory where plugin artifacts are installed. |
Webhooks, Hive, and Spring
Two small areas round out the inventory.
| Variable | Default | Description |
|---|---|---|
BOT_WEBHOOKS_DELIVERY_HISTORY_MAX_ENTRIES | 500 | Maximum number of webhook delivery records kept in the in-memory history for the dashboard's Deliveries view. Raise for longer audit windows, lower on tight memory. |
BOT_HIVE_DASHBOARD_BASE_URL | (empty) | Bootstrap-only. Hive dashboard base URL used for SSO redirects from a self-hosted Hive deployment. Normally managed from the dashboard at runtime; the env var exists so the value can be seeded before first boot. |
BOT_HIVE_SSO_ENABLED | (empty) | Bootstrap-only. Hive SSO enable flag. Same rules as the URL above — seeded on first boot, then managed from the dashboard. |
SPRING_APPLICATION_NAME | golemcore-bot | Standard Spring Boot variable used for the application name. Rarely overridden. |
SPRING_PROFILES_ACTIVE | (none) | Standard Spring Boot variable. Set to |
What is not env-configurable at all
Everything below lives in preferences/ JSON files, is written by the dashboard, and has no environment-variable equivalent. If you need to seed these on a fresh install without a human clicking through the dashboard, bake the correct JSON files into your image or mount them as a volume — there is no env var shortcut.
- LLM provider API keys and base URLs (Anthropic, OpenAI, Gemini, Groq, xAI, Mistral, and OpenAI-compatible endpoints).
- Model router config — default tier, per-tier models, fallbacks, dynamic upgrade rules.
- Channel integrations — Telegram bot token, Slack bot token and app credentials, Discord, custom channels.
- Voice provider settings — ElevenLabs API key, Whisper backend config, voice IDs, prefix character.
- Auto Mode configuration — the Enable toggle, task time limit, max goals, model tier, reflections, auto-start, notify milestones.
- Memory preset, reranker backend, and retrieval provider choice.
- MCP runtime defaults (startup/idle timeouts), the Enable MCP kill switch, and the full MCP catalog.
- Webhook config — wake/agent paths, shared secrets, HMAC settings, response JSON schemas, the memory preset for webhook turns.
- Plugin-level settings — API keys and credentials for installed plugins like brave-search, firecrawl, browserless, mail, notion, obsidian, lightrag.
Bootstrap by file, not by env var
To bring up a fresh bot with these already populated, mount a pre-built preferences/ directory into STORAGE_PATH before the bot starts. The bot reads the files on boot exactly as if a human had configured them through the dashboard.
Example: Docker with env overrides
A minimal Docker invocation that overrides the three most commonly set variables — workspace, tool sandbox, and the first-boot admin password:
docker run --rm -p 8080:8080 \
-e STORAGE_PATH=/data/workspace \
-e TOOLS_WORKSPACE=/data/sandbox \
-e BOT_DASHBOARD_ADMIN_PASSWORD=your-bootstrap-password \
-v golemcore-data:/data \
golemcore/bot:latestAfter the first boot the bot saves the admin credential under /data/workspace/preferences/admin-credentials.json and ignores BOT_DASHBOARD_ADMIN_PASSWORD on subsequent restarts. Rotate the password from Settings → Security in the dashboard, not by changing the env var.