Quick Start

Get Beai running on your infrastructure in under 5 minutes using the CLI.

Prerequisites

  • Docker — Docker Engine 24+ with Docker Compose v2
  • Node.js — 18.x or later (for the CLI)
  • At least one AI provider API key (OpenAI, Anthropic, or OpenRouter)
  • A TypeSafe API key for Jev, which judges which answers mention your brand and their sentiment, or an OpenRouter key to call Jev through OpenRouter. Very roughly $0.15–0.35 per 1,000 answers, about $2–4 a month for 25 daily prompts on 3 platforms (pricing by volume)
  • (Recommended) A scraping provider to track the real ChatGPT and Google AI Mode experiences — see Providers

Install the CLI

npm install -g @elmohq/cli

Initialize Your Instance

Run the interactive setup wizard:

elmo init

The wizard walks you through:

  1. Config directory — Where to store your elmo.yaml and .env files (default: ./elmo)
  2. PostgreSQL — Run Postgres in Docker (recommended) or provide an existing DATABASE_URL
  3. AI Providers — Configure scrapers (Cloro, BrightData, Oxylabs, SearchApi, Olostep, DataForSEO) and/or direct model APIs (OpenAI, Anthropic, Mistral, OpenRouter); see Providers for details
  4. Access — Use Beai on this machine (localhost), or from a domain behind a reverse proxy (see Serving Beai from a Domain)
  5. Start — Optionally start the stack immediately

Once complete, Beai generates two files in your config directory:

FilePurpose
elmo.yamlDocker Compose configuration for all services
.envEnvironment variables, secrets, and API keys

Start Beai

If you didn't start during init, bring everything up with:

elmo compose up -d

This pulls the Docker images and starts all services. Once they report healthy, open http://localhost:1515 in your browser.

System Architecture

Beai system architecture: User connects to Web; Web and Worker share a Postgres database; Web calls LLM APIs; Worker calls both LLM APIs and an LLM Scraper.
ServiceRole
WebDashboard UI and REST API
WorkerBackground scheduler that drives prompt runs
PostgresShared database and job queue
LLM APIsDirect API calls (OpenAI, Anthropic, OpenRouter)
LLM ScraperScrapers for ChatGPT, Google AI Mode, and other live AI surfaces (Cloro, BrightData, Oxylabs, SearchApi, Olostep, DataForSEO)
Beai CLIGenerates elmo.yaml + .env and runs docker compose

CLI Commands Reference

Once Beai is running, these commands help you manage it:

# View live logs
elmo compose logs -f

# View logs for a specific service
elmo compose logs -f web

# Check service status
elmo compose ps

# Stop all services
elmo compose down

What's Next

With Beai running, head to the User Guide to create your first brand, configure prompts, and start tracking AI visibility.

Was this page helpful?

Edit this page·View as Markdown·Report an issue·Join our Discord