LangBot

https://langbot.app/docs/
Admin
LangBot is an open-source LLM-native instant messaging bot platform that connects messaging...
Tokens:207,952
Snippets:1,615
Trust Score:7.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install and start frontend with pnpm or npm

Source: https://langbot.app/docs/en/develop/dev-config

Install dependencies and start the frontend. The pnpm commands are the primary method; the npm commands are an alternative if pnpm is not installed.

```bash
pnpm install
pnpm dev
```

```bash
npm install
npm run dev
```

--------------------------------

### Frontend setup with pnpm

Source: https://langbot.app/docs/en/develop/agent-context

Sets up the frontend with pnpm, copies the environment file, installs dependencies, and starts the dev server on http://127.0.0.1:3000. The dev server reads VITE_API_BASE_URL from web/.env to reach the backend on :5300. npm install and npm run dev are also supported.

```bash
cd web
cp .env.example .env   # Windows: copy .env.example .env
pnpm install
pnpm dev               # http://127.0.0.1:3000 (npm install / npm run dev also work)
```

--------------------------------

### Backend setup with uv

Source: https://langbot.app/docs/en/develop/agent-context

Sets up the Python backend with uv, installs dev dependencies, and runs the main application serving API and frontend on http://127.0.0.1:5300. On first run, the config file is generated at data/config.yaml; SQLite is the default database with zero setup, and PostgreSQL is also supported. Migrations run automatically on startup.

```bash
pip install uv
uv sync --dev          # uv creates a .venv/ for you; point your editor's interpreter at it
uv run main.py         # serves API + frontend on http://127.0.0.1:5300
```

--------------------------------

### Run Python reference client (serve and push)

Source: https://langbot.app/docs/en/usage/platforms/http-bot

Sets up and runs the Python reference client: installs dependencies, starts a callback receiver on port 8900 with a shared secret, and pushes a message to a bot. The receiver prints each reply part with its sequence number, demonstrating 1→M multi-reply with signature verification.

```bash
cd examples/http-bot
pip install flask requests

# Terminal 1: callback receiver (point the bot's callback_url here; use cloudflared / ngrok locally)
python client.py serve --port 8900 --secret SHARED_SECRET

# Terminal 2: push a message
python client.py push \
  --url https://your-langbot/bots/<bot_uuid> \
  --secret SHARED_SECRET \
  --session ticket-1 \
  --text "hello"
```

--------------------------------

### Plugin installation flow (async generator)

Source: https://langbot.app/docs/en/articles/langbot-plugin-system-deep-dive

Shows the four-step installation process: downloading and extracting the package, installing dependencies via pip, initializing plugin settings, and launching the plugin process. Progress is reported through an AsyncGenerator for real-time frontend status.

```python
async def install_plugin(self, source, install_info):
    yield {"current_action": "downloading plugin package"}
    # 1. Fetch and extract the plugin package (unzip)
    plugin_path, author, name, version = await self.install_plugin_from_file(plugin_file)

    yield {"current_action": "installing dependencies"}
    # 2. Install dependencies (pip install -r requirements.txt)
    pkgmgr_helper.install_requirements(requirements_file)

    yield {"current_action": "initializing plugin settings"}
    # 3. Initialize configuration
    await self.context.control_handler.call_action(
        RuntimeToLangBotAction.INITIALIZE_PLUGIN_SETTINGS, {...}
    )

    yield {"current_action": "launching plugin"}
    # 4. Launch the plugin process
    task = self.launch_plugin(plugin_path)
```

--------------------------------

### Start Chatting with LangTARS

Source: https://langbot.app/docs/en/articles/langtars-remote-pc-control-dify-n8n

Example chat command to start interacting with LangTARS after installation. Use this in your configured chat platform to test the assistant.

```text
!tars Hello, tell me what you can do
```

--------------------------------

### Install backend dependencies with uv

Source: https://langbot.app/docs/en/develop/dev-config

Install uv and sync development dependencies for the backend.

```bash
pip install uv
uv sync --dev
```

--------------------------------

### Install dependencies with uv

Source: https://langbot.app/docs/en/deploy/langbot/manual

Install uv and sync dependencies. The default installation excludes optional SeekDB support; use the --extra seekdb flag to include it.

```bash
pip install uv
uv sync
```

--------------------------------

### Install NGINX on Ubuntu

Source: https://langbot.app/docs/en/workshop/production/proxy-and-ssl

Installs NGINX on Ubuntu using apt. Run these commands in a terminal with sudo privileges.

```bash
sudo apt update
sudo apt install nginx
```

--------------------------------

### Deploy LangBot with uvx

Source: https://langbot.app/docs/en/articles/dify-agent-discord-telegram-slack

