a2wave
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, Telegram, an HTTP API, or a schedule. No flowcharts, no glue code.
Core Concepts · Project Guide · Contributing · Security
English | 简体中文
What is a2wave?
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, Telegram, 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.
How it compares
| 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.
Features
- 🤖 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, Telegram, 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.
Trust Model
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.
Quick Start
npm i -g a2wave
a2wave setup
One 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 3512
The 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.
Local Development
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 orphans
A 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 Backend
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.
Channels
A published Agent is reachable through HTTP API, Feishu, Slack, Discord, Telegram, 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.
Screenshots
The Agent overview: run volume, success rate, average duration, token usage, and
trends over the selected window.
Documentation
| 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.
Built with AI
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.
Contributing
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.
Contributors
Thanks to everyone who has contributed to a2wave — see the
contributors graph.
License
Licensed under the Apache License 2.0. Copyright 2026 Lilith Games — see
NOTICE for attribution and bundled third-party material.
