Installation

One-Line Install (Recommended)

The fastest way to get DjinnBot running. A single command installs all prerequisites, launches the setup wizard, and starts the stack:

curl -fsSL https://raw.githubusercontent.com/BaseDatum/djinnbot/main/install.sh | bash

The installer automatically detects your platform and installs everything needed. Then the setup wizard walks you through:

Supported platforms: Ubuntu, Debian, Fedora, CentOS/RHEL, Rocky/Alma, Amazon Linux, Arch, macOS (Intel and Apple Silicon).

Manual Install

If you prefer to set things up yourself:

Prerequisites

• Docker + Docker Compose — Install Docker Desktop (includes Compose)
• An LLM API key — OpenRouter is recommended (one key, access to all models)

That’s it. No Node.js, no Python, no database setup. Docker handles everything.

Clone & Configure

git clone https://github.com/BaseDatum/djinnbot.git
cd djinnbot
cp .env.example .env

Open .env in your editor and set your API key:

# Required — this is the only thing you must set
OPENROUTER_API_KEY=sk-or-v1-your-key-here

Generate Secrets

For production deployments, generate all required secrets:

# Encryption key for secrets at rest (AES-256-GCM)
python3 -c "import secrets; print('SECRET_ENCRYPTION_KEY=' + secrets.token_hex(32))" >> .env

# Internal service-to-service auth token
python3 -c "import secrets; print('ENGINE_INTERNAL_TOKEN=' + secrets.token_urlsafe(32))" >> .env

# JWT signing key for user authentication
python3 -c "import secrets; print('AUTH_SECRET_KEY=' + secrets.token_urlsafe(64))" >> .env

Enable Authentication

To enable the built-in authentication system, set in .env:

AUTH_ENABLED=true

When enabled, the dashboard will redirect to a setup page on first visit where you create an admin account and optionally enable two-factor authentication. See Security Model for details.

Start Services

docker compose up -d

This starts 6 services:

Check that everything is healthy:

docker compose ps

You should see all services running with healthy status.

SSL/TLS with Traefik

For production deployments exposed to the internet, DjinnBot includes a Traefik reverse proxy with automatic Let’s Encrypt certificates.

The setup wizard configures this automatically when you choose SSL. To set it up manually:

Requirements:

• A domain name with an A record pointing to your server
• Ports 80 and 443 accessible from the internet

Configuration:

1. Set environment variables in .env:

DOMAIN=djinn.example.com
BIND_HOST=127.0.0.1          # Only Traefik faces the internet
TRAEFIK_ENABLED=true
VITE_API_URL=https://djinn.example.com

2. Create proxy/.env:

ACME_EMAIL=you@example.com
DOMAIN=djinn.example.com

3. Create the shared Docker network and start the proxy:

docker network create djinnbot-proxy
docker compose -f proxy/docker-compose.yml up -d

4. Start the main stack (it picks up docker-compose.override.yml automatically):

docker compose up -d

Traefik handles:

• Automatic certificate issuance and renewal via Let’s Encrypt
• HTTP to HTTPS redirection
• Routing /v1/* to the API and everything else to the dashboard
• SSE streaming support with proper flush intervals

Verify

Open the dashboard:

http://localhost:3000

If authentication is enabled, you’ll be redirected to the setup page to create your admin account.

Check the API:

curl http://localhost:8000/v1/status

You should see a JSON response with "status": "ok" and connected service counts.

What Just Happened

Docker Compose built and started the entire stack:

1. PostgreSQL stores pipeline runs, steps, agent state, project boards, user accounts, and settings
2. Redis provides the event bus via Redis Streams — reliable, ordered message delivery between services
3. API Server (FastAPI/Python) exposes REST endpoints for the dashboard, CLI, and external integrations, with optional JWT authentication
4. Pipeline Engine (TypeScript/Node) runs the state machine that coordinates agent execution, spawns agent containers, manages memory, and bridges messaging platforms (Slack, Discord, Telegram, Signal, WhatsApp)
5. Dashboard (React/Vite) serves the web interface with real-time SSE streaming, authentication pages, and project management
6. mcpo proxies MCP tool servers (GitHub, web fetch, etc.) as OpenAPI endpoints for agents

When a pipeline runs, the engine dynamically spawns agent containers — isolated Docker containers with a full engineering toolbox — for each step. These are separate from the 6 core services and are created/destroyed per step.

Next Steps