Run these three commands to create a directory, enter it, and start LangBot with uvx. After starting, visit http://127.0.0.1:5300 to register an admin account.

```bash
mkdir langbot-instance
cd langbot-instance
uvx langbot@latest
```

--------------------------------

### POST /api/v1/plugins/install/marketplace

Source: https://langbot.app/docs/en/api-reference/plugins/install-a-plugin-from-marketplace

This endpoint installs a plugin from the LangBot Marketplace asynchronously. It requires a plugin ID in the request body and returns a task ID for tracking the installation.

```APIDOC
## POST /api/v1/plugins/install/marketplace

### Description
Install a plugin from LangBot Marketplace asynchronously and return the task ID.

### Method
POST

### Endpoint
/api/v1/plugins/install/marketplace

### Parameters
#### Request Body
- **plugin_id** (string) - Required - Marketplace plugin ID (author/name format), e.g., "kellz-dev/disaster-alert"

### Request Example
{
  "plugin_id": "kellz-dev/disaster-alert"
}

### Response
#### Success Response (200)
- **code** (integer) - Response code, e.g., 0
- **data** (object) - Response data
  - **task_id** (integer) - Task ID for the installation

#### Response Example
{
  "code": 0,
  "data": {
    "task_id": 123
  }
}

### Authentication
- **ApiKeyAuth**: API key via `X-API-Key` header or `Authorization: Bearer <key>`
- **BearerAuth**: Bearer token via `Authorization: Bearer <token>`

### Server
http://localhost:5300
```

--------------------------------

### POST /api/v1/plugins/install/github

Source: https://langbot.app/docs/en/api-reference/plugins/install-a-plugin-from-github

This endpoint installs a plugin from a GitHub repository asynchronously. It requires a JSON body with the repository URL and returns a task ID for tracking the installation.

```APIDOC
## POST /api/v1/plugins/install/github

### Description
Install a plugin from a GitHub repository asynchronously and return the task ID.

### Method
POST

### Endpoint
/api/v1/plugins/install/github

### Parameters
#### Request Body
- **url** (string) - Required - GitHub repository URL

### Request Example
{
  "url": "https://github.com/rocksclawbot/langbot-community-plugins/tree/main/disaster-alert"
}

### Response
#### Success Response (200)
- **code** (integer) - Response code
- **data** (object) - Response data
  - **task_id** (integer) - Task ID

#### Response Example
{
  "code": 0,
  "data": {
    "task_id": 123
  }
}
```

--------------------------------

### Get configuration parameters with self.config.get

Source: https://langbot.app/docs/en/plugin/dev/components/knowledge-retriever

Use self.config.get(parameter_name, default_value) to retrieve user-configured values. The example shows how to get string, number, boolean, and select parameters with their default values.

```python
# Get string parameter
api_base_url = self.config.get('api_base_url', 'http://localhost:3000')

# Get number parameters
limit = self.config.get('limit', 5000)
similarity = self.config.get('similarity', 0.0)

# Get boolean parameter
using_rerank = self.config.get('using_rerank', False)

# Get select parameter
search_mode = self.config.get('search_mode', 'embedding')
```

--------------------------------

### Initialize plugin directory with lbp init

Source: https://langbot.app/docs/en/plugin/dev/tutor

Run inside the plugin directory to initialize the plugin structure. Follow prompts for Author, Description, etc.

```bash
lbp init
```

--------------------------------

### GET /api/v1/plugins

Source: https://langbot.app/docs/en/api-reference/plugins/list-installed-plugins

Retrieves the list of plugins installed on the LangBot instance. This endpoint requires authentication via API key or bearer token.

```APIDOC
## GET /api/v1/plugins

### Description
Lists the plugins installed on the LangBot instance.

### Method
GET

### Endpoint
/api/v1/plugins

### Authentication
- **X-API-Key** (header) - API key authentication
- **Authorization: Bearer <token>** (header) - Bearer token authentication

### Response
#### Success Response (200)
- **code** (integer) - Response code, e.g., 0
- **data** (object) - Response data
  - **plugins** (array of objects) - List of installed plugins

#### Response Example
{
  "code": 0,
  "data": {
    "plugins": []
  }
}
```

--------------------------------

### Call get_group_info platform API

Source: https://langbot.app/docs/en/plugin/dev/apis/platform

Example call to get group info. bot_uuid comes from await self.plugin.get_bots() or await event_context.get_bot_uuid() in a Pipeline event. Use platform IDs from real events or platform configuration.

```python
group = await self.plugin.call_platform_api(
    bot_uuid=bot_uuid,
    action="get_group_info",
    params={"group_id": "123456"},
)
```

--------------------------------

