Integration
Swarmclaw
By Self-hosted AI agent orchestration dashboard with OpenClaw integration, multi-provider support, LangGraph workflows, and chat platform connectors.
Install
npm install
npmConfiguration Example
module.exports = {
name: 'my-plugin',
description: 'What it does',
hooks: {
beforeAgentStart: async ({ session, message }) => { /* ... */ },
afterAgentComplete: async ({ session, response }) => { /* ... */ },
beforeToolExec: async ({ toolName, input }) => { /* ... */ },
afterToolExec: async ({ toolName, input, output }) => { /* ... */ },
onMessage: async ({ session, message }) => { /* ... */ },
},
}README
# SwarmClaw
[](https://github.com/swarmclawai/swarmclaw/actions/workflows/ci.yml)
[](https://github.com/swarmclawai/swarmclaw/releases)
<p align="center">
<img src="https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/public/branding/swarmclaw-org-avatar.png" alt="SwarmClaw lobster logo" width="120" />
</p>
Self-hosted AI agent orchestration dashboard. Manage multiple AI providers, orchestrate agent swarms, schedule tasks, and bridge agents to chat platforms β all from a single mobile-friendly interface.
Inspired by [OpenClaw](https://github.com/openclaw).
**[Documentation](https://swarmclaw.ai/docs)** | **[Website](https://swarmclaw.ai)**
Org avatar files: `public/branding/swarmclaw-org-avatar.png` (upload-ready), `public/branding/swarmclaw-org-avatar.svg` (source)
## Security Warning
SwarmClaw can spawn **Claude Code CLI** processes with full shell access on your machine. This means agents can read, write, and execute anything your user account can. **Do not run this on a shared server or expose it to the public internet without understanding the risks.**
- Always use the access key authentication (generated on first run)
- Never expose port 3456 without a reverse proxy + TLS
- Review agent system prompts before giving them shell or browser tools
## Features
- **15 Built-in Providers** β Claude Code CLI, OpenAI Codex CLI, OpenCode CLI, Anthropic, OpenAI, Google Gemini, DeepSeek, Groq, Together AI, Mistral AI, xAI (Grok), Fireworks AI, Ollama, OpenClaw, plus custom OpenAI-compatible endpoints
- **OpenClaw Integration** β First-tier OpenClaw support with endpoint normalization (`ws://`, root HTTP, `/v1`), live health checks, and provider-level diagnostics
- **Agent Builder** β Create agents with custom personalities (soul), system prompts, tools, and skills. AI-powered generation from a description
- **Agent Tools** β Shell, process control for long-running commands, files, edit file, send file, web search, web fetch, CLI delegation (Claude/Codex/OpenCode), Playwright browser automation, and persistent memory
- **Platform Tools** β Agents can manage other agents, tasks, schedules, skills, connectors, sessions, and encrypted secrets via built-in platform tools
- **Orchestration** β Multi-agent workflows powered by LangGraph with automatic sub-agent routing
- **Agentic Execution Policy** β Tool-first autonomous action loop with progress updates, evidence-driven answers, and better use of platform tools for long-lived work
- **Task Board** β Queue and track agent tasks with status, comments, results, and archiving (soft delete with show/hide toggle)
- **Background Daemon** β Auto-processes queued tasks and scheduled jobs with a 30s heartbeat plus recurring health monitoring
- **Scheduling** β Cron-based agent scheduling with human-friendly presets
- **Loop Runtime Controls** β Switch between bounded and ongoing loops with configurable step caps, runtime guards, heartbeat cadence, and timeout budgets
- **Session Run Queue** β Per-session queued runs with followup/steer/collect modes, collect coalescing for bursty inputs, and run-state APIs
- **Voice Settings** β Per-instance ElevenLabs API key + voice ID for TTS replies, plus configurable speech recognition language for chat input
- **Chat Connectors** β Bridge agents to Discord, Slack, Telegram, and WhatsApp with media-aware inbound handling
- **Skills System** β Discover local skills, import skills from URL, and load OpenClaw `SKILL.md` files (frontmatter-compatible)
- **Execution Logging** β Structured audit trail for triggers, tool calls, file ops, commits, and errors in a dedicated `logs.db`
- **Context Management** β Auto-compaction of conversation history when approaching context limits, with manual `context_status` and `context_summarize` tools for agents
- **Memory** β Per-agent and per-session memory with hybrid FTS5 + vector embeddings search, relevance-based memory recall injected into runs, and periodic auto-journaling for durable execution context
- **Cost Tracking** β Per-message token counting and cost estimation displayed in the chat header
- **Model Failover** β Automatic key rotation on rate limits and auth errors with configurable fallback credentials
- **Plugin System** β Extend agent behavior with JS plugins (hooks: beforeAgentStart, afterAgentComplete, beforeToolExec, afterToolExec, onMessage)
- **Secrets Vault** β Encrypted storage for API keys and service tokens
- **Custom Providers** β Add any OpenAI-compatible API as a provider
- **Mobile-First UI** β Responsive glass-themed dark interface, works on phone and desktop
## Requirements
- **Node.js** 20+
- **npm** 10+
- **Claude Code CLI** (optional, for `claude-cli` provider) β [Install](https://docs.anthropic.com/en/docs/claude-code/overview)
- **OpenAI Codex CLI** (optional, for `codex-cli` provider) β [Install](https://github.com/openai/codex)
- **OpenCode CLI** (optional, for `opencode-cli` provider) β [Install](https://github.com/opencode-ai/opencode)
## Quick Start
```bash
curl -fsSL https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/install.sh | bash
```
The installer resolves the latest stable release tag and installs that version by default.
To pin a version: `SWARMCLAW_VERSION=v0.1.0 curl ... | bash`
Or run locally from the repo (friendly for non-technical users):
```bash
git clone https://github.com/swarmclawai/swarmclaw.git
cd swarmclaw
npm run quickstart
```
`npm run quickstart` will:
- Check Node/npm versions
- Install dependencies
- Prepare `.env.local` and `data/`
- Start the app at `http://localhost:3456`
On first launch, SwarmClaw will:
1. Generate an **access key** and display it in the terminal
2. Save it to `.env.local`
3. Show a first-time setup screen in the browser with the key to copy
Open `http://localhost:3456` (or your machine's IP for mobile access). Enter the access key, set your name, and you're in.
### Command-Line Setup (No UI Required)
You can complete first-time setup from terminal:
```bash
# Start the app (if not already running)
npm run dev
# In another terminal, run setup with your provider
node ./bin/swarmclaw.js setup init --provider openai --api-key "$OPENAI_API_KEY"
```
Notes:
- On a fresh instance, `setup init` can auto-discover and claim the first-run access key from `/api/auth`.
- For existing installs, pass `--key <ACCESS_KEY>` (or set `SWARMCLAW_ACCESS_KEY`).
- `setup init` performs provider validation, stores credentials, creates a starter agent, and marks setup complete.
- Use `--skip-check` to bypass connection validation.
### 2-Minute Setup Wizard
After login, SwarmClaw opens a guided wizard designed for non-technical users:
1. Choose a provider: **OpenAI**, **Anthropic**, **OpenClaw**, or **Ollama**
2. Add only required fields (API key and/or endpoint)
3. Click **Check Connection** for live validation before continuing
4. (Optional) click **Run System Check** for setup diagnostics
5. Create a starter assistant (advanced settings are optional)
Notes:
- OpenClaw supports endpoint + optional bearer token.
- Ollama and OpenClaw checks can auto-suggest a model from the connected endpoint.
- You can skip setup and configure everything later in the sidebar.
## Configuration
All config lives in `.env.local` (auto-generated):
```
ACCESS_KEY=<your-access-key> # Auth key for the dashboard
CREDENTIAL_SECRET=<auto-generated> # AES-256 encryption key for stored credentials
```
Data is stored in `data/swarmclaw.db` (SQLite with WAL mode), `data/memory.db` (agent memory with FTS5 + vector embeddings), and `data/logs.db` (execution audit trail). Back the `data/` directory up if you care about your sessions, agents, and credentials. Existing JSON file data is auto-migrated to SQLite on first run.
## Architecture
```
src/
βββ app/
β βββ api/ # Next.js API routes (REST + SSE streaming)
β βββ page.tsx # Auth flow β UserPicker β AppLayout
βββ components/
β βββ agents/ # Agent builder UI
β βββ auth/ # Access key gate + user picker
β βββ chat/ # Message rendering, streaming, code blocks
β βββ connectors/ # Discord/Slack/Telegram/WhatsApp config
β βββ layout/ # App shell, sidebar, mobile header
β βββ providers/ # Provider management
β βββ schedules/ # Cron scheduler
β βββ sessions/ # Session list + new session
β βββ skills/ # Skills manager
β βββ tasks/ # Task board
β βββ shared/ # Reusable UI (BottomSheet, IconButton, etc.)
βββ lib/
β βββ providers/ # LLM provider implementations
β βββ server/ # Storage, orchestrator, connectors, tools
βββ stores/ # Zustand state (app store, chat store)
βββ types/ # TypeScript interfaces
```
**Stack:** Next.js 16, React 19, Tailwind v4, shadcn/ui, Zustand, LangGraph, TypeScript
## Providers
### CLI Providers
| Provider | Binary | Notes |
|-|-|-|
| Claude Code CLI | `claude` | Spawns with `--print --output-format stream-json`. Includes auth preflight and clearer timeout/exit diagnostics. |
| OpenAI Codex CLI | `codex` | Spawns with `--full-auto --skip-git-repo-check`. Includes login preflight and streamed CLI error events. |
| OpenCode CLI | `opencode` | Spawns with `run --format json` and tracks session resume IDs. Multi-model support. |
### API Providers
| Provider | Endpoint | Models |
|-|-|-|
| Anthropic | api.anthropic.com | Claude Sonnet 4.6, Opus 4.6, Haiku 4.5 |
| OpenAI | api.openai.com | GPT-4o, GPT-4.1, o3, o4-mini |
| Google Gemini | generativelanguage.googleapis.com | Gemini 2.5 Pro, Flash, Flash Lite |
| DeepSeek | api.deepseek.com | DeepSeek Chat, Reasoner |
| Groq | api.groq.com | Llama 3.3 70B, DeepSeek R1, Qwen QW
... (truncated)
integration
Comments
Sign in to leave a comment