Manage LangBot with lbctl
Install, upgrade, start/stop, read logs, diagnose, configure autostart, run multiple instances and uninstall LangBot with lbctl, and bring existing Docker Compose deployments under lbctl.
lbctl is LangBot's official command-line tool. The one-line installer installs it for you. lbctl handles the day-to-day operation of a self-hosted LangBot, so you no longer need to run docker compose, uvx or download archives by hand.
lbctl prints English or Chinese based on your system language; override it with --lang en / --lang zh-Hans. Every command accepts -o json for machine-readable output, which is useful for scripts and AI agents.
What lbctl replaces
| Task | Previously | With lbctl |
|---|---|---|
| Install | uvx langbot, or git clone then docker compose up | One-line installer, or lbctl install (add --driver docker for Docker) |
| Upgrade LangBot | git pull + docker compose up --force-recreate --pull always; rerun uvx langbot@latest; overwrite with a release archive | lbctl upgrade --yes (automatic backup and health checks) |
| Check status and version | docker compose ps, or open the WebUI | lbctl status |
| Read logs | docker logs langbot | lbctl logs, lbctl logs -f |
| Start / stop / restart | docker compose up -d / down / restart | lbctl start / stop / restart |
| Troubleshoot the environment | Check Docker, ports, disk and network by hand | lbctl doctor |
| Start at boot | Write systemd / launchd units or scheduled tasks | Configured at install; lbctl autostart status/enable/disable |
| Optional SeekDB, Milvus, Valkey dependencies | uv sync --extra ..., or switch image tags by hand | lbctl install --extra seekdb (or milvus, valkey) |
| Mirrors in mainland China | Edit PyPI or Docker registry settings by hand | Region detected automatically and a working source selected; or --region cn |
| Run several instances | Copy directories and edit ports | lbctl install --name <instance> --port <port>, lbctl list |
| Uninstall | Remove containers and directories by hand | lbctl uninstall (keeps data by default) |
| Update lbctl itself | Download again | lbctl update |
| Connect the CLI to a local instance | Create an API key in the WebUI, then lbctl context add | Connected automatically after install; just run lbctl bot list |
Status and diagnostics
lbctl status # state, LangBot and lbctl versions, URL, deployment type
lbctl doctor # checks Python/Docker, ports, disk, network, image sources, sandbox
lbctl list # lists all LangBot instances on this machineWhen something goes wrong, run lbctl doctor first. It reports each failing check and the next command to run.
Start, stop and logs
lbctl start
lbctl stop
lbctl restart
lbctl logs # last 200 lines
lbctl logs -f # follow
lbctl logs --tail 1000 # last 1000 lines (up to 5000)
lbctl logs --service langbot_plugin_runtime # Plugin Runtime logs on Docker deploymentsNative deployments write logs to logs/langbot.log in the instance directory, with automatic rotation.
Upgrade LangBot
lbctl upgrade --dry-run # check and show the plan without changing anything
lbctl upgrade --yes # upgrade to the latest stable release
lbctl upgrade --version v4.11.8 --yes # upgrade to a specific releaseHow upgrades work:
- Native: prepares the new runtime first, then stops the service, backs up data, switches versions and checks
/healthz. If the new version fails to start, the previous version and data are restored automatically. - Docker: pulls and verifies the new image, then stops the service, backs up data and the Compose file, starts the new version and waits for every service's health check.
- Backups are stored in
backups/next to the data directory; native deployments keep the newest 3. - If you are already on the latest version,
lbctl upgrade --yessays so and changes nothing. lbctl updateupgrades lbctl itself and does not touch LangBot.
Bring an existing Docker Compose deployment under lbctl
If you deployed with docker compose following the Docker guide, you don't need to reinstall. Install lbctl and adopt the existing deployment:
# Install lbctl only, without deploying a new LangBot
curl -fsSL https://langbot.app/install.sh | bash -s -- --lbctl-only
# Run in the LangBot/docker directory to adopt the deployment (adjust the port if needed)
lbctl --endpoint http://127.0.0.1:5300 adopt \
--file "$(pwd)/docker-compose.yaml" --project docker --profile all
lbctl status
lbctl upgrade --dry-run
lbctl upgrade --yes--projectis the Compose project name; seedocker compose ls(it isdockerwhen started fromLangBot/docker).lbctl context list --discoveralso lists deployments on this machine that can be adopted.- Adoption does not change your Compose file. Upgrades only replace the images of the
langbot,langbot_plugin_runtimeandlangbot_boxservices; ports, mounts, environment variables and other services stay as they are. - Automatic upgrades require services to use a
rockchin/langbot:<tag>image directly and all data to live in thedatabind mount under the Compose directory (SQLite, Chroma and local storage). Otherwiselbctl upgrade --dry-runexplains why; in that case keep upgrading manually as described in Update LangBot. - After editing the Compose file by hand, run
adoptagain. - Once adopted,
status,logs,start,stop,restart,doctorandupgradeall work.
Upgrading an adopted Docker deployment requires lbctl v0.5.9 or later. Check with lbctl version and update with lbctl update.
Start at boot
The one-line installer enables startup at boot/login by default: systemd on Linux, launchd on macOS, the current user's login startup on Windows (no administrator rights needed), and restart: unless-stopped for Docker.
lbctl autostart status
lbctl autostart disable # turn off autostart without stopping the running instance
lbctl autostart enableNon-root Linux users get a systemd user service. Run loginctl enable-linger to keep it running after you log out.
Install options
lbctl install # native deployment (recommended), Python prepared automatically
lbctl install --driver docker # Docker Compose deployment
lbctl install --port 5300 # HTTP port
lbctl install --extra seekdb # optional dependencies: seekdb, milvus, valkey
lbctl install --version v4.11.8 # specific release
lbctl install --region cn # network region: auto, cn, global
lbctl install --dry-run # check prerequisites and show the plan only- Native deployments use uv and Python managed by lbctl; the system Python is never used or modified.
- If a native installation fails, rerun
lbctl installwith the same instance name and port to repair it; existing data and version are kept. - Instances live in
~/.langbot/instances/<name>by default (/opt/langbotfor root,%LOCALAPPDATA%\LangBoton Windows); change this withLANGBOT_HOME.
Multiple instances
lbctl install --driver docker --name second --port 5310 --project langbot-second
lbctl list
lbctl stop --name second
lbctl start --name secondstart, stop, restart, upgrade, uninstall and autostart accept --name to select an instance. status, logs and doctor act on the current connection; list connections with lbctl context list and switch with lbctl context use <name>.
Use Docker to run several instances at the same time: native deployments need exclusive use of ports 5401 (plugin debugging) and 5410 (sandbox).
Uninstall
lbctl uninstall --yes # stop and remove the service, keep data and backups
lbctl uninstall --purge-data --yes # also delete lbctl-managed data directoriesManage bots, plugins and models from the command line (optional)
Day-to-day configuration is easiest in the WebUI. lbctl can also manage Workspace resources over the HTTP API, which suits scripts and AI agents.
Local instances installed or adopted with lbctl connect automatically (lbctl v0.5.11 or later). lbctl generates an API key for each instance, writes it to api.global_api_key in data/config.yaml, and attaches it to that instance's connection. No setup is needed:
lbctl whoami
lbctl bot list
lbctl plugin list
lbctl model list
lbctl knowledge-base list- Existing instances get a key the next time you run
lbctl start,restartorupgrade. For adopted deployments, runlbctl restartonce when prompted. - The key is stored only in the instance directory (mode 0600) and never appears in lbctl's config file,
-o jsonoutput or logs. To configure an MCP client or another tool, show it withlbctl auth show-key --yes. - With several local instances, list their connections with
lbctl context listand pick one with--context <name>.
For a remote instance or LangBot Cloud, create an API key in the WebUI, then add a connection:
export LANGBOT_API_KEY=<your API key>
lbctl context add remote --endpoint https://your-langbot.example.com --api-key-env LANGBOT_API_KEY
lbctl --context remote whoamiSee lbctl help or the lbctl repository for every command.
One-Line Install (Recommended)
Install lbctl and deploy LangBot with one command: Python set up automatically, native or Docker deployment, start on boot, one-command upgrades.
Deploy with Package Manager
Deploy LangBot with a package manager (uv/uvx). Quick install for the open-source LLM chatbot platform.