### Python: DashboardPage extending Page with handle_api

Source: https://langbot.app/docs/en/plugin/dev/components/page

Use this handler to process API requests from the frontend page. It reads the endpoint, method, and body from the request, and returns a PageResponse. The example checks for a GET request to '/stats' and returns the total entry count, otherwise returns a failure response.

```python
from langbot_plugin.api.definition.components.page import Page, PageRequest, PageResponse


class DashboardPage(Page):

    async def handle_api(self, request: PageRequest) -> PageResponse:
        # request.endpoint: API endpoint path, e.g. '/stats'
        # request.method:   HTTP method (GET, POST, PUT, DELETE)
        # request.body:     Request body (parsed JSON, or None)

        if request.endpoint == '/stats' and request.method == 'GET':
            # Read installation-scoped data from a Host storage API.
            entries = await self.load_entries_for_current_installation()
            return PageResponse.ok({'total': len(entries)})

        return PageResponse.fail(f'Unknown endpoint: {request.endpoint}')
```

--------------------------------

### Copy .env.example to .env on Windows

Source: https://langbot.app/docs/en/develop/dev-config

Copy the .env.example file to .env on Windows environments.

```bash
copy .env.example .env
```

--------------------------------

### Initialize plugin in subdirectory with lbp init HelloPlugin

Source: https://langbot.app/docs/en/plugin/dev/tutor

Alternative command to initialize the plugin in the subdirectory `HelloPlugin`.

```bash
lbp init HelloPlugin
```

--------------------------------

### Anti-pattern: Reading installation config during initialization

Source: https://langbot.app/docs/en/plugin/certified-plugins

Anti-pattern: reading installation config during initialization. Shared initialization has no installation configuration, so this reads empty or stale values.

```python
async def initialize(self):
    self.endpoint = self.plugin.config["endpoint"]  # process-scoped init has no active installation
    self.api_key = self.plugin.config["api_key"]
```

--------------------------------

### Copy .env.example to .env on Linux

Source: https://langbot.app/docs/en/develop/dev-config

Copy the .env.example file to .env on Linux and other Unix-like environments.

```bash
cp .env.example .env
```

--------------------------------

### Start Plugin Runtime with python -m langbot_plugin.cli.__init__ rt

Source: https://langbot.app/docs/en/develop/plugin-runtime

Start the Plugin Runtime. Accepts parameters such as --debug-only, --ws-debug-port (default 5401), --ws-control-port (default 5400), -s (use stdio only in production), and --skip-deps-check to skip dependency checks.

```bash
python -m langbot_plugin.cli.__init__ rt

```

--------------------------------

### GET /api/v1/provider/models/llm/{model_uuid}

Source: https://langbot.app/docs/en/api-reference/llm-models/get-an-llm-model

Retrieves a specific LLM model by its UUID using the GET /api/v1/provider/models/llm/{model_uuid} endpoint.

```APIDOC
## GET /api/v1/provider/models/llm/{model_uuid}

### Description
Retrieves a specific LLM model by its UUID.

### Method
GET

### Endpoint
/api/v1/provider/models/llm/{model_uuid}

### Parameters
#### Path Parameters
- **model_uuid** (string) - Required - The UUID of the LLM model to retrieve.

### Authentication
- **ApiKeyAuth** - API key authentication (header name and scheme as defined in the OpenAPI security schemes).
- **BearerAuth** - Bearer token authentication (header name and scheme as defined in the OpenAPI security schemes).

### Servers
- http://localhost:5300 - Use your own LangBot instance, not the documentation host.

### Response
#### Success Response (200)
- Returns the details of the requested LLM model.

#### Response Example
(No response example provided in the source documentation.)

### Error Handling
(No error responses are documented in the source.)
```

--------------------------------

### Deploy LangBot with uvx

Source: https://langbot.app/docs/en/articles/n8n-multi-platform-ai-chatbot

Run these commands in your workspace to create a LangBot instance and start it with uvx. On first launch, LangBot initializes automatically and opens http://127.0.0.1:5300 in your browser.

```bash
cd your-workspace
mkdir -p langbot-instance && cd langbot-instance
uvx langbot@latest
```

--------------------------------

### Serve demo page locally

Source: https://langbot.app/docs/en/usage/platforms/webpage

Serve the LangBot repo root statically, then open the demo page in a browser to preview the widget. The demo page loads the live embed widget and generates the exact script snippet to paste into your site.

```bash
# Serve the repo root statically, then open it in a browser
python3 -m http.server 8930
# Visit http://localhost:8930/examples/web-page-bot/
```

--------------------------------

### list_tools example

Source: https://langbot.app/docs/en/plugin/dev/apis/common

