Installation

Don’t want to read all this?

Just drop a link to https://xedant.com/agents/chatbot/install.md or to https://xedant.com/llms.txt into any AI chat (Claude, ChatGPT, etc.) and ask it to generate the config files and commands. It will read the docs, ask you a few questions about your setup, and hand you a ready-to-use configuration. Save time — let the model do the reading for you.

You can also reach me on Telegram — I’m always glad to help. And that’s not just politeness — I genuinely enjoy talking to like-minded people, especially if you love coding as much as I do.

Chatbot Agent is a program for building AI chatbots that you run on your own server. It deploys as a single Docker container and keeps everything in two permanent volumes: /apps/chatbot — the database, the media library and the knowledge bases, /project/apps/chatbot — bot files and scripts. No separate database server is needed: the built-in SQLite works out of the box, and PostgreSQL connects optionally.

Minimum requirements

Any Linux host with Docker is enough (an inexpensive VPS, for example). Everything else is already built into the image:

• the application web server (ASP.NET Core 9 runtime);
• an SQLite database — works without any setup;
• the Telegram emulator — you can build and check bots without creating a real bot or connecting to the messenger;
• for the chat with the AI agent you will need the address and API key of your Xedant Agent — but that is optional: without them everything works except the agent chat.

The application is sparing with server resources. While idle the processor is not loaded: background handlers do not poll the database on a timer — they wake up when there is work. After 15 minutes without activity the memory in use is released — the knowledge-base search snapshots, the analytics cache and other service data; everything comes back on its own at the next request. That is why Chatbot Agent sits comfortably alongside other services on one server. Nothing needs to be configured; if you wish, the deadline is set in the settings.yml file in the settings folder — in the memory block, the idleTrimMinutes field (0 disables the trim).

Docker Compose

Create a compose.yml file and run docker compose up -d:

services:
  chatbotagent:
    image: xedant/chatbot-agent:min-latest
    container_name: chatbotagent
    ports:
      - "3978:80"
    volumes:
      - chatbotagent-data:/apps/chatbot
      - chatbotagent-config:/project/apps/chatbot
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ASPNETCORE_URLS=http://+:80
      - CHATBOT_APP_DATA=/apps/chatbot
      - CHATBOT_APP_CONFIG_FOLDER=/project/apps/chatbot
      # Optional link to Xedant Agent (without these lines the agent chat is hidden):
      # - AGENT_API_URL=https://your-agent-host
      # - AGENT_API_KEY=your-agent-API-key
      # Serve from a first-level subfolder (for example, /chatbot):
      # - CHATBOT_APP_BASE_PATH=/chatbot
    restart: unless-stopped
    sysctls:
      fs.inotify.max_user_watches: "524288"
      fs.inotify.max_user_instances: "512"

volumes:
  chatbotagent-data:
  chatbotagent-config:

After startup the interface is available on port 3978: http://<server-address>:3978.

The two sysctls lines raise the system file-watching limits — they are needed so edits to scenarios and scripts are picked up instantly, without a restart. Without them, on large projects some changes may not reach the application.

Environment variables

Application settings are passed through environment variables — a convenient way to set them once in compose.yml and change them without touching the code:

Variable	Purpose	Default
CHATBOT_APP_BRAND	brand and interface language: xedant (English) or pastukhov (Russian)	xedant
CHATBOT_APP_DATA	data folder (inside the container — /apps/chatbot)	/apps/chatbot
CHATBOT_APP_DB	PostgreSQL connection string; empty value — the built-in SQLite	SQLite (/apps/chatbot/data.db)
CHATBOT_APP_BASE_PATH	serve from a first-level subfolder (for example, /chatbot)	— (domain root)
CHATBOT_APP_LOGIN	login of a pre-configured user; together with the password below, creates the administrator at startup	— (self-registration)
CHATBOT_APP_PASSWORD	lowercase SHA-256 hash of the password, not the password itself	—
AGENT_API_URL	address of Xedant Agent for the chat with the AI agent	— (agent chat hidden)
AGENT_API_KEY	access key to your Xedant Agent	—
AGENT_LICENSE	license key, so you do not have to enter it by hand in the interface	— (no license in the image)
CHATBOT_APP_HASH	SHA-256 hex of the management key: the AI agent uses it to manage bots over the API; empty — disabled	— (API management disabled)
CHATBOT_APP_CONFIG_FOLDER	folder with bot files (settings and scenarios in YAML format)	/project/apps/chatbot
CHATBOT_APP_SCRIPTS_FOLDER	folder with bot Python scripts	/project/apps/chatbot/scripts
CHATBOT_APP_PYTHON	which Python program executes your scripts (when not set, taken from the scripts environment)	from the scripts environment
CHATBOT_APP_VENV	folder of the separate Python environment for script libraries	/apps/chatbot/venv
CHATBOT_APP_DOCS_FOLDER	documents folder for the file manager	/project/docs
CHATBOT_APP_SSL	self-signed HTTPS: auto — enable; companions _SSL_PORT and _SSL_DOMAINS	— (HTTP only)
JWT_SECRET_KEY	secret for signing sign-in sessions (set automatically by MultiAgent)	key in /apps/chatbot/keys
SSO_PROXY_TOKEN	sign-in through an external SSO proxy (set automatically by MultiAgent)	— (disabled)
CHATBOT_APP_ERROR_REPORTING	0 — disable error reporting	— (reporting is off anyway: no receiving address is configured)

Note: CHATBOT_APP_PASSWORD contains not the password but its lowercase SHA-256 hash — a “fingerprint” from which the password cannot be recovered. Compute it with echo -n your-password | sha256sum. On sign-in the application hashes the entered password and compares it with the configured value. The management key works the same way: CHATBOT_APP_HASH holds not the key itself but its hexadecimal hash — computed by the same sha256sum command.

Data storage

All permanent data survives container recreation. The application’s data lives in the /apps/chatbot volume:

• /apps/chatbot/data.db — the SQLite database (when PostgreSQL is not used);
• /apps/chatbot/auth/ — data protection keys;
• /apps/chatbot/keys/ — the sign-in session signing key;
• /apps/chatbot/bot-media/<bot>/ — the bots’ media library: pictures and files from dialogues;
• /apps/chatbot/kb/ — knowledge base files (the documents AI answers from);
• /apps/chatbot/venv/ — the Python environment where your scripts run (the libraries for them are listed in the scripts-requirements.txt file in the root of the settings folder);
• /apps/chatbot/.xedant/license.txt — the activated license key (for the pastukhov brand — the .pastukhov folder).

Bot files and scripts live separately — in the /project/apps/chatbot volume: settings and scenarios in the bots/ folder, your own Python scripts in scripts/. It is the same directory as in the developer’s project, so a bot’s folder can be copied there as a whole.

The volumes are mandatory: without them you lose the database, the media library, the knowledge bases and the bot files on the very first docker compose down. And the important advantage: all of it is plain files — you can see them, copy them and move them to another server.

First sign-in

Open the interface in a browser. While the database has no users, the registration form is open by itself — the first person to register becomes the administrator. If the login and password are set with environment variables, sign in with them (the variable holds the hash; at sign-in you enter the password itself). A sign-in session lasts 90 days. Right after signing in you can change the interface language and theme in the settings. Details in the Getting Started section.

Setup after launch

Create your first bot — a name and a token from @BotFather. No real bot yet? That is not a problem: a test bot can be built and checked right on the built-in emulator. Then assemble the scenario in the studio and test it: details in the Bots, Flow Studio and Emulator sections.

If you like, connect Xedant Agent — the chat with the AI agent appears, and you can delegate edits in plain words. Details in the Chat with the AI Agent section.

Running without Compose

You can also start the application with a single docker run command:

docker run -d \
  --name chatbotagent \
  -p 3978:80 \
  -v chatbotagent-data:/apps/chatbot \
  -v chatbotagent-config:/project/apps/chatbot \
  -e CHATBOT_APP_DATA=/apps/chatbot \
  -e CHATBOT_APP_CONFIG_FOLDER=/project/apps/chatbot \
  --sysctl fs.inotify.max_user_watches=524288 \
  --sysctl fs.inotify.max_user_instances=512 \
  --restart unless-stopped \
  xedant/chatbot-agent:min-latest

The remaining environment variables can be passed from a file with the --env-file .env flag — more convenient when there are many settings.

Installing through Xedant MultiAgent

If you have several servers and applications, it is more convenient to install Chatbot Agent from Xedant MultiAgent: the product is in the list of new agents. MultiAgent raises the container itself, gives it a permanent address and HTTPS, connects the PostgreSQL database and the shared documents volume, and links the application with the selected AI agent — nothing needs to be configured by hand. The default port is 6050. Details on the MultiAgent page.

License

The license key is activated in the license dialog or passed with the AGENT_LICENSE variable at startup. No ready license ships in the image: a fresh container starts without one. Without a license everything works — bots, the studio, the emulator, testing, the knowledge base, operators, the chat room, the widget, broadcasts and analytics. The license is needed only for sending messages to the chat with the AI agent. Details on the Licensing page.

← Back to the Chatbot Agent home