{"id":45388030,"url":"https://github.com/basedatum/djinnbot","last_synced_at":"2026-03-04T17:02:26.314Z","repository":{"id":339684813,"uuid":"1162966784","full_name":"BaseDatum/DjinnBot","owner":"BaseDatum","description":"Containerized Opinionated Agent Orchestration Platform","archived":false,"fork":false,"pushed_at":"2026-02-27T00:48:39.000Z","size":4359,"stargazers_count":5,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T05:23:30.287Z","etag":null,"topics":["agents","ai","cli","docker","llm","openclaw","openclaw-killer","orchestration","python","shadcn","typer"],"latest_commit_sha":null,"homepage":"https://docs.djinn.bot/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BaseDatum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-20T23:01:51.000Z","updated_at":"2026-02-27T01:31:19.000Z","dependencies_parsed_at":"2026-02-27T01:02:28.187Z","dependency_job_id":null,"html_url":"https://github.com/BaseDatum/DjinnBot","commit_stats":null,"previous_names":["basedatum/djinnbot"],"tags_count":60,"template":false,"template_full_name":null,"purl":"pkg:github/BaseDatum/DjinnBot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaseDatum%2FDjinnBot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaseDatum%2FDjinnBot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaseDatum%2FDjinnBot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaseDatum%2FDjinnBot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BaseDatum","download_url":"https://codeload.github.com/BaseDatum/DjinnBot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaseDatum%2FDjinnBot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29959284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T01:47:18.291Z","status":"online","status_checked_at":"2026-03-01T02:00:07.437Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","cli","docker","llm","openclaw","openclaw-killer","orchestration","python","shadcn","typer"],"created_at":"2026-02-21T18:05:52.439Z","updated_at":"2026-03-01T03:05:10.194Z","avatar_url":"https://github.com/BaseDatum.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DjinnBot\n\n**Autonomous AI teams that build software while you sleep.**\n\nDjinnBot is an open-core agent orchestration platform that deploys a full team of AI agents — product owner, architect, engineers, QA, SRE, and more — to collaboratively execute software development workflows. Each agent has a distinct persona, persistent memory, and its own Slack presence. Define a task, kick off a pipeline, and watch your AI team spec, design, implement, review, test, and deploy — autonomously.\n\nSelf-hosted is free. One command to install, one command to run.\n\n**Docs:** [docs.djinn.bot](https://docs.djinn.bot) | **License:** [FSL-1.1-ALv2](LICENSE) (free to use, converts to Apache 2.0 after 2 years)\n\n---\n\n## Why DjinnBot\n\n- **Plug and play.** One `curl` command installs everything. The setup wizard handles secrets, API keys, Docker, and optional SSL. No Kubernetes, no cloud accounts, no 45-minute setup guides.\n- **Fully containerized.** Every agent runs in its own isolated Docker container with a full engineering toolbox (Node, Python, Go, Rust, git, ripgrep, GitHub CLI, and dozens more). No host access, no security concerns.\n- **Real team, not a chatbot.** Agents have personas, opinions, and memory. Eric (Product Owner) pushes back on vague specs. Finn (Architect) rejects PRs that violate architecture. Chieko (QA) finds the edge cases you forgot.\n- **Persistent memory.** Agents remember decisions, lessons, and patterns across runs using ClawVault with semantic search. They learn and improve over time.\n- **Beautiful dashboard.** Real-time streaming output, live agent sessions, project management with kanban boards, chat interface, and pipeline visualization — not a terminal dump.\n- **Slack-native.** Each agent gets its own Slack bot. Watch your team discuss in threads. Mention an agent to get their perspective. Or skip Slack entirely and use the built-in chat.\n- **YAML pipelines.** Define workflows as simple YAML — steps, agents, branching, loops, retries. No code required for orchestration.\n- **MCP tools.** Agents can use any MCP-compatible tool server via the built-in mcpo proxy. Add GitHub, web search, or any custom tool with a single config entry.\n- **Built-in auth.** User accounts with email/password, TOTP two-factor authentication, API keys, and optional OIDC single sign-on. Enable with one toggle for production deployments.\n- **Open core.** Self-hosted is completely free. Use it, modify it, run it on your own infra. SaaS option coming for teams that don't want to manage infrastructure.\n\n---\n\n## Quick Start\n\n### One-Line Install (Recommended)\n\nThe installer handles everything — Docker, Python, the CLI, cloning the repo, generating secrets, configuring your first model provider, optional SSL, and starting the stack:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/BaseDatum/djinnbot/main/install.sh | bash\n```\n\nThis installs prerequisites (Docker, Python 3.11+, git), installs the `djinn` CLI, and launches the interactive setup wizard which walks you through:\n\n1. Cloning the DjinnBot repository\n2. Generating encryption keys and secrets\n3. Choosing a model provider and entering your API key\n4. Detecting your server IP and configuring network access\n5. Optional SSL/TLS setup with Traefik (automatic Let's Encrypt certificates)\n6. Starting the Docker stack\n\nWorks on **Linux** (Ubuntu, Debian, Fedora, CentOS, Arch, Amazon Linux) and **macOS** (Intel and Apple Silicon).\n\n### Manual Install\n\nIf you prefer to set things up yourself:\n\n```bash\ngit clone https://github.com/BaseDatum/djinnbot.git\ncd djinnbot\ncp .env.example .env\n```\n\nEdit `.env` and add your API key:\n\n```bash\nOPENROUTER_API_KEY=sk-or-v1-your-key-here\n```\n\nGenerate required secrets:\n\n```bash\npython3 -c \"import secrets; print('SECRET_ENCRYPTION_KEY=' + secrets.token_hex(32))\" \u003e\u003e .env\npython3 -c \"import secrets; print('ENGINE_INTERNAL_TOKEN=' + secrets.token_urlsafe(32))\" \u003e\u003e .env\npython3 -c \"import secrets; print('AUTH_SECRET_KEY=' + secrets.token_urlsafe(64))\" \u003e\u003e .env\n```\n\nStart services:\n\n```bash\ndocker compose up -d\n```\n\nThis starts 6 services: PostgreSQL, Redis, API server, pipeline engine, dashboard, and the mcpo tool proxy.\n\n### First Visit\n\n| Service | URL |\n|---------|-----|\n| Dashboard | http://localhost:3000 |\n| API | http://localhost:8000 |\n| MCP Tools | http://localhost:8001 |\n\nWhen authentication is enabled (`AUTH_ENABLED=true`), the dashboard redirects you to a setup page on first visit where you create your admin account and optionally enable two-factor authentication.\n\n### CLI\n\nInstall the CLI to manage agents, providers, authenticate, and chat from the terminal:\n\n```bash\npip install djinn-bot-cli\ndjinn --help\n```\n\nLog in and chat with agents:\n\n```bash\ndjinn login                         # email/password + optional 2FA\ndjinn chat                          # interactive agent + model selection\ndjinn whoami                        # show current user\n```\n\nRun the setup wizard anytime:\n\n```bash\ndjinn setup                         # interactive setup (safe to re-run)\n```\n\nConfigure model provider API keys:\n\n```bash\ndjinn provider set-key anthropic\ndjinn provider set-key openrouter\n```\n\nSee the [CLI reference](https://docs.djinn.bot/docs/reference/cli/) for all commands.\n\n---\n\n## Architecture\n\n```\n┌──────────────────┐     ┌──────────────────┐     ┌──────────────┐\n│    Dashboard     │◄SSE─│   API Server     │────►│  PostgreSQL  │\n│  (React + Vite)  │     │   (FastAPI)      │     │              │\n└──────────────────┘     └──────┬───────────┘     └──────────────┘\n                                │\n                                ▼\n                        ┌──────────────┐\n                        │    Redis     │\n                        │(Streams+Pub/ │\n                        │    Sub)      │\n                        └──────┬───────┘\n                               │\n              ┌────────────────┼────────────────┐\n              │                │                │\n              ▼                ▼                ▼\n     ┌────────────────┐ ┌──────────┐  ┌──────────────┐\n     │Pipeline Engine │ │  Agent   │  │  Agent       │\n     │(State Machine) │ │Container │  │  Container   │\n     └───────┬────────┘ │(Isolated)│  │  (Isolated)  │\n             │          └────┬─────┘  └──────┬───────┘\n             │               │               │\n             ▼               ▼               ▼\n     ┌──────────────┐  ┌──────────────────────────┐\n     │  Slack       │  │     mcpo Proxy            │\n     │  Bridge      │  │  (MCP → Native Tools)     │\n     └──────────────┘  └──────────────────────────┘\n```\n\n**How it works:**\n\n1. **Create a project** — describe what you want built via the dashboard's guided onboarding, or import an existing repo\n2. **Plan it** — the planning pipeline decomposes your project into tasks on a kanban board with priorities and dependencies\n3. **Assign agents** — each agent is assigned to project board columns matching their role (e.g., Yukihiro watches \"Ready\", Chieko watches \"Review\")\n4. **Agents work autonomously** — on pulse cycles, agents wake up, check the board, claim a task, spin up an isolated container, do the work, open a PR, and move the task forward\n5. **Watch it happen** — streaming output in the dashboard, Slack threads, or the kanban board. Step in when you want, or let them run\n\nPipelines also exist for structured workflows — the planning pipeline generates tasks, the engineering pipeline runs a full SDLC for a single task, and you can create custom pipelines for any repeatable process.\n\nEach agent runs in a fully isolated Docker container — its own filesystem, git workspace, installed tools, and network. No host access.\n\n---\n\n## The Team\n\nDjinnBot ships with a default software engineering team. Each agent has a rich persona with backstory, opinions, communication style, and domain expertise:\n\n| Agent | Role | Pipeline Stage |\n|-------|------|---------------|\n| **Eric** | Product Owner | SPEC — Requirements, user stories, acceptance criteria |\n| **Finn** | Solutions Architect | DESIGN, REVIEW — Architecture, tech decisions, code review |\n| **Shigeo** | UX Specialist | UX — User flows, design systems, accessibility |\n| **Yukihiro** | Senior Software Engineer | IMPLEMENT, FIX — Writing code, fixing bugs |\n| **Chieko** | Senior Test Engineer | TEST — QA, testing, regression detection |\n| **Stas** | Site Reliability Engineer | DEPLOY — Infrastructure, monitoring, deployment |\n| **Yang** | DevEx Specialist | DX — CI/CD, tooling, developer workflow |\n| **Holt** | Marketing \u0026 Sales Lead | On-demand — Sales, outreach, positioning |\n| **Luke** | SEO Specialist | On-demand — Content strategy, keyword research |\n| **Jim** | Business \u0026 Finance Lead | On-demand — Budget, pricing, runway |\n\n\u003e Agents are assigned to projects and kanban columns. On pulse cycles, they autonomously pick up tasks, do the work, open PRs, and advance tasks through the board. Marketing, sales, and finance agents work in chat and pulse modes. More project types are coming.\n\n---\n\n## Pipelines\n\nPipelines are YAML files that define structured multi-step workflows. They power project planning, guided onboarding, and predefined SDLC passes:\n\n| Pipeline | Description |\n|----------|------------|\n| `engineering` | Full SDLC: spec → design → UX → implement → review → test → deploy |\n| `feature` | Lightweight: design → implement → review → test |\n| `bugfix` | Focused: diagnose → fix → validate |\n| `planning` | Project decomposition into tasks with dependency chains |\n| `execute` | Run a single task from a project board |\n\n### Example: Engineering Pipeline Flow\n\n```\nSPEC (Eric) → DESIGN (Finn) → UX (Shigeo) → IMPLEMENT (Yukihiro)\n                                                    ↕\n                                              REVIEW (Finn)\n                                                    ↕\n                                               TEST (Chieko)\n                                                    ↓\n                                              DEPLOY (Stas)\n```\n\nSteps support **loops** (implement each task in a breakdown), **branching** (approved vs. changes requested), **retries**, and **template variables** that pass outputs between agents.\n\n---\n\n## Agent Anatomy\n\nEach agent is defined by a directory under `agents/`:\n\n```\nagents/eric/\n├── IDENTITY.md      # Name, origin, role, emoji\n├── SOUL.md          # Personality, beliefs, anti-patterns, communication style\n├── AGENTS.md        # Workflow procedures, collaboration triggers, tools\n├── DECISION.md      # Memory-first decision framework\n├── PULSE.md         # Autonomous wake-up routine (check inbox, find tasks, work)\n├── config.yml       # Model, pulse schedule, thinking settings\n└── slack.yml        # Slack bot credentials (optional)\n```\n\nAgents also have access to **skills** — on-demand instruction sets loaded via `load_skill(\"name\")` — and **MCP tools** — external tool servers accessed through the mcpo proxy.\n\n---\n\n## Memory System\n\nDjinnBot uses [ClawVault](https://github.com/koi-labs-org/clawvault) for persistent agent memory with semantic search powered by QMDR:\n\n- **Personal vaults** — Each agent has private memory for lessons, decisions, patterns, and preferences\n- **Shared vault** — Team-wide knowledge that all agents can access\n- **Wiki-link graph** — Memories are connected via `[[Topic]]` links for graph traversal\n- **Semantic search** — `recall(\"query\")` finds relevant memories by meaning, not just keywords\n- **Automatic lifecycle** — Memory is loaded on wake, checkpointed during work, and saved on sleep\n\nEmbeddings and reranking run through OpenRouter (using `text-embedding-3-small` and `gpt-4o-mini`) — no local GPU required.\n\n---\n\n## Slack Integration\n\nEach agent can have its own Slack bot, appearing as a distinct team member in your workspace. Agents post updates to threads, respond to mentions, and collaborate in channels.\n\nSlack is **optional**. The built-in dashboard chat works without any Slack configuration. See the [docs](https://docs.djinn.bot) for setup instructions.\n\n---\n\n## MCP Tools\n\nDjinnBot includes an [mcpo](https://github.com/skymoore/mcpo) proxy that exposes MCP tool servers as OpenAPI endpoints. Agents call tools like `github`, `fetch`, `time`, and any custom MCP server you add.\n\nTools are configured in `mcp/config.json` and can be managed through the dashboard UI. The proxy supports hot-reload — add a tool server and agents can use it immediately, no restart needed.\n\n---\n\n## LLM Providers\n\nDjinnBot supports all major providers through [pi-mono](https://github.com/badlogic/pi-mono):\n\n| Provider | Env Variable |\n|----------|-------------|\n| OpenRouter (recommended) | `OPENROUTER_API_KEY` |\n| Anthropic | `ANTHROPIC_API_KEY` |\n| OpenAI | `OPENAI_API_KEY` |\n| Google (Gemini) | `GEMINI_API_KEY` |\n| xAI (Grok) | `XAI_API_KEY` |\n| Groq | `GROQ_API_KEY` |\n| Mistral | `MISTRAL_API_KEY` |\n| Azure OpenAI | `AZURE_OPENAI_API_KEY` |\n| Amazon Bedrock | AWS credentials |\n| Google Vertex | GCP ADC |\n| Custom (OpenAI-compatible) | Via settings UI |\n\nConfigure providers in `.env` or through the dashboard settings page. Each agent can use a different model — put your architect on Claude Opus and your engineer on Kimi K2.5.\n\n---\n\n## Tech Stack\n\n| Component | Technology |\n|-----------|-----------|\n| Pipeline Engine | TypeScript, Redis Streams |\n| API Server | Python, FastAPI, PostgreSQL, SQLAlchemy, JWT auth |\n| Dashboard | React, Vite, TanStack Router, Tailwind CSS |\n| Agent Runtime | Node.js 22, Debian (full toolbox) |\n| Memory | ClawVault + QMDR (semantic search) |\n| Agent Framework | pi-mono (pi-agent-core) |\n| Slack | Bolt.js, Socket Mode |\n| MCP Proxy | mcpo (hot-reload) |\n| Build | Turborepo monorepo |\n| Orchestration | Docker Compose |\n\n---\n\n## Project Structure\n\n```\ndjinnbot/\n├── agents/                     # Agent persona definitions\n│   ├── _templates/             # Shared templates (AGENTS.md, PULSE.md, etc.)\n│   ├── _skills/                # Global skills (available to all agents)\n│   ├── eric/                   # Product Owner\n│   ├── finn/                   # Solutions Architect\n│   ├── shigeo/                 # UX Specialist\n│   ├── yukihiro/               # Senior SWE\n│   ├── chieko/                 # Test Engineer\n│   ├── stas/                   # SRE\n│   ├── yang/                   # DevEx\n│   ├── holt/                   # Marketing \u0026 Sales\n│   ├── luke/                   # SEO\n│   └── jim/                    # Finance\n├── pipelines/                  # YAML pipeline definitions\n├── packages/\n│   ├── core/                   # Engine, events, memory, container management\n│   ├── server/                 # FastAPI API server (Python)\n│   ├── dashboard/              # React dashboard (TypeScript)\n│   ├── slack/                  # Slack bridge and per-agent bots\n│   └── agent-runtime/          # Agent container entrypoint + tools\n├── mcp/                        # MCP tool server config\n├── cli/                        # Python CLI (pip install djinn-bot-cli)\n├── proxy/                      # Traefik reverse proxy for SSL\n├── install.sh                  # One-shot installer script\n├── docker-compose.yml\n├── Dockerfile.engine\n├── Dockerfile.server\n├── Dockerfile.dashboard\n└── Dockerfile.agent-runtime\n```\n\n---\n\n## Development\n\nFor local development (not Docker):\n\n**Requirements:** Node.js 20+, Python 3.12+, PostgreSQL, Redis\n\n```bash\n# Install dependencies\nnpm install\ncd packages/server \u0026\u0026 pip install -e \".[dev]\" \u0026\u0026 cd ../..\ncd cli \u0026\u0026 uv sync --all-extras \u0026\u0026 cd ..\n\n# Start services\nredis-server \u0026\n# Start PostgreSQL\n\n# Run API server\ncd packages/server \u0026\u0026 uvicorn app.main:app --reload --port 8000\n\n# Run engine (separate terminal)\ncd packages/core \u0026\u0026 npm run build \u0026\u0026 node dist/main.js\n\n# Run dashboard (separate terminal)\ncd packages/dashboard \u0026\u0026 npm run dev\n```\n\n---\n\n## Roadmap\n\n- **RBAC \u0026 team management** — Role-based access control with granular permissions per project\n- **Marketing \u0026 sales pipelines** — Structured workflows for content, outreach, and deal management\n- **More bot interfaces** — Discord, Microsoft Teams, and other platforms beyond Slack\n- **SaaS offering** — Managed hosting at djinn.bot for teams that don't want to self-host\n- **Pipeline marketplace** — Share and discover community pipeline templates\n- **Custom agent builder** — Create new agents with custom personas through the UI\n\n---\n\n## License\n\n[FSL-1.1-ALv2](LICENSE) — Functional Source License with Apache 2.0 future grant.\n\n**What this means:** You can use, modify, and self-host DjinnBot for free. The only restriction is you can't use it to build a competing commercial product. After 2 years, every release automatically converts to Apache 2.0 with no restrictions.\n\n---\n\n## Links\n\n- **Documentation:** [docs.djinn.bot](https://docs.djinn.bot)\n- **Website:** [djinn.bot](https://djinn.bot)\n- **GitHub:** [github.com/BaseDatum/djinnbot](https://github.com/BaseDatum/djinnbot)\n\nBuilt by [Sky Moore](https://github.com/skymoore) and the DjinnBot team.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasedatum%2Fdjinnbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasedatum%2Fdjinnbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasedatum%2Fdjinnbot/lists"}