Turn the agent CLIs you already use into shared services your whole team can call.
Describe an Agent in plain language, bind a model provider, publish it to Feishu, Slack, Discord, an HTTP API, or a schedule. No flowcharts, no glue code.
Core Concepts · Project Guide · Contributing · Security
English | 简体中文
a2wave turns the agent CLIs you already use — Claude Code, Cursor Agent, OpenAI Codex, and more — into shared, governed services, reachable from Feishu, Slack, Discord, an HTTP API, or a schedule.
Describe an Agent in natural language, bind a model provider, extend it with Skills and MCP servers, publish. a2wave handles credential injection, run queueing, audit trails, permissions, and delivery — all managed from a built-in web dashboard.
a2wave orchestrates; it does not execute. No bundled LLM inference, no sandbox runtime, no drag-and-drop DAG editor — execution comes from the underlying CLIs, and orchestration is written in natural language. These boundaries are enforced; see the Iron Rules.
| a2wave | Workflow builders (n8n, Dify, Flowise) | A bare agent CLI | |
|---|---|---|---|
| How logic is expressed | Natural language | Nodes, edges, variable mapping | Natural language |
| Who can run it | Your whole team, via the channels they already use | Whoever opens the builder | Whoever has the terminal |
| Model execution | Your existing CLI + your credentials | Vendor-managed runtimes | Local only |
| Governance | Per-Agent permissions, audit trail, run queue | Varies | None |
Pick a2wave when your team already trusts an agent CLI and needs to share it — with access control, an audit trail, and delivery into Feishu or Slack — rather than rebuild its reasoning as a graph.
- 🤖 Bring your own agent CLI — Claude Code, Cursor Agent, OpenAI Codex, OpenCode, Qoder, Trae, Kimi and Pi are interchangeable execution engines, installed on demand from a pinned, checksum-verified lockfile.
- 🌊 Publish to multiple channels — one Agent, reachable via HTTP API, Feishu, Slack, Discord, A2A, schedules, GitLab / GitHub repository triggers, and a first-party chat page.
- 🖥️ Web dashboard — build and publish Agents, manage providers, Skills, MCP servers and SCM sources, watch runs, and browse the audit trail from one console.
- 🧩 Extend by composition — add capabilities through Skills and MCP servers (stdio / SSE / HTTP / proxy groups) instead of forking the platform.
- 🔗 Agent-to-agent calls — Agents reach other Agents over A2A, including ones hosted outside your deployment.
- 📚 Persistent memory — per-Agent, with progressive disclosure and keyword, vector and hybrid search.
- 🧪 Built-in evaluation — replay curated case sets against an Agent's current config, with a frozen provider/model/prompt snapshot for honest comparison.
- 📦 Git & Perforce workspaces — Agents work on real checkouts, with isolated worktrees per evaluation run.
- 🔐 Enterprise auth — OIDC and SAML SSO, per-Agent owner/editor/viewer permissions, rate limiting, and an audit entry behind every write.
a2wave is built for internal enterprise teams: Agent authors and Agent users are assumed to be trusted colleagues acting in good faith.
That shapes the boundaries. Agents run CLIs with real capabilities — filesystem, shell, injected credentials — by design. The platform does not sandbox authors from each other, nor defend against an insider crafting a hostile Agent. Its controls (authentication, per-Agent permissions, audit logging, rate limiting) enforce accountability and least privilege among teammates, not containment of an adversary already inside.
Important
Exposing a2wave to untrusted users or running untrusted Agent configurations is out of scope — add your own isolation layer. Full statement: SECURITY.md.
npm i -g a2wave
a2wave setupOne command installs the published image, writes docker-compose.yml + .env,
starts the container and waits until it is healthy — no clone, no build. Then open
the web dashboard at http://localhost:3502: the first login claims the admin
account, and everything from there — creating an Agent, binding a model provider,
publishing it to channels — happens in the dashboard. The in-app manual at /wiki
walks through your first Agent end to end.
To deploy with the bundled PostgreSQL container (experimental — see Database Backend first):
a2wave setup --yes --with-postgres --dir "$HOME/a2wave-pg" --port 3512The CLI selects the versioned image matching its own release; upgrade later with
a2wave setup --upgrade from the same install directory. The generated deployment
includes a dedicated a2wave-workspace volume — new Git sources use managed paths
there automatically. P4 sources instead require an absolute mounted path covered by
the existing P4 Client Root or AltRoots.
Every generated setting has a working default; see Configuration for what each one does.
Requires Node.js ≥ 22 (matching the image's node:22-slim runtime) and pnpm ≥ 9.
pnpm install
cp .env.example .env # leave AUTH_SECRET empty; pnpm dev generates one
pnpm dev # API :3502 + Web :3501
pnpm stop # free the ports if a previous run left orphansA clone also ships a docker-compose.yml for building and
running the image from source (cp .env.example .env && docker compose up -d --build
— on macOS read the workspace-mount notes inside the compose file first).
Development guides, API reference and database operations: AGENTS.md. CLI install / upgrade / publish: CLI Installation & Publishing.
DATABASE_URL alone picks the backend: a postgres:// scheme means PostgreSQL,
anything else is a SQLite file path.
SQLite (default, supported) — nothing to configure; a2wave setup gives you one
container with the database on a named volume.
PostgreSQL ≥ 9.6 (experimental) — deploy the bundled sidecar with
a2wave setup --with-postgres, or point at an external server with
--database-url postgres://…. Migrations run on boot and pick the matching lineage;
the API waits for the database healthcheck, so a cold start is safe. The sidecar's
port is not published to the host.
Warning
PostgreSQL is experimental and not recommended for production: it passes the full suite and a smoke test, but has no production soak time, and there is no SQLite → PostgreSQL migration path — switching starts from an empty database. It exists for multi-instance deployments, where one SQLite file cannot be shared safely. Details, including per-process cache caveats for replicas: docs/agent/postgresql.md.
A published Agent is reachable through HTTP API, Feishu, Slack, Discord, the A2A protocol, scheduled triggers, GitLab / GitHub repository triggers, and the first-party chat page.
The Feishu channel supports Feishu (feishu.cn) apps; Lark international (larksuite.com) is not configurable yet.
| Document | Contents |
|---|---|
| Core Concepts | Agent, Provider, Skill, MCP Server, SCM Source, Run, Evaluation |
| Configuration | Every environment variable and settings override |
| Project Guide | Architecture, full API reference, testing strategy, conventions |
| CLI Installation & Publishing | Installing, upgrading, and publishing the a2wave CLI |
| Contributing | Dev setup, commit convention, quality gates, AI policy |
| Security Policy | Trust model and vulnerability disclosure |
A running instance also serves an interactive API reference at /api/docs (Swagger
UI) and the user manual at /wiki.
a2wave is built extensively with AI coding agents — a fitting way to build a platform that orchestrates them. Every change lands through a full test pyramid (unit / integration / E2E), hard lint and typecheck gates, and human review. AI-assisted contributions are held to the same bar; see the AI Contribution Policy.
Issues, discussions and pull requests are welcome. Start with CONTRIBUTING.md — dev setup, commit convention, quality gates and the AI contribution policy. a2wave has explicit product boundaries (the Iron Rules in AGENTS.md); features that cross them need maintainer discussion first. By participating you agree to the Code of Conduct.
Warning
Do not report security vulnerabilities through public issues or pull requests — follow SECURITY.md to disclose privately.
Thanks to everyone who has contributed to a2wave — see the contributors graph.
Licensed under the Apache License 2.0. Copyright 2026 Lilith Games — see NOTICE for attribution and bundled third-party material.