---
title: "System Environment Settings"
description: "Configure LangBot system environment variables and runtime settings for your AI bot deployment."
---

Configure system runtime settings in `data/config.yaml`.
Generally, no modification is needed.

```yaml
admins: []
api:
    port: 5300
    webhook_prefix: 'http://127.0.0.1:5300'
    extra_webhook_prefix: ''
    global_api_key: ''  # Global API key. When non-empty, it is accepted for both the HTTP API and the MCP server (/mcp) with no login session, no database record, and no lbk_ prefix required. Empty = disabled. Stored in plaintext — enable only on trusted/internal deployments and serve over HTTPS.
command:
    enable: true
    prefix:
    - '!'
    - ！
    privilege: {}
concurrency:
    pipeline: 20
    session: 1
proxy:
    http: ''
    https: ''
system:
    instance_id: ''
    edition: community
    recovery_key: ''
    allow_modify_login_info: true
    disabled_adapters: []
    limitation:
        max_bots: -1
        max_pipelines: -1
        max_extensions: -1
    task_retention:
        # Keep at most this many completed async task records in memory
        completed_limit: 200
    jwt:
        expire: 604800
        secret: ''
database:
    use: sqlite
    sqlite:
        path: 'data/langbot.db'
    postgresql:
        host: '127.0.0.1'
        port: 5432
        user: 'postgres'
        password: 'postgres'
        database: 'postgres'
vdb:
    use: chroma
    qdrant:
        url: ''
        host: localhost
        port: 6333
        api_key: ''
    seekdb:
        mode: embedded  # 'embedded' or 'server'
        # Embedded mode options:
        path: './data/seekdb'
        database: 'langbot'
        # Server mode options (used when mode='server'):
        host: 'localhost'
        port: 2881
        user: 'root'
        password: ''
        tenant: ''  # Optional, for OceanBase server
    milvus:
        uri: 'http://127.0.0.1:19530'
        token: ''
        db_name: ''
    pgvector:
        host: '127.0.0.1'
        port: 5433
        database: 'langbot'
        user: 'postgres'
        password: 'postgres'
storage:
    use: local
    cleanup:
        # Enable periodic cleanup of local/S3 uploaded files and old log files
        enabled: true
        # Cleanup check interval in hours
        check_interval_hours: 1
        # Root-level uploaded files older than this will be deleted
        uploaded_file_retention_days: 7
        # LangBot log files older than this many days will be deleted
        log_retention_days: 3
    s3:
        endpoint_url: ''
        access_key_id: ''
        secret_access_key: ''
        region: 'us-east-1'
        bucket: 'langbot-storage'
plugin:
    enable: true
    runtime_ws_url: 'ws://langbot_plugin_runtime:5400/control/ws'
    enable_marketplace: true
    display_plugin_debug_url: 'ws://localhost:5401/plugin/debug/ws'
    binary_storage:
        # Max bytes for a single plugin binary storage value
        max_value_bytes: 10485760
monitoring:
    auto_cleanup:
        # Enable automatic cleanup of expired monitoring records
        enabled: true
        # Retention period in days, records older than this will be deleted
        retention_days: 30
        # Cleanup check interval in hours
        check_interval_hours: 1
        # Number of expired rows to delete per table batch
        delete_batch_size: 1000
box:
    enabled: true  # Master switch for Box Runtime. When false, Box-dependent features such as sandbox tools, Skill add/edit, and stdio MCP are disabled.
    backend: 'local'  # 'local' (Docker/nsjail), 'docker', 'nsjail', or 'e2b'. Can be written via BOX__BACKEND.
    runtime:
        endpoint: ''  # External Box Runtime base URL, e.g. 'ws://127.0.0.1:5410'. When empty, non-Docker deployments use a locally managed Runtime; Docker deployments connect to langbot_box:5410 on the Compose network.
    local:
        profile: 'default'
        image: ''  # Custom local sandbox image. Leave empty to use the profile default.
        host_root: './data/box'  # Base host directory for local workspace mounts. Docker deployments should use an absolute host path mounted by langbot_box.
        default_workspace: ''  # Defaults to '<host_root>/default'.
        skills_root: 'skills'  # Box-owned Skill package directory. Relative paths are resolved under host_root.
        allowed_mount_roots:  # Defaults to ['<host_root>'] when left empty.
            - './data/box'
            - '/tmp'
        workspace_quota_mb: null  # Optional disk quota override (>= 0). null = profile default.
    e2b:
        api_key: ''  # Can also be set via E2B_API_KEY env var.
        api_url: ''  # Custom API URL for self-hosted deployments.
        template: ''  # Default template ID (e.g. 'base', 'python-3.11').
space:
    # Space service URL for OAuth and API
    url: 'https://space.langbot.app'
    # Space API URL for model requests (MaaS)
    models_gateway_api_url: 'https://api.langbot.cloud/v1'
    # OAuth authorization page URL
    oauth_authorize_url: 'https://space.langbot.app/auth/authorize'
    disable_models_service: false
    disable_telemetry: false
```

