docs/self-hosting/environment-variables/basic.mdx
LobeHub provides some additional configuration options during deployment, which can be customized using environment variables.
KEY_VAULTS_SECRETKix2wcUONd4CX51E/ZPAd36BqM4wzJgKjPtz2sGztqQ=<Callout type={'warning'}> This key is used to encrypt sensitive data. Once set, do not change it, otherwise encrypted data cannot be decrypted. </Callout>
<GenerateSecret envName="KEY_VAULTS_SECRET" />API_KEY_SELECT_MODErandom and turn.randomrandom or turnWhen using the random mode, a random API Key will be selected from the available multiple API Keys.
When using the turn mode, the API Keys will be retrieved in a polling manner according to the specified order.
DEFAULT_AGENT_CONFIG'model=gpt-4o;params.max_tokens=300;plugins=search-engine,lobe-image-designer'The DEFAULT_AGENT_CONFIG is used to configure the default settings for the LobeHub default agent. It supports various data types and structures, including key-value pairs, nested fields, array values, and more. The table below provides detailed information on the configuration options, examples, and corresponding explanations for the DEFAULT_AGENT_CONFIG environment variable:
| Configuration Type | Example | Explanation |
|---|---|---|
| Basic Key-Value Pair | model=gpt-4 | Set the model to gpt-4. |
| Nested Field | tts.sttLocale=en-US | Set the language locale for the text-to-speech service to en-US. |
| Array | plugins=search-engine,lobe-image-designer | Enable the search-engine and lobe-image-designer plugins. |
| Chinese Comma | plugins=search-engine，lobe-image-designer | Same as above, demonstrating support for Chinese comma separation. |
| Multiple Configurations | model=glm-4;provider=zhipu | Set the model to glm-4 and the model provider to zhipu. |
| Numeric Value | params.max_tokens=300, chatConfig.historyCount=5 | Set the maximum tokens to 300, Set the number of historical messages to 5. |
| Boolean Value | chatConfig.enableHistoryCount=true, chatConfig.enableCompressThreshold=true, chatConfig.enableStreaming=true | Enable history length limit, history length compression threshold, and streaming output. |
| Special Characters | inputTemplate="Hello; I am a bot;" | Set the input template to Hello; I am a bot;. |
| Error Handling | model=gpt-4;maxToken | Ignore invalid entry maxToken and only parse model=gpt-4. |
| Value Override | model=gpt-4;model=gpt-4o | If a key is repeated, use the value that appears last; in this case, the value of model is gpt-4o. |
Further reading:
SYSTEM_AGENT-default=ollama/deepseek-v3 or topic=openai/gpt-4,translation=anthropic/claude-sonnet-4-5-20250929The SYSTEM_AGENT environment variable supports two configuration methods:
default=provider/model to set the same default configuration for all system agentsagent-name=provider/modelConfiguration details:
| Config Type | Format | Explanation |
|---|---|---|
| Default setting | default=ollama/deepseek-v3 | Set deepseek-v3 from ollama as the default model for all system agents |
| Specific setting | topic=openai/gpt-4 | Set a specific provider and model for topic generation |
| Mixed configuration | default=ollama/deepseek-v3,topic=openai/gpt-4 | First set default values for all agents, then override specific agents |
Available system agents and their functions:
| System Agent | Key Name | Function Description |
|---|---|---|
| Topic Generation | topic | Automatically generates topic names and summaries based on chat content |
| Translation | translation | Handles text translation between multiple languages |
| Metadata Generation | agentMeta | Generates descriptive information and metadata for assistants |
| History Compression | historyCompress | Compresses and organizes history for long conversations, optimizing context management |
| Branch Conversation | thread | Automatically generate titles for branch conversations |
| Image Generation Naming | generationTopic | AI image automatic topic naming |
| Input Auto-completion | inputCompletion | Input auto-completion suggestions (similar to GitHub Copilot ghost text) |
| Prompt Rewrite | promptRewrite | Optimize prompts before generation |
| Image Generation Naming | generationTopic | AI image automatic topic naming |
FEATURE_FLAGS+ to add a feature and - to disable a feature. Separate multiple feature flags with a comma , and enclose the entire value in quotes " to avoid parsing errors.-"-welcome_suggest"For specific content, please refer to the Feature Flags documentation.
ENABLE_AGENT_GATEWAYAGENT_GATEWAY_URL is also configured.01Business builds enable Gateway Mode automatically. Self-hosted deployments can set ENABLE_AGENT_GATEWAY=1 together with AGENT_GATEWAY_URL to expose Gateway Mode to clients.
AGENT_GATEWAY_URLhttps://agent-gateway.example.comAGENT_GATEWAY_SERVICE_TOKENdev-secretPROXY_URLhttp://127.0.0.1:7890 or socks5://localhost:7891SSRF_ALLOW_PRIVATE_IP_ADDRESS1 to disable SSRF protection and allow all private IP addresses. In a trusted environment (e.g., internal network), this can be enabled to allow access to internal resources.01 or 0Use Cases:
LobeHub performs SSRF security checks in the following scenarios:
Image/Video URL to Base64 Conversion: When processing media messages (e.g., vision models, multimodal models), LobeHub converts image and video URLs to base64 format. This check prevents malicious users from accessing internal network resources.
Examples:
http://192.168.1.100/admin/secrets.pnghttp://10.0.0.50/internal/meeting.mp4Without SSRF protection, these requests could expose internal network resources.
Web Crawler: When using web crawling features to fetch external content.
Proxy Requests: When proxying external API requests.
Configuration Examples:
# Scenario 1: Public deployment (recommended)
# Block all private IP addresses for security
SSRF_ALLOW_PRIVATE_IP_ADDRESS=0
# Scenario 2: Internal deployment
# Allow all private IP addresses to access internal image servers
SSRF_ALLOW_PRIVATE_IP_ADDRESS=1
# Scenario 3: Hybrid deployment (most common)
# Block private IPs by default, but allow specific trusted internal servers
SSRF_ALLOW_PRIVATE_IP_ADDRESS=0
SSRF_ALLOW_IP_ADDRESS_LIST=192.168.1.100,10.0.0.50
SSRF_ALLOW_IP_ADDRESS_LISTSSRF_ALLOW_PRIVATE_IP_ADDRESS is 0. Use this to allow specific internal IP addresses while keeping SSRF protection enabled for other private IPs.192.168.1.100,10.0.0.50,172.16.0.10Common Use Cases:
192.168.1.10010.0.0.50172.16.0.10ASSET_BASE_URLhttps://cdn.example.com<Callout type={'warning'}>
When this points at a different origin than the app, that host must respond with an
Access-Control-Allow-Origin header covering your app's origin. Once an asset base URL is
configured, LobeHub emits crossorigin on the generated <script> and <link> tags — a host
without the header makes the browser refuse to execute those assets, leaving a blank page. It also
means script errors from those files reach error monitoring with a real stack instead of an opaque
Script error. frame.
</Callout>
NEXT_PUBLIC_ASSET_PREFIXASSET_BASE_URL insteadASSET_BASE_URL. Still used as a fallback when ASSET_BASE_URL is unset, and carries the same cross-origin requirement described above.https://cdn.example.comMULTIMODAL_UNDERSTANDING_PROVIDERMULTIMODAL_UNDERSTANDING_MODEL to let models without native audio, image, or video understanding inspect uploaded media through the built-in multimodal understanding tool.openai, google, or ollamaMULTIMODAL_UNDERSTANDING_MODELMULTIMODAL_UNDERSTANDING_PROVIDER and MULTIMODAL_UNDERSTANDING_MODEL are configured.gemini-2.5-flash or your local multimodal model IDConfiguration example:
MULTIMODAL_UNDERSTANDING_PROVIDER=google
MULTIMODAL_UNDERSTANDING_MODEL=gemini-2.5-flash
For migration compatibility, VISUAL_UNDERSTANDING_PROVIDER and VISUAL_UNDERSTANDING_MODEL remain supported as legacy aliases. When both old and new variables are set, MULTIMODAL_UNDERSTANDING_* takes precedence.
When this feature is enabled, users can upload audio, images, or videos while using a model that does not have the corresponding native multimodal capability, as long as the active model supports tool use. File upload still requires the normal file storage configuration for your deployment.
AI_IMAGE_DEFAULT_IMAGE_NUM261-20This environment variable allows administrators to customize the default image generation count for their deployment. The value must be between 1 and 20. If not set, it defaults to 2. Users can still adjust this value in their personal settings.
TOOL_NAME_MAX_LENGTHMD5HASH_… name. OpenAI caps function names at 64 characters, but providers without that limit only pay the readability cost, so the threshold is configurable. Set it to 0 to disable length-based compression entirely and keep full, readable tool names. Names containing characters providers reject (non-ASCII, dots, spaces…) are still hashed regardless of this setting.640PLUGINS_INDEX_URLhttps://registry.npmmirror.com/@lobehub/plugins-index/v1/files/publicPLUGIN_SETTINGSplugin-name:setting-field=setting-value to configure the settings of the plugin. Separate multiple setting fields with a semicolon ;, and separate multiple plugin settings with a comma ,.-search-engine:SERPAPI_API_KEY=xxxxx,plugin-2:key1=value1;key2=value2The above example sets the SERPAPI_API_KEY of the search-engine plugin to xxxxx, and sets key1 of plugin-2 to value1, and key2 to value2. The generated plugin settings configuration is as follows:
{
"plugin-2": {
"key1": "value1",
"key2": "value2"
},
"search-engine": {
"SERPAPI_API_KEY": "xxxxx"
}
}
AGENTS_INDEX_URLhttps://registry.npmmirror.com/@lobehub/agents-index/v1/files/public