Aqua CLI
A CLI for messaging between agents: node identities, contact invitations, inboxes and relay connectivity
- 259 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- The aqua serve node listens for inbound connections and accepts messages from approved contacts
- When a direct connection is unavailable, traffic may pass through the selected relay
- The webhook sends the content of inbound messages to the address you set
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/aquaDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The aqua serve node listens for inbound connections and accepts messages from approved contacts
- When a direct connection is unavailable, traffic may pass through the selected relay
- The webhook sends the content of inbound messages to the address you set
This is third-party code. Review the repository files before installing.
What it does
Aqua is a Go protocol and CLI for messaging between agents on different machines. Each node creates an identity with `aqua id`, listens through `aqua serve` and prints a connection address. The project originated in mistermorph but installs independently. Nodes exchange contact invitations. Once accepted, `aqua send` transmits messages, and incoming and outgoing messages are stored locally. `aqua inbox list --unread` lists unread items; watching the inbox can connect new messages to an agent workflow. Connections use libp2p node identities; a contact name alone does not identify a person or organization. When a direct connection is unavailable, `--relay-mode auto` tries a relay. `aqua serve --webhook <url>` forwards incoming events to a chosen handler. The repository’s `aqua-communication` skill describes installation, address exchange and the message-reading loop.
Who it is for. For developers who need messaging between agents on different machines and command-line contact management.
Good fit when
- Two agents on different machines need to talk and you do not want to run a shared server or chat
- You need to receive messages into a durable inbox and wake the agent with `aqua inbox watch`
- An agent should react to events through a webhook: `aqua serve --webhook` posts every message to your URL
- The connection goes through NAT or a firewall and you need a relay in `--relay-mode auto`
- A contact must be confirmed in both directions before agents start exchanging data
Not a fit when
- You need encrypted group chats: group end-to-end encryption is on the project's plan and not ready yet
- You need guaranteed delivery after a restart: webhook retries live in the process memory
- You need a peer directory or agent discovery: the online directory is only planned
- You only want to connect agents on one machine: passing data through a file or standard input is simpler
Example request
Start aqua serve with a relay in auto mode, show my address and send contact alice an invite with verificationLimitations
Before using `--verify`, confirm the peer identity through another trusted channel. The flag records a trust decision; it does not verify a person’s identity. Without it, the workflow uses trust on first use, or TOFU. Claimed connection encryption does not encrypt the local `~/.aqua` files containing keys, contacts and messages.
The node defaults to TCP and UDP on `0.0.0.0:6372`. A relay sees network addresses and routing metadata. Webhooks receive decrypted events; their in-memory retries are lost on restart.
Group end-to-end encryption and a persistent retransmission queue remain planned. Receiving messages requires a running process. Source installation uses Go 1.24.6 and toolchain 1.24.13; the license is Apache-2.0.
How to disable. Stop the aqua serve process and delete the aqua binary. Delete the node's local data with its identity and mailbox separately if you no longer need it.
FAQ
How do I install Aqua?
Run `go install github.com/quailyquaily/aqua/cmd/aqua@latest`. go.mod specifies Go 1.24.6 and toolchain 1.24.13; installation downloads dependencies and, if needed, Go tooling. Add the binary directory to PATH.
How do two agents start a conversation?
Both nodes create identities, start `aqua serve` and exchange the resulting addresses. The sender invites a contact, and the recipient inspects and accepts the invitation. Use `--verify` after checking identity through an independent channel, then begin messaging with `aqua send`.
What if a direct connection fails?
Start the node with --relay-mode auto and pass a relay with --relay. The node tries a direct connection and falls back to the relay. A relay you run needs its own identity that differs from the node identity.
How do I wake an agent on an incoming message?
Use aqua inbox watch for wake-ups on new messages, or run aqua serve --webhook with your handler URL. A POST request goes out for every inbound event, and failures are retried in the background.
Why does the repository contain SKILL.md?
The aqua-communication skill tells an agent the working order: install, get an ID, connect through a relay, send contact invites and run the inbox loop.
Discussion
No questions or reviews yet.
Related
CLI toolsOpen Agent Email — a self-hosted mail server for AI agents: inboxes, in-thread replies, human approval, webhooks and an MCP endpoint with 96 tools
An agent messages your phone or calls it over VoIP, a voice AI discusses the decision and the transcript returns to the agent
Connects Claude Code, Cursor, Codex or OpenCode to Telegram, Slack and Discord: teammates message a bot, an agent replies
A CLI that passes your WeChat messages to an agent through the official ClawBot (iLink) and sends replies back
A skill helps connect an agent to email and messaging through Caspian, with shared handling of incoming messages
A KakaoTalk CLI for Mac: the agent reads chats, searches messages and sends texts through client automation
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Aqua (this card) | no | 259 | |
| hcom | no | 638 | links agents in different terminals on one machine |
| AgentBridge: a bridge between Claude Code and Codex | no | 422 | a local bridge between Claude Code and Codex in one session |
README in short
The CLI stores messages on disk and supports inbox watching. It is a transport between programs: it includes no language model and does not turn a received message into an executed task without an attached agent process.
README badge
Original SKILL.md
--- name: aqua-communication description: "Aqua is a CLI-first message tool for AI agents. Use aqua CLI to exchange messages, manage contacts and invites, and drive agent inbox workflows with unread, watch, mark-read, or webhook-triggered serve integrations." --- # Aqua Communication Skill ## Goal Use `aqua` to establish trusted peer communication and exchange messages reliably between other agents. When acting as an agent, treat Aqua as: - transport + local mailbox - `aqua serve` for receiving traffic - `aqua inbox watch` for prompt wakeups - `aqua inbox list --unread` and `aqua inbox mark-read` for inbox-driven work loops - optional `aqua serve --webhook ...` when your runtime can supervise a long-lived daemon and prefers HTTP wakeups ## Identity Syntax * If you want to use aqua peer id to identify a peer in file or storage, use format `aqua:<PEER_ID>`, e.g., `aqua:12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E`. * If nickname is specified, use markdown-like syntax `[<nickname>](aqua:<PEER_ID>)`, e.g., `[John Wick](aqua:12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E)`. * The `<PEER_ID>` is the source of truth and `<nickname>` is an optional annotation for human-friendly display. * Use `aqua` cmd if you find this kind of syntax in the context or files. ## Defaults - Official `relay_host` for relay mode: `aqua-relay.mistermorph.com` - Official `relay_peer_id`: `12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E` - Official relay endpoint - TCP: `/dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E` - UDP (QUIC): `/dns4/aqua-relay.mistermorph.com/udp/6372/quic-v1/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E` ## Install Aqua CLI: ```bash curl -fsSL -o /tmp/install.sh https://raw.githubusercontent.com/quailyquaily/aqua/refs/heads/master/scripts/install.sh; \ sudo bash /tmp/install.sh ``` ## Quick Start with Official Relay Node (Recommended) 1. Get your peer ID and optionally set a nickname: