https://github.com/ClawixAI/clawix
Open-source, self-hosted multi-agent AI orchestration platform. Run agents in isolated Docker containers with swarm coordination, RBAC, token governance, and multi-channel support.
https://github.com/ClawixAI/clawix
agent-orchestration ai ai-platform ai-swarm assistant docker-ai multi-agent self-hosted-ai swarm
Last synced: 26 days ago
JSON representation
Open-source, self-hosted multi-agent AI orchestration platform. Run agents in isolated Docker containers with swarm coordination, RBAC, token governance, and multi-channel support.
- Host: GitHub
- URL: https://github.com/ClawixAI/clawix
- Owner: ClawixAI
- Created: 2026-04-08T16:40:46.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-12T16:02:02.000Z (2 months ago)
- Last Synced: 2026-05-12T18:05:28.242Z (2 months ago)
- Topics: agent-orchestration, ai, ai-platform, ai-swarm, assistant, docker-ai, multi-agent, self-hosted-ai, swarm
- Language: TypeScript
- Homepage:
- Size: 12.9 MB
- Stars: 11
- Watchers: 0
- Forks: 5
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Security: docs/SECURITY.md
- Governance: docs/GOVERNANCE.md
- Agents: docs/AGENTS.md
Awesome Lists containing this project
- awesome-ai-devtools - Clawix AI Platform - source, self-hosted multi-agent AI orchestration platform running agents in isolated Docker containers. | CLI · Web · Self-hosted | [Docs](https://github.com/ClawixAI/clawix#readme) / [Repo](https://github.com/ClawixAI/clawix) | (Browse The Shelves / Self-hosted AI dev stacks)
README
Clawix
Self-hosted multi-agent AI orchestration platform
Run AI agent swarms in isolated containers. Full governance. Zero vendor lock-in.
---
## Why Clawix?
Most AI agent frameworks are either **toys** (single-process, no isolation, no audit trail) or **walled gardens** (cloud-only, per-seat pricing, your data on someone else's servers).
Clawix sits in between: **production-grade orchestration you own entirely.**
- **Every agent runs in its own Docker container** -- no agent can read another's files, exhaust your host's memory, or escape its sandbox.
- **Plug in any LLM** -- Claude, GPT, DeepSeek, and Gemini today, with Azure and OpenRouter coming soon. Any OpenAI-compatible endpoint (Ollama, vLLM, etc.) works now via the custom provider.
- **Built for teams** -- RBAC, token budgets, audit logs, and scoped memory mean you can hand agents to your whole org without losing sleep.
- **Reach users where they are** -- Telegram, WhatsApp, Slack, and a built-in web dashboard. One agent, many channels.
> Think of it as "Kubernetes for AI agents" -- container isolation, resource limits, health checks, and warm pools, but purpose-built for LLM workloads.
---
## Features
### Container-Isolated Agents
Every agent gets its own sandboxed Docker container with CPU/memory limits, read-only mounts, and no root access. Cross-agent interference is architecturally impossible.
### Warm Container Pool
Primary agents stay warm in pre-provisioned containers. Cold-start latency drops from **1-3 seconds to ~50ms**.
### Swarm Orchestration
Break complex tasks into sub-agent DAGs. The coordinator delegates, aggregates results, and handles failures -- all within isolated containers.
### Multi-Provider AI
Anthropic, OpenAI, DeepSeek, and Gemini out of the box, with Azure and OpenRouter planned. Any OpenAI-compatible endpoint already works via the custom provider. Add new providers with a single config entry.
### Scoped Memory System
Persistent memory at three levels: private (per-user), group (team), and org-wide. Agents build context over time without re-prompting.
### Skills Framework
Pluggable tools with approval workflows. Bundle built-in skills, create custom ones at runtime, or use the built-in skill-creator agent to generate new skills from natural language.
### And also...
- **Governance & Compliance** -- Token budgets per user/group, immutable audit logs, structured logging (Pino), Prometheus metrics
- **Multi-Channel Delivery** -- reach users across messaging platforms and web (see table below)
- **Per-User Workspaces** -- Persistent directories that survive container teardown, with quota enforcement
- **Encrypted Secrets** -- Provider API keys stored with AES-256-GCM; encryption key never leaves your server
- **RBAC** -- Role-based access control across all management APIs
---
## Architecture
```
┌──────────────────────────────────────────┐
│ User Interfaces │
│ Telegram WhatsApp Slack Web UI │
└──────────────────┬───────────────────────┘
│
┌──────────────────▼───────────────────────┐
│ API Gateway │
│ NestJS + Fastify │ JWT │ Rate Limit │
└──────────────────┬───────────────────────┘
│
┌────────────────────────────▼────────────────────────────┐
│ Core Engine │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ Reasoning │ │ Tool │ │ Swarm │ │
│ │ Loops │ │ Execution │ │ Coordinator │ │
│ └─────────────┘ └──────────────┘ └───────────────┘ │
│ │
│ Providers: Claude │ GPT │ OpenAI-compatible │ Custom │
└────────────────────────────┬───────────────────────────┘
│
┌────────────────────────────▼────────────────────────────┐
│ Container Pool │
│ ┌──────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ Warm │ │ Ephemeral │ │ Resource │ │
│ │ Primary │ │ Sub-Agents │ │ Limits │ │
│ └──────────┘ └──────────────┘ └─────────────────┘ │
└────────────────────────────┬───────────────────────────┘
│
┌────────────────────────────▼────────────────────────────┐
│ Data Layer │
│ PostgreSQL │ Redis │ User Workspaces │
└─────────────────────────────────────────────────────────┘
```
---
## Quick Start
### Prerequisites
- [Git](https://git-scm.com/)
- [Node.js 20+](https://nodejs.org/)
- [pnpm 9+](https://pnpm.io/installation) (`npm install -g pnpm`)
- [Docker](https://docs.docker.com/get-docker/) (for agent containers, PostgreSQL, and Redis)
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (user-friendly platform for container management)
- [Docker Compose](https://docs.docker.com/compose/install/) (included in Docker Desktop)
> **Self-hosting in production?** Skip ahead to [Production Deployment](#production-deployment-first-run) — the installer handles `.env` generation, image builds, and bootstrap for you. The steps below are for local development.
### 1. Clone & Install
```bash
# 1. Clone the repository
git clone https://github.com/ClawixAI/clawix.git
cd clawix
# 2. Run the interactive installer
pnpm run install:clawix
```
Manual setup (click to expand)
```bash
pnpm install
cp .env.example .env
pnpm --filter @clawix/shared run build
docker build -t clawix-agent:latest -f infra/docker/agent/Dockerfile .
docker compose -f docker-compose.dev.yml up -d
```
### 2. Configure
Edit `.env` with your API keys:
```bash
# Required: encryption key for provider secrets (AES-256-GCM)
PROVIDER_ENCRYPTION_KEY=$(openssl rand -hex 32)
# AI providers (used by db:seed; also env fallback at runtime)
ANTHROPIC_API_KEY=sk-ant-xxx # Claude
OPENAI_API_KEY=sk-xxx # GPT (optional)
DEEPSEEK_API_KEY=sk-xxx # DeepSeek (optional)
# Channels (optional -- used by db:seed to populate channel config)
TELEGRAM_BOT_TOKEN=123456789:ABCdef... # Telegram (from @BotFather)
# Database (defaults work with docker-compose)
DATABASE_URL="postgresql://clawix:clawix_dev@localhost:5433/clawix"
REDIS_URL="redis://localhost:6379"
```
### 3. Run
```bash
pnpm run dev # API on :3001, Dashboard on :3000
```
That's it. Open `http://localhost:3000` or message your Telegram bot.
---
## Production Deployment (First Run)
Two helper scripts wrap the full production flow:
| Command | What it does |
| ------------------------- | --------------------------------------------------------------------------- |
| `pnpm run install:clawix` | Interactive first-time setup: generates `.env`, builds images, starts stack |
| `pnpm run update:clawix` | Non-interactive rebuild + restart (use after `git pull` or config changes) |
### First run
```bash
pnpm run install:clawix
```
The installer will:
1. Check prerequisites (Node 20+, pnpm, Docker, Docker Compose)
2. Ask for deployment mode (production / development), provider selection (Anthropic, OpenAI, Z.AI Coding, Kimi, Gemini, DeepSeek, or a custom OpenAI-compatible endpoint) + API key, admin email/password (production only), and optional Telegram bot token
3. Generate `.env` with cryptographically random `JWT_SECRET`, `PROVIDER_ENCRYPTION_KEY`, `POSTGRES_PASSWORD` (file permissions set to `600`)
4. Build `clawix-agent:latest` (agent image used for isolated per-task containers)
5. Run `docker compose … up -d --build`
6. Wait for `http://localhost:3001/health` to go green (migrations + bootstrap run inside the API container on first start)
When it finishes, open `http://localhost:3000` and sign in with the admin credentials you entered.
> Re-running `install:clawix` with an existing `.env` is safe — it keeps your secrets, skips the prompts, and just rebuilds/restarts. To reconfigure from scratch, delete `.env` and re-run.
### Updates and restarts
```bash
pnpm run update:clawix # rebuild + restart (default)
pnpm run update:clawix -- --pull # git pull --ff-only, then rebuild + restart
pnpm run update:clawix -- --no-build # plain restart, reuse existing images
```
The updater reads `CLAWIX_DEPLOY_MODE` from `.env` and picks the right compose file automatically. Prisma migrations and the idempotent bootstrap run inside the container on every start — bootstrap no-ops once the admin exists.
### What happens under the hood
- `infra/docker/api/entrypoint.sh` runs `prisma migrate deploy`, then `node dist/bootstrap.js`.
- `bootstrap.ts` only writes when the admin doesn't already exist and only uses `upsert` / guarded `create` — never deletes data.
- The production compose file **fails fast** at `docker compose up` time if any of `POSTGRES_PASSWORD`, `JWT_SECRET`, `CORS_ALLOWED_ORIGINS`, or `PROVIDER_ENCRYPTION_KEY` are missing.
- Generate the encryption key manually (if not using the installer) with `openssl rand -hex 32`.
### Manual equivalent (no installer)
```bash
cp .env.example .env
# edit .env — set POSTGRES_PASSWORD, JWT_SECRET, CORS_ALLOWED_ORIGINS,
# PROVIDER_ENCRYPTION_KEY, DEFAULT_PROVIDER, _API_KEY,
# INITIAL_ADMIN_EMAIL, INITIAL_ADMIN_PASSWORD, INITIAL_ADMIN_NAME
docker build -t clawix-agent:latest -f infra/docker/agent/Dockerfile .
docker compose -f docker-compose.prod.yml up -d --build
docker compose -f docker-compose.prod.yml logs api | grep '\[bootstrap\]'
```
## Uninstallation
Remove Clawix completely with:
```bash
pnpm run uninstall:clawix # preserve host data
pnpm run uninstall:clawix -- --full # complete removal
```
### Flags
| Flag | Description |
| --------------- | ----------------------------------------------------------------------- |
| `--full` / `-f` | Remove Docker resources AND host data (.env, ./data/, ./skills/custom/) |
| `--yes` / `-y` | Skip confirmation prompt |
### What gets removed
**Docker cleanup (default):**
- Containers from both dev and prod environments
- Images built by compose + `clawix-agent:latest`
- Named volumes (`postgres_data`, `redis_data`, etc.)
- Orphan containers
**Host data (with `--full`):**
- `.env` — configuration and secrets
- `./data/` — runtime data, user workspaces
- `./skills/custom/` — user-created skills
### Fresh reinstall
```bash
# Full cleanup
pnpm run uninstall:clawix -- --full -y
# Reinstall from scratch
pnpm run install:clawix
```
> Without `--full`, host data is preserved. The installer detects existing `.env` and skips configuration prompts, reusing your previous settings.
---
## Multi-Provider Support
Built-in providers plus extensible registry -- add new ones with a single `ProviderSpec` entry:
| Provider | Detection | Use Case | Status |
| --------------- | ------------------------------------------ | --------------------- | --------- |
| **Anthropic** | model starts with `claude-` | Primary (best tools) | Available |
| **OpenAI** | model starts with `gpt-`/`o1-`/`o3-`/`o4-` | General purpose | Available |
| **Z.AI Coding** | model starts with `glm-` | GLM models | Available |
| **Azure** | config key `azure_openai` | Enterprise compliance | Planned |
| **DeepSeek** | model starts with `deepseek-` | Cost-effective | Available |
| **Gemini** | model starts with `gemini-` | Google ecosystem | Available |
| **Kimi** | provider id `kimi-code` | Long-context tasks | Available |
| **OpenRouter** | API key starts with `sk-or-` | Provider gateway | Planned |
| **Custom** | any OpenAI-compatible endpoint | Ollama, vLLM, etc. | Available |
## Channels
| Channel | Integration | Use Case | Status |
| ----------------- | ------------------- | ----------------------------- | --------- |
| **Telegram** | grammY | Personal & team chat | Available |
| **WhatsApp** | Business API | Customer-facing agents | Planned |
| **Slack** | Bolt SDK | Workspace collaboration | Planned |
| **Web Dashboard** | Next.js + WebSocket | Admin console & conversations | Available |
---
## Security Model
Clawix follows a **zero-trust architecture** for agent execution:
| Threat | Mitigation |
| ------------------------------ | -------------------------------------------------------------- |
| Cross-user data access | Workspaces only mounted into owner's container |
| Sub-agent privilege escalation | Sub-agents get read-only curated context, never full workspace |
| Memory poisoning | Agent context regenerated from DB each run |
| Disk exhaustion | Per-user quota enforcement (default 500 MB) |
| Path traversal | All paths validated to stay under `data/org/` |
| Secret leakage | API keys encrypted at rest (AES-256-GCM) |
| Untrusted code execution | All agent code runs inside sandboxed containers, never on host |
---
## Tech Stack
| Layer | Technology |
| ---------- | --------------------------------------------------------- |
| API | NestJS 11 + Fastify |
| Frontend | Next.js 15 + Tailwind CSS + shadcn/ui |
| AI | Multi-provider (Anthropic, OpenAI, any OpenAI-compatible) |
| Database | Prisma ORM + PostgreSQL 16 |
| Cache | Redis 7 (ioredis) |
| Auth | NextAuth (JWT + OAuth2) |
| Containers | Docker CLI with resource limits |
| Logging | Pino (structured JSON) |
| Metrics | Prometheus (prom-client) |
| Testing | Vitest + Playwright |
| Monorepo | pnpm workspaces |
---
## Project Structure
```
clawix/
├── packages/
│ ├── api/ # NestJS API server (auth, engine, channels, skills)
│ ├── web/ # Next.js dashboard (React 19, Tailwind, shadcn/ui)
│ ├── shared/ # Shared types, schemas, utilities, logger
│ └── worker/ # Background job processor
├── skills/
│ └── builtin/ # Bundled skills (web_search, file_ops, etc.)
├── infra/
│ └── docker/ # Agent container Dockerfile
├── prisma/ # Database schema + migrations
├── docs/ # Architecture & implementation docs
└── scripts/ # Dev/ops scripts
```
---
## Commands
```bash
pnpm run dev # Start API + dashboard (hot-reload)
pnpm run build # Build all packages
pnpm run test # Run all tests
pnpm run test:coverage # Tests with coverage report
pnpm run lint # ESLint + type check
pnpm run format # Prettier format
# Production deployment
pnpm run install:clawix # Interactive first-time setup (generates .env, builds, starts)
pnpm run update:clawix # Rebuild + restart after git pull or config changes
# Infrastructure
pnpm run docker:dev # Start Postgres, Redis, pgAdmin
pnpm run docker:down # Stop local infra
# Database
pnpm run db:migrate # Run Prisma migrations
pnpm run db:seed # Seed initial data
pnpm run db:studio # Open Prisma Studio (GUI)
```
---
## Roadmap
- [x] Container-isolated agent execution
- [x] Multi-provider AI support (Claude, GPT, OpenAI-compatible endpoints)
- [ ] First-class Azure, OpenRouter providers
- [x] Warm container pool (~50ms cold start)
- [x] Swarm orchestration with DAG dependencies
- [x] Telegram channel integration
- [x] Scoped memory system
- [x] Skills framework with built-in skill creator
- [ ] WhatsApp Business API integration
- [ ] Slack integration
- [x] Web dashboard (conversations, agents, skills, settings)
- [ ] Skill marketplace UI
- [ ] Advanced token analytics & optimization
- [ ] Multi-region deployment support
---
## Contributing
Contributions are welcome! Whether it's bug fixes, new features, documentation, or feedback -- we'd love your help.
```bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/clawix.git
cd clawix
# Create a feature branch
git checkout -b feature/your-feature
# Make changes, then test and lint
pnpm run test
pnpm run lint
# Commit with conventional commits
git commit -m "feat: add amazing feature"
# Push and open a PR
git push origin feature/your-feature
```
**Guidelines:**
- TypeScript strict mode -- no `any`
- Write tests for new features (Vitest)
- Follow conventional commits (`feat:`, `fix:`, `refactor:`, etc.)
- Keep files under 400 LOC
- Never commit secrets or API keys
---
## Security
If you discover a security vulnerability, please report it responsibly via [GitHub Security Advisories](https://github.com/clawix/clawix/security/advisories) instead of using the public issue tracker.
---
## Acknowledgments
Clawix builds on ideas from:
- [nanoClaw](https://github.com/qwibitai/nanoclaw) -- Container-isolated agent execution
- [nanobot](https://github.com/HKUDS/nanobot) -- Multi-provider AI design patterns
---
## License
MIT -- see [LICENSE](LICENSE) for details.
---
Built for organizations that need AI agents they can actually trust.