█████╗ ██╗ █████╗ ██████╗ ██████╗ ██╗███╗ ██╗ █████╗ ██╗
██╔══██╗██║ ██╔══██╗██╔══██╗██╔══██╗██║████╗ ██║██╔══██╗██║
███████║██║ ███████║██║ ██║██║ ██║██║██╔██╗ ██║███████║██║
██╔══██║██║ ██╔══██║██║ ██║██║ ██║██║██║╚██╗██║██╔══██║██║
██║ ██║███████╗██║ ██║██████╔╝██████╔╝██║██║ ╚████║██║ ██║██║
╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═════╝ ╚═╝╚═╝ ╚═══╝╚═╝ ╚═╝╚═╝
AladdinAI is an open-source, self-hosted AI workspace — agents, memory, CRM, and multi-channel messaging running entirely in your own infrastructure.
436 unique cloners |
14 days since launch |
$0 marketing spend |
|---|---|---|
| organic traction | after public release | zero paid promotion |
One command. No git clone. No Python. No Node toolchain. Just Docker.
We believe the next wave of AI adoption won't happen in shared clouds. It will happen in companies that need control over their data, their models, and their customer relationships.
AladdinAI is the platform that makes that possible — without building everything from scratch.
Status: actively developed. Most features are wired end-to-end and usable locally. See
docs/ARCHITECTURE.mdfor the full picture.
| Module | Description |
|---|---|
| Agents | Per-user agents with their own model, system prompt, tool set, and safety stack (NemoGuard / Llama-Guard, PII redaction via GLiNER) |
| Memory | Private + shared stores with vector search (MongoDB Atlas + NIM embeddings). Every recall and write decision is logged via pluggable Gates |
| CRM | Contacts, deals, activities. Every inbound message is auto-attributed to a contact and logged to the activity timeline |
| Channels | Telegram, WhatsApp (Cloud API), SMS, IMAP/SMTP email. Outgoing webhooks for fan-out |
| Terminal | Browser-based terminals (ttyd local shell, wetty SSH) for remote server management |
| Triggers | Cron-scheduled fan-out tasks via APScheduler, per-agent model overrides, fallback chains across providers |
| Infrastructure | Manage LLM providers, MongoDB clusters, cloud VMs (SSH), and BentoML deployments from the UI |
Every fact is evaluated by NemoGuard before it is written.
Retrieval uses MongoDB Atlas Vector Search — semantic, not keyword.
NVIDIA NIM — LLM inference and embeddings on-prem or in any cloud. No dependency on shared inference APIs. Every agent routes to a NIM endpoint, making the entire inference layer sovereign by default.
MongoDB Atlas — Long-term agentic memory with Atlas Vector Search. Handles both structured data (CRM, activity timelines) and the vector layer (semantic memory recall) in a single platform. No separate vector DB to sync.
Backed by MongoDB for Startups — $500 in Atlas credits to remove infrastructure barriers for the first 8 months.
BentoML — Deploy and scale custom tools and local LLMs within your own infrastructure. Swap, scale, or version models directly from the AladdinAI UI — without touching the codebase.
One command — pulls prebuilt images from GHCR (multi-arch: amd64 + arm64), generates a .env with cryptographically-secure secrets, and brings up the full stack:
npx aladdin-ai✓ Services running
Frontend: http://localhost:3000
Backend: http://localhost:8000
Open http://localhost:3000, register a user, and land on the dashboard.
Add at least one LLM Provider under Settings → LLM Providers before creating agents.
- Docker Desktop (macOS / Windows) or
docker+docker compose(Linux) - Node.js 18+ (just to run
npx)
npx aladdin-ai up # start services
npx aladdin-ai down # stop services
npx aladdin-ai restart backend # restart one service
npx aladdin-ai logs -f # tail logs
npx aladdin-ai update # pull latest images and recreate
npx aladdin-ai doctor # diagnose setup issuesSee cli/README.md for the full command reference.
For contributors who want to modify the code rather than just run it:
npx aladdin-ai init --source
# or manually:
git clone https://github.com/aliyevaladddin/AladdinAI.git
cd AladdinAI
cp .env.example .env
docker compose up --buildFor a non-Docker workflow with hot-reload:
make install # creates .venv, installs Python deps
cd frontend && npm install && cd ..
make migrate # apply Alembic migrations
make dev-backend # FastAPI on :8000 with --reload
make dev-frontend # Next.js on :3000 with --reload| Layer | Tools |
|---|---|
| Frontend | Next.js 15, React 19, TailwindCSS, shadcn/ui, sonner |
| Backend | FastAPI, SQLAlchemy 2 (async), Alembic, APScheduler |
| Storage | SQLite or Postgres (relational), MongoDB Atlas (vectors) |
| LLM access | Provider-agnostic — NIM, OpenAI, Anthropic, local via BentoML |
| Auth | JWT (HS256) with access + refresh tokens |
| Realtime | Server-sent events for chat streaming |
- Marketplace — shareable agent templates, tool packs, and gate configurations
- Multi-tenant SaaS mode — deploy AladdinAI as a hosted service for your own customers, with per-tenant isolation and billing hooks
- Advanced observability — full trace view per agent turn: memory reads, gate decisions, tool calls, model latency
- Expanded channels — voice (WebRTC + NIM ASR/TTS), native mobile push, browser extension
- One-click cloud deploy — pre-configured Terraform modules for AWS, GCP, and Azure. Full stack up in under 10 minutes
AladdinAI/
├── backend/ FastAPI service, models, services, tools, migrations
├── frontend/ Next.js 15 dashboard
├── scripts/ dev / install / migration helpers
├── docs/ Architecture & design notes
├── cli/ npx aladdin-ai CLI
├── docker-compose.yml
├── Makefile
└── .env.example
| Subtree | README |
|---|---|
backend/ |
Request lifecycle, services, how to add a tool/gate/channel |
frontend/ |
Page structure, panel pattern, API client |
scripts/ |
What each shell script does |
docs/ |
Architecture concept doc |
make help # list all Make targets
make dev-backend # FastAPI on :8000 with auto-reload
make dev-frontend # Next.js on :3000
make up # full stack via docker compose
make down # stop docker compose stack
make migration m="add foo table" # autogenerate alembic revision
make migrate # apply pending migrations
make downgrade # roll back one alembic step
make clean # remove .venv, caches, build artefactsJWT_SECRET— replace withopenssl rand -hex 32before deploying. Anyone who knows it can mint tokens for any user.- Database — switch
DATABASE_URLto Postgres. SQLite is fine locally but not for multi-worker deployments. - Frontend URL — set
NEXT_PUBLIC_API_URLto the public backend URL the browser will reach. - API keys — provider keys live in the database (encrypted at rest, set via the UI), not in
.env.
npx aladdin-ai logs -f # tail all services
npx aladdin-ai logs -f backend # backend only
npx aladdin-ai logs -f frontend # frontend onlyEvery agent turn is traceable: memory reads, gate decisions, tool calls, and model latency are logged to the backend. Use GET /api/agents/{agent_id}/gate-logs to pull structured decision logs per agent.
npx aladdin-ai update # pull latest images, recreate containers
make migrate # apply any new database migrationsImages are versioned and tagged. The CLI always pulls the same tag it was installed with unless you pass --tag latest explicitly. Database migrations run automatically on backend startup via Alembic.
If a service crashes, Docker Compose restarts it automatically (restart: unless-stopped). To restart manually:
npx aladdin-ai restart backend
npx aladdin-ai restart frontend
npx aladdin-ai doctor # diagnose config, DB connection, and provider healthAgent tasks (scheduled cron jobs via APScheduler) are in-process and will restart with the backend. Persistent state lives in Postgres — no in-memory-only state that can be lost on restart.
All resources are scoped per user. Agents, memories, CRM contacts, and channel connections are isolated by user_id at the database query level — a user cannot read or write another user's data even if they share the same instance.
Role model: admin users can manage LLM providers and system-wide settings. Regular users manage only their own agents and data.
Agents are bounded at multiple layers to prevent runaway behaviour:
| Layer | Mechanism |
|---|---|
| Safety gates | NemoGuard / Llama-Guard runs before and after every model response. Blocks or redacts harmful content. |
| PII redaction | GLiNER-based extraction strips personal data from memory writes and shared context. |
| Gate logging | Every gate decision is written to gate_logs — auditable, queryable via API. |
| Tool scope | Each agent has an explicit tool list. No agent can call a tool it was not granted. |
| Model overrides | Per-agent model, temperature, and token limits are set at creation time and not changeable by the agent itself. |
| Cron throttling | Scheduled tasks are defined with explicit intervals — no self-scheduling or infinite loops. |
Configure gates under Settings → Safety in the dashboard.
Two browser-based terminal providers, running in isolated Docker containers with Traefik routing and forward-auth:
ttyd — Lightweight Bash/Zsh terminal in the browser. Minimal resource usage. Default for local access.
wetty — SSH-in-browser with server-side proxy. Password and key-based auth. Connects to remote Linux/Unix servers with automatic VM credential injection.
Install through the UI under Settings → Terminal Providers. No additional setup required.
I'm building AladdinAI in public and I read every message personally. Even one sentence helps — especially the negative ones.
- Quick form: https://aliyev.site/AladdinAI/feedback
- Email: aladdin@aliyev.site
- GitHub: open an issue · start a discussion
"This is broken." "Didn't get past step 2." "Cool but not for me." All of it useful.
— Aladdin
Apache 2.0 — see LICENSE.
Your data. Your models. Your rules.