## Notes

- `storage.cleanup.uploaded_file_retention_days` only cleans temporary uploaded files at the storage root. It does not delete plugin configuration files or internal objects stored under directories.
- `storage.cleanup.log_retention_days` cleans old log files by the date in their file names. The default keeps at most 3 days of logs.
- When SQLite is used as the database, automatic monitoring cleanup directly releases database file space after deleting expired records.
- `plugin.binary_storage.max_value_bytes` limits the size of a single plugin binary storage value. The default is 10 MiB.
- The WebUI sidebar includes a “Storage Analysis” page for viewing database, logs, uploaded files, vector store, plugins, MCP, temporary files, and cleanup candidates.
- `api.global_api_key` is a global API key for agents / automation: once set, calls to the HTTP API or the built-in MCP server (`/mcp`) authenticate by sending `X-API-Key: <key>` or `Authorization: Bearer *** — no login session and no database-stored `lbk_` key required. It is stored in plaintext in `config.yaml`, so enable it only on trusted / internal deployments and serve it over HTTPS. See [API Key Authentication](https://github.com/langbot-app/LangBot/blob/master/docs/API_KEY_AUTH.md).

## Set Configuration Via Environment Variables

The configuration in `config.yaml` can be set via environment variables. Environment variable names use uppercase letters and double underscores, for example: `API__PORT` represents `api.port`.

- `API__PORT` represents `api.port`
- `CONCURRENCY__PIPELINE` represents `concurrency.pipeline`
- `DATABASE__SQLITE__PATH` represents `database.sqlite.path`
- `STORAGE__CLEANUP__UPLOADED_FILE_RETENTION_DAYS` represents `storage.cleanup.uploaded_file_retention_days`
- `STORAGE__CLEANUP__LOG_RETENTION_DAYS` represents `storage.cleanup.log_retention_days`
- `MONITORING__AUTO_CLEANUP__RETENTION_DAYS` represents `monitoring.auto_cleanup.retention_days`
- `PLUGIN__BINARY_STORAGE__MAX_VALUE_BYTES` represents `plugin.binary_storage.max_value_bytes`
- `BOX__BACKEND` represents `box.backend`
- `BOX__LOCAL__HOST_ROOT` represents `box.local.host_root`
- `BOX__LOCAL__SKILLS_ROOT` represents `box.local.skills_root`

On startup, LangBot reads all environment variables, applies the corresponding configuration to `config.yaml`, and writes it to `data/config.yaml`.

<Note>
Set Box-related configuration on the `langbot` service with the unified `BOX__*` environment variables. LangBot applies them to `data/config.yaml` on startup and sends the Box configuration to `langbot_box` through INIT RPC. Do not set `LANGBOT_BOX_*` or `BOX__*` on the `langbot_box` service; they are not read directly there.
</Note>