Lists all available tools in the current LangBot instance, including plugin tools and MCP tools. Each tool dict contains name, label, description, icon, and spec (which includes llm_prompt and parameters).

```python
async def list_tools(self) -> list[dict[str, Any]]:
    """List all available tools

    Returns:
        A list of tool dicts, each containing:
        - name: Tool name
        - label: Display label (i18n)
        - description: Tool description (i18n)
        - icon: Tool icon
        - spec: Tool specification (includes llm_prompt and parameters)
    """

# Example
tools = await self.plugin.list_tools()
for tool in tools:
    print(f"Tool: {tool['name']}")
```

--------------------------------

### Install pre-commit hooks

Source: https://langbot.app/docs/en/develop/agent-context

Installs pre-commit hooks so the same lint and format checks that CI runs are executed locally before each commit.

```bash
uv run pre-commit install
```

--------------------------------

### JSON translation file example

Source: https://langbot.app/docs/en/plugin/dev/components/page

Example of a flat JSON translation file with key-value pairs for the page's translatable strings.

```json
{
  "title": "Dashboard",
  "totalEntries": "Total Entries"
}
```

--------------------------------

### Run the interactive playground (playground.py)

Source: https://langbot.app/docs/en/usage/platforms/http-bot

Starts the interactive playground web app from the LangBot repo root. Requires the backend to be running and an enabled `http_bot` bot bound to a working pipeline; the app reads the API key and bot from `data/langbot.db` and points the bot's callback_url back at itself.

```bash
# From the LangBot repo root, with the backend running:
PUBLIC_IP=<your-host-ip> ./.venv/bin/python examples/http-bot/playground.py
# then open  http://<your-host-ip>:8920/
```

--------------------------------

### GET /api/v1/pipelines

Source: https://langbot.app/docs/en/api-reference/pipelines/list-all-pipelines

This snippet documents the GET /api/v1/pipelines endpoint, which lists all pipelines. It includes query parameters, response schema, and authentication details.

```APIDOC
## GET /api/v1/pipelines

### Description
List all pipelines.

### Method
GET

### Endpoint
/api/v1/pipelines

### Parameters
#### Query Parameters
- **sort_by** (string) - Optional - Default: `created_at`
- **sort_order** (string) - Optional - Enum: `ASC`, `DESC` - Default: `DESC`

### Response
#### Success Response (200)
- **code** (integer) - Example: `0`
- **data** (object)
  - **pipelines** (array of Pipeline)
    - **uuid** (string, uuid)
    - **name** (string)
    - **config** (object)
    - **is_default** (boolean)
    - **created_at** (string, date-time)
    - **updated_at** (string, date-time)

#### Response Example
```json
{
  "code": 0,
  "data": {
    "pipelines": [
      {
        "uuid": "string",
        "name": "string",
        "config": {},
        "is_default": true,
        "created_at": "2023-01-01T00:00:00Z",
        "updated_at": "2023-01-01T00:00:00Z"
      }
    ]
  }
}
```

### Authentication
- API Key: `X-API-Key: <key>` or `Authorization: Bearer <key>`
- Bearer Token: `Authorization: Bearer <token>`

### Server
`http://localhost:5300`
```

--------------------------------

### Install locally modified langbot-plugin-sdk

Source: https://langbot.app/docs/en/develop/plugin-runtime

Install the locally modified langbot-plugin-sdk into the LangBot virtual environment. Run in the langbot-plugin-sdk directory with the LangBot venv activated.

```bash
uv pip install .

```

--------------------------------

### Run plugin with lbp run

Source: https://langbot.app/docs/en/develop/plugin-runtime

Start the plugin from its project directory for debugging with the values set in .env. You can also pass the key with --plugin-debug-key '<debug key>' instead.

```bash
python -m langbot_plugin.cli.__init__ run

```

--------------------------------

### Start LangBot with standalone Box Runtime

Source: https://langbot.app/docs/en/develop/plugin-runtime

Starts LangBot in standalone mode with the standalone Box Runtime, connecting to the local endpoint configured in data/config.yaml.

```bash
python main.py --standalone-runtime --standalone-box
```

--------------------------------

### Add an EventListener component

Source: https://langbot.app/docs/en/plugin/dev/components/add

Example command to add an EventListener component. Follow the prompts to enter component configuration if any.

```bash
lbp comp EventListener
```

--------------------------------

### Install LangBot Beta 3 with uvx

Source: https://langbot.app/docs/en/deploy/langbot/package

Optional command to try Beta 3. --prerelease=allow permits prereleases of dependencies; --refresh refreshes cached package data.

```bash
uvx --prerelease=allow --refresh langbot==4.11.0b3
```
Tokens:
Raw