Docker Deployment

Deploy LangBot with Docker and Docker Compose. Run an open-source multi-platform AI chatbot for Discord, Telegram, WeChat and more in minutes.

Before you start, you may learn about in advanced:

Usage of Docker and Docker Compose
Docker container network communication configuration methods

Please ensure Git, Docker, and Docker Compose are installed

Clone the project:

git clone https://github.com/langbot-app/LangBot
cd LangBot/docker

Start the containers with the recommended all profile, which enables Box Runtime-dependent features by default, including the sandbox, stdio MCP hosting, and Skill add/edit:

docker compose --profile all up

Runtime tokens for Internet-accessible deployments

The open-source edition skips token verification only when both LangBot and the corresponding Runtime leave the token unset. If the deployment is accessible from the Internet, strongly protect Plugin Runtime and Box Runtime with separate strong tokens:

export LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN="$(openssl rand -hex 32)"
export LANGBOT_BOX_CONTROL_TOKEN="$(openssl rand -hex 32)"
docker compose --profile all up -d

The official Compose file passes each variable to both ends of its connection. Setting only one end, using different values, or using a weak token causes the connection to be rejected. Store tokens in your deployment platform's secret manager and never commit them.

This starts langbot, langbot_plugin_runtime, and langbot_box. If you only need the basic services and do not want to enable Box Runtime, run:

docker compose up

SeekDB support

The official Docker image already includes the optional SeekDB dependencies; no additional build argument is required. The container uses the matching Linux pylibseekdb wheel, so the host macOS version does not limit embedded mode inside the container. Keep the default vdb.use: chroma when SeekDB is not needed.

langbot_box creates sandbox containers through the host Docker socket, so the Box root path must be identical on the host and inside the container:

services:
  langbot:
    environment:
      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__LOCAL__DEFAULT_WORKSPACE=default
      - BOX__LOCAL__SKILLS_ROOT=skills
      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}

  langbot_box:
    profiles: ["box", "all"]
    volumes:
      - ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - /var/run/docker.sock:/var/run/docker.sock

The Box control plane's transport depends on the deployment method. In Docker deployments it runs as the standalone langbot_box container, and langbot connects to it over WebSocket (ws://langbot_box:5410). In manual / uvx deployments, langbot instead spawns a stdio subprocess as the Box control plane. langbot_box creates sandbox sibling containers on the host Docker through the mounted docker.sock; the LangBot image already bundles the docker client, so no extra installation is required.

If you see No sandbox backend (Docker/nsjail/E2B) is ready, first make sure the current user can access Docker:

sudo usermod -aG docker $USER
newgrp docker
docker info

If docker info works, restart LangBot.

langbot_box does not read LANGBOT_BOX_* or BOX__* variables directly. Set BOX__LOCAL__* on langbot; LangBot forwards the effective Box config to Box Runtime through INIT RPC. To change the Box root, set LANGBOT_BOX_ROOT to an absolute path, for example LANGBOT_BOX_ROOT=/var/lib/langbot/box docker compose --profile all up.

The container maps port 5300 for WebUI access. You can visit http://127.0.0.1:5300 to view the WebUI.
It also maps ports 2280-2285 reserved for message platform adapters.

After completing the LangBot deployment, please continue reading:

Docker Deployment

Runtime tokens for Internet-accessible deployments

SeekDB support

On this page