Ecbot Docs
Getting started

Installation

Run Ecbot on your own machine or server. Install the tools, fill the env files with one command, start the Docker services and run the apps.

Ecbot is open source, so you can run the whole stack yourself: the API, the web app and the AI service, backed by Postgres, Redis and a Cloud Tasks emulator in Docker. A setup script fills in the configuration, so a fresh checkout can be running in about 15 minutes. If you only want to use Ecbot, set up your shop on the hosted version instead.

Requirements

  • Node.js 22 and pnpm 9 (corepack enable).
  • Docker with Docker Compose.
  • Python 3.12 or newer and uv, for the AI service.
  • An OpenRouter API key.

Get the code and install

git clone https://github.com/blackmouse572/ecbot.git
cd ecbot
pnpm install

Create the env files

pnpm setup:local

The script creates .env for the API, the web app and the AI service from their .env.example files. It generates the JWT keys, internal secrets and matching API keys for you, and asks only for values you must supply, such as the OpenRouter key. It never overwrites a value you already set, so it is safe to run again. Use pnpm setup:local --check to list what is still missing. See Configuration for every variable.

Start the services

docker compose up -d

This starts Postgres with pgvector (5432), Redis (6379), the JWKS server (3011), the Bull board (3010) and the Cloud Tasks emulator (8123).

Create the database

pnpm db:migrate:up
pnpm db:seed

Run the apps

pnpm dev:app                     # API on :8080 and web app on :5173
cd apps/ai && uv sync && pnpm dev   # AI service on :8000

Open http://localhost:5173 and log in with a seed user.

Background jobs

Knowledge processing, emails and follow-ups run as Cloud Tasks. To run them locally, uncomment CLOUD_TASKS_EMULATOR_HOST=localhost:8123 in apps/api/.env. The emulator runs in Docker and calls the API back at API_BACKEND_URL, so that address must be reachable from inside the container (on Linux, use the Docker bridge address rather than localhost).

Run everything in Docker

The compose file also has profiles that run the apps in containers: docker compose --profile app up -d adds the API and web app, and --profile full adds the AI service too.

Frequently asked questions

Set up your shop

Create an Ecbot account and workspace, build your first agent with the agent builder, and test it before any customer sees it.

Agents

The agent builder turns a short description of your business into a working agent by asking one question at a time about tone, facts and rules.

On this page

RequirementsGet the code and installCreate the env filesStart the servicesCreate the databaseRun the appsBackground jobsRun everything in Docker