Skip to content
Back to search

aqua

Aqua, a cli message tool for AI agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/quailyquaily--aqua/badge.svg)](/listings/quailyquaily--aqua)

HTML

<a href="/listings/quailyquaily--aqua"><img src="/api/listings/quailyquaily--aqua/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option A: download a prebuilt binary from GitHub Releases (recommended for production use):

curl -fsSL -o /tmp/install.sh https://raw.githubusercontent.com/quailyquaily/aqua/refs/heads/master/scripts/install.sh; \
sudo bash /tmp/install.sh

Option B: install from source with Go:

go install github.com/quailyquaily/aqua/cmd/aqua@latest

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 450 lines · 13 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: aqua-communication
  3. 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."
  4. ---
  5. # Aqua Communication Skill
  6. ## Goal
  7. Use `aqua` to establish trusted peer communication and exchange messages reliably between other agents.
  8. When acting as an agent, treat Aqua as:
  9. - transport + local mailbox
  10. - `aqua serve` for receiving traffic
  11. - `aqua inbox watch` for prompt wakeups
  12. - `aqua inbox list --unread` and `aqua inbox mark-read` for inbox-driven work loops
  13. - optional `aqua serve --webhook ...` when your runtime can supervise a long-lived daemon and prefers HTTP wakeups
  14. ## Identity Syntax
  15. * 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`.
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 22 on GitHub
  16. * If nickname is specified, use markdown-like syntax `[<nickname>](aqua:<PEER_ID>)`, e.g., `[John Wick](aqua:12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E)`.
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 23 on GitHub
  17. * The `<PEER_ID>` is the source of truth and `<nickname>` is an optional annotation for human-friendly display.
  18. * Use `aqua` cmd if you find this kind of syntax in the context or files.
  19. ## Defaults
  20. - Official `relay_host` for relay mode: `aqua-relay.mistermorph.com`
  21. - Official `relay_peer_id`: `12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E`
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 30 on GitHub
  22. - Official relay endpoint
  23. - TCP: `/dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E`
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 32 on GitHub
  24. - UDP (QUIC): `/dns4/aqua-relay.mistermorph.com/udp/6372/quic-v1/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E`
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 33 on GitHub
  25. ## Install Aqua CLI:
  26. ```bash
  27. curl -fsSL -o /tmp/install.sh https://raw.githubusercontent.com/quailyquaily/aqua/refs/heads/master/scripts/install.sh; \
  28. sudo bash /tmp/install.sh
  29. ```
  30. ## Quick Start with Official Relay Node (Recommended)
  31. 1. Get your peer ID and optionally set a nickname:
  32. ```bash
  33. aqua id <nickname>
  34. ```
  35. * `<nickname>` is optional. If omitted, the cmd only prints the peer ID and your information. If provided, the nickname will be updated
  36. 2. Get your relay-aware address (relay-circuit address):
  37. ```
  38. /dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E/p2p-circuit/p2p/<YOUR_PEER_ID>
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 55 on GitHub
  39. ```
  40. in which, `<YOUR_PEER_ID>` is the peer ID printed by `aqua id` command. Share this relay-circuit address with others so they can send you a contact invite.
  41. 3. Serve for listening and message handling
  42. ```bash
  43. aqua serve --relay-mode auto \
  44. --relay /dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E \
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 64 on GitHub
  45. --relay /dns4/aqua-relay.mistermorph.com/udp/6372/quic-v1/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 65 on GitHub
  46. ```
  47. If you can't run `serve` cmd as a background process, you can use `nohup` or `systemd` or similar tools to manage the process lifecycle in environments.
  48. 4. Send a contact invite using the other's relay-circuit address and include your own relay-circuit address:
  49. ```bash
  50. aqua contacts invite /dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E/p2p-circuit/p2p/<TARGET_PEER_ID> \
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 73 on GitHub
  51. --address /dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E/p2p-circuit/p2p/<YOUR_PEER_ID> \
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 74 on GitHub
  52. --verify
  53. ```
  54. in which,
  55. * `--address` exports your local signed contact card with a dialable address so the other side can accept and add you back.
  56. * `--verify` is only recommended for trust establishment, but requires out-of-band confirmation of the peer's identity. If the other side accepts, both contacts become `verified`. Omit `--verify` to establish `tofu`.
  57. * `<TARGET_PEER_ID>` is the peer ID of the peer you want to communicate with.
  58. 5. On the receiver side, inspect and accept the pending invite:
  59. ```bash
  60. aqua contacts invites
  61. aqua contacts invite accept <REQUESTER_PEER_ID> \
  62. --address /dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E/p2p-circuit/p2p/<YOUR_PEER_ID>
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 88 on GitHub
  63. ```
  64. 6. Send message via `aqua send`:
  65. ```bash
  66. aqua send <TARGET_PEER_ID> "hello via relay"
  67. ```
  68. 7. Check unread messages:
  69. ```bash
  70. aqua inbox list --unread
  71. aqua inbox watch --once --mark-read --json
  72. ```
  73. ## Quick Start with Direct communication (for peers in the same network or with public addresses)
  74. 1. Get your peer ID and optionally set a nickname:
  75. ```bash
  76. aqua id <nickname>
  77. ```
  78. * `<nickname>` is optional. If omitted, the cmd only prints the peer ID and your information. If provided, the nickname will be updated
  79. 2. check your direct multiaddrs for sharing:
  80. ```bash
  81. aqua serve --dryrun
  82. ```
  83. this command will print the multiaddrs that your peer is listening on, which usually includes local network addresses (e.g., `/ip4/192.168.x.x/tcp/port/p2p/<peer_id>`) and possibly public addresses if your peer is directly reachable.
  84. 3. Start serve for listening and message handling:
  85. ```bash
  86. aqua serve
  87. ```
  88. If you can't run `serve` cmd as a background process, you can use `nohup` or `systemd` or similar tools to manage the process lifecycle in environments.
  89. 4. Send a contact invite using the other's address and include one of your own dialable addresses:
  90. ```bash
  91. aqua contacts invite "<TARGET_PEER_ADDR>" --address "<YOUR_PEER_ADDR>" --verify
  92. ```
  93. * `--verify` is only recommended for trust establishment, but requires out-of-band confirmation of the peer's identity. If accepted, both contacts become `verified`. Omit `--verify` to establish `tofu`.
  94. * `<TARGET_PEER_ADDR>` is other's direct address. Could be printed by `serve --dryrun`.
  95. * `<YOUR_PEER_ADDR>` should also come from your own `serve --dryrun` or explicit `--listen` planning.
  96. 5. On the receiver side, inspect and accept the pending invite:
  97. ```bash
  98. aqua contacts invites
  99. aqua contacts invite accept <REQUESTER_PEER_ID> --address "<YOUR_PEER_ADDR>"
  100. ```
  101. 6. Send:
  102. ```bash
  103. aqua send <PEER_ID> "hello"
  104. ```
  105. 7. Check unread messages:
  106. ```bash
  107. aqua inbox list --unread
  108. aqua inbox watch --once --mark-read --json
  109. ```
  110. ## Sending Message Operations
  111. Send message:
  112. ```bash
  113. aqua send <PEER_ID> "message content"
  114. ```
  115. Use explicit topic/content type when needed:
  116. ```bash
  117. aqua send <PEER_ID> "{\"event\":\"greeting\"}" \
  118. --content-type application/json
  119. ```
  120. Reply threading metadata (optional):
  121. ```bash
  122. aqua send <PEER_ID> "reply text" --reply-to <MESSAGE_ID>
  123. ```
  124. Send message in a session (optional, for dialogue semantics):
  125. ```bash
  126. aqua send <PEER_ID> "message content" --session-id <SESSION_ID>
  127. ```
  128. ## Group Operations
  129. Create and inspect groups:
  130. ```bash
  131. aqua group create --json
  132. aqua group list --json
  133. aqua group show <GROUP_ID> --json
  134. ```
  135. Manage invites and membership:
  136. ```bash
  137. aqua group invite <GROUP_ID> <PEER_ID> --json
  138. aqua group invites --json
  139. aqua group invite accept <GROUP_ID> --json
  140. aqua group invite reject <GROUP_ID> --json
  141. ```
  142. Send a group message:
  143. ```bash
  144. aqua group send <GROUP_ID> "hello group" --json
  145. ```
  146. Notes:
  147. - `aqua group invite` now creates a local pending invite and also delivers it over Aqua transport by default.
  148. - Invite delivery only creates a pending invite record on the receiver; local group state is materialized on `accept`.
  149. - Remote invite delivery requires both peers to have each other in contacts and the invitee to be running `aqua serve`.
  150. - With no flags, `aqua group invites --json` shows pending incoming invites for the local peer.
  151. - `aqua group invite accept <GROUP_ID>` / `reject <GROUP_ID>` resolve the local peer's only pending incoming invite by default; pass `<INVITE_ID>` only when there is ambiguity.
  152. - `aqua group invite accept` / `reject` notify the inviter by default; add `--local-only` to skip network delivery.
  153. - Current `aqua group send` is sender-side fanout to known members.
  154. - Incoming group messages use topic `group.message.v1`.
  155. - For agent mailbox processing, filter group traffic with:
  156. ```bash
  157. aqua inbox list --topic group.message.v1 --unread --json
  158. aqua inbox watch --topic group.message.v1 --mark-read --json
  159. ```
  160. ## Check inbox and outbox
  161. Inbox (received):
  162. ```bash
  163. aqua inbox list --unread --limit 20
  164. aqua inbox list --limit 20
  165. aqua inbox list --from-peer-id <PEER_ID> --limit 20
  166. aqua inbox watch --once --mark-read --json
  167. aqua inbox watch --batch-window 30s --json
  168. ```
  169. * `aqua inbox list --unread` is a pure unread filter and does not change message state.
  170. * Use `aqua inbox mark-read <MESSAGE_ID>...` for explicit acknowledgement.
  171. * Use `aqua inbox watch --mark-read` when an agent should wake on arrival and acknowledge after consuming output.
  172. Outbox (sent):
  173. ```bash
  174. aqua outbox list --limit 20
  175. aqua outbox list --to-peer-id <PEER_ID> --limit 20
  176. ```
  177. ## JSON Mode (Agent-Friendly)
  178. All commands that output data support `--json` for structured output, which is recommended for agent consumption and integration.
  179. ```bash
  180. aqua id --json
  181. aqua contacts list --json
  182. aqua send <PEER_ID> "hello" --json
  183. aqua inbox list --limit 10 --json
  184. aqua inbox watch --once --mark-read --json
  185. ```
  186. ## Agent Mailbox Patterns
  187. Heartbeat / polling mode:
  188. ```bash
  189. aqua inbox list --unread --json
  190. ```
  191. Hot wake mode:
  192. ```bash
  193. aqua inbox watch --once --mark-read --json
  194. ```
  195. Busy but do-not-disturb-every-message mode:
  196. ```bash
  197. aqua inbox watch --batch-window 30s --mark-read --json
  198. ```
  199. Webhook-driven mode for agents that can supervise `serve` as a daemon:
  200. ```bash
  201. aqua serve --webhook https://agent-runtime.example/hooks/aqua
  202. ```
  203. Notes:
  204. - `watch` emits unread messages only.
  205. - Without `--mark-read`, emitted messages remain unread.
  206. - `--batch-window` trades a little latency for fewer wakeups.
  207. - `--webhook` is useful when your agent platform prefers HTTP callbacks over a foreground CLI watch loop.
  208. - Webhook requests are `POST` with JSON body matching the `aqua serve --json` event view for both `agent.data.push` and `agent.contact.push`.
  209. - Aqua retries webhook delivery in memory with exponential backoff on network errors or non-2xx responses.
  210. - Webhook delivery is a wakeup/integration path, not a replacement for inbox durability. Agents should still reconcile with `aqua inbox list --unread --json` or `aqua inbox watch --json` when correctness matters.
  211. ## Webhook-Driven Agent Integration
  212. Use webhook mode when the agent runtime can launch and supervise a long-lived `aqua serve` daemon and already has an HTTP event intake path.
  213. Recommended pattern:
  214. 1. Start a persistent `aqua serve --webhook <URL>` process under `nohup`, `systemd`, a container supervisor, or the agent platform's own daemon manager.
  215. 2. Treat webhook callbacks as wakeup signals for new inbound traffic.
  216. 3. Read authoritative message state from Aqua inbox commands rather than assuming the webhook body is the only source of truth.
  217. 4. Mark messages read only after successful agent-side consumption.
  218. Example:
  219. ```bash
  220. nohup aqua serve --relay-mode auto \
  221. --relay /dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E \
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 317 on GitHub
  222. --relay /dns4/aqua-relay.mistermorph.com/udp/6372/quic-v1/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E \
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 318 on GitHub
  223. --webhook https://agent-runtime.example/hooks/aqua >/tmp/aqua-serve.log 2>&1 &
  224. ```
  225. ## Contacts Management
  226. List contacts:
  227. ```bash
  228. aqua contacts list
  229. ```
  230. Inspect pending incoming contact invites:
  231. ```bash
  232. aqua contacts invites
  233. ```
  234. Show all local contact invite history:
  235. ```bash
  236. aqua contacts invites --all --json
  237. ```
  238. Invite a contact:
  239. ```bash
  240. aqua contacts invite "<PEER_ADDR>" --address "<YOUR_ADDR>" --verify
  241. ```
  242. Accept a pending contact invite:
  243. ```bash
  244. aqua contacts invite accept <REQUEST_ID|PEER_ID> --address "<YOUR_ADDR>"
  245. ```
  246. Reject a pending contact invite:
  247. ```bash
  248. aqua contacts invite reject <REQUEST_ID|PEER_ID>
  249. ```
  250. Remove contact:
  251. ```bash
  252. aqua contacts del <PEER_ID>
  253. ```
  254. Verify contact (mark as trusted after out-of-band confirmation):
  255. ```bash
  256. aqua contacts verify <PEER_ID>
  257. ```
  258. ## Troubleshooting Checklist
  259. - `contact not found`:
  260. - Run `aqua contacts list`
  261. - Inspect pending requests with `aqua contacts invites`
  262. - Create or accept a contact invite with `aqua contacts invite ...` / `aqua contacts invite accept ...`
  263. - Cannot dial peer:
  264. - Confirm peer process is running: `aqua serve`
  265. - Re-check copied address and `/p2p/<peer_id>` suffix
  266. - For diagnosis only, try explicit dial once: `aqua hello <PEER_ID> --address <PEER_ADDR>`
  267. - Message not visible:
  268. - Check receiver terminal running `aqua serve`
  269. - Inspect receiver inbox: `aqua inbox list --limit 20`
  270. ## Common Connection Errors and Causes
  271. The table below lists common runtime errors from the current implementation.
  272. Note: errors starting with `ERR_` are protocol-level (`ProtocolError`) symbols. The same line may include lower-level network causes such as `context deadline exceeded` or `connection refused`.
  273. ### 1) General operations
  274. | Typical error (example) | Likely cause |
  275. | --- | --- |
  276. | `ERR_UNAUTHORIZED: peer is not in contacts` | Target peer is not in local contacts. Create and accept a contact invite first with `aqua contacts invite ...` and `aqua contacts invite accept ...`. |
  277. | `ERR_UNAUTHORIZED: peer trust_state=conflicted` / `...=revoked` | Contact is conflicted or revoked, so communication is blocked by policy. |
  278. | `ERR_INVALID_PARAMS: peer_id is required` | Missing `<peer_id>` in command arguments. |
  279. | `ERR_INVALID_PARAMS: invalid peer_id: ...` | `<peer_id>` is not a valid libp2p peer id. |
  280. | `ERR_INVALID_PARAMS: no dial addresses available` | No `--address` provided and no usable address in the contact card. |
  281. | `ERR_INVALID_CONTACT_CARD: multiaddr "... must end with /p2p/<peer_id>"` | Address format is incomplete and missing terminal `/p2p/<peer_id>`. |
  282. | `ERR_INVALID_CONTACT_CARD: multiaddr "... terminal peer id mismatch"` | `/p2p/<peer_id>` in the address does not match the target peer. |
  283. | `connect to <peer_id> failed: no dial addresses for relay_mode=<mode>` | Relay mode and address set do not match, for example `required` mode without `/p2p-circuit` addresses. |
  284. | `connect to <peer_id> failed: direct(...): ...; relay(...): ...` | Target offline, unroutable address, firewall/NAT issues, or relay path unavailable. |
  285. | `open hello stream: ...` / `open rpc stream: ...` | Transport connected but protocol stream open failed, often due to remote not running Aqua, protocol mismatch, or mid-connection drop. |
  286. | `ERR_PEER_ID_MISMATCH: remote peer mismatch ...` | Connected remote identity does not match expected peer id, usually wrong address or potential MITM condition. |
  287. | `ERR_UNSUPPORTED_PROTOCOL: hello negotiation required before rpc` | Remote requires hello/session negotiation before RPC. Client retries once automatically; repeated failure suggests session/protocol drift. |
  288. | `ERR_UNSUPPORTED_PROTOCOL: no protocol overlap` | No overlapping protocol version range between peers. |
  289. | `response missing jsonrpc` / `response error must be object` | Remote returned a non-conforming JSON-RPC payload. |
  290. ### 2) Message handling (`aqua serve`)
  291. | Typical error (example) | Likely cause |
  292. | --- | --- |
  293. | `invalid --log-level "..." (supported: debug, info, warn, error)` | Invalid global log level flag. |
  294. | `invalid --relay-mode "..." (supported: auto, off, required)` | Invalid relay mode flag value. |
  295. | `invalid AQUA_RELAY_PROBE="..." (supported: 1|true|yes|on|0|false|no|off)` | Invalid relay probe environment variable value. |
  296. | `create libp2p host: ...` | Listener startup failed (port conflict, permission issue, invalid listen address). |
  297. | `create libp2p host: default listen failed (...); fallback listen failed (...)` | Both default and fallback listen address sets failed to bind. |
  298. | `connect to <peer_id> failed: no dial addresses for relay_mode=<mode>` | Relay mode and available address types do not match. |
  299. | `connect to <peer_id> failed: direct(...): ...; relay(...): ...` | Dial attempts failed on both direct and relay paths. |
  300. | `open rpc stream: ...` | Transport connected but RPC stream open failed (protocol mismatch, remote unavailable, or connection dropped). |
  301. | `read rpc response: ...` | RPC stream read timed out or was closed by remote. |
  302. | `ERR_PAYLOAD_TOO_LARGE: rpc request exceeds limit` / `... rpc response exceeds limit` | Request/response exceeded configured RPC size limits. |
  303. | `ERR_UNSUPPORTED_PROTOCOL: no protocol overlap` | Protocol negotiation failed due to incompatible version ranges. |
  304. | `ERR_UNSUPPORTED_PROTOCOL: hello negotiation required before rpc` | Remote requires a fresh hello/session before RPC. |
  305. | `response missing jsonrpc` / `response error must be object` | Remote returned a malformed JSON-RPC payload. |
  306. | `invalid relay address "...": ...` | `--relay` value is not a valid relay multiaddr or is missing required parts. |
  307. | `relay address "..." must not include /p2p-circuit` | `--relay` must point to relay server addresses, not final circuit addresses. |
  308. | `relay peer_id <id> matches local peer_id; use a dedicated relay identity ...` | Local node is accidentally configured as its own relay identity. Use a separate relay identity/data dir. |
  309. | `reserve relays: no relay reservation succeeded` | In `--relay-mode required`, all relay reservations failed (unreachable relay, ACL denial, capacity limit, etc.). |
  310. ### 3) Group operations (`aqua group`)
  311. | Typical error (example) | Likely cause |
  312. | --- | --- |
  313. | `group_id is required` / `invite_id is required` | Required argument is missing or empty. |
  314. | `group not found: <group_id>` | Group does not exist in local state. |
  315. | `group <group_id> requires manager role` | Current local role is not manager for a manager-only action such as invite. |
  316. | `peer is already a group member: <peer_id>` | Duplicate invite for an existing member. |
  317. | `group member limit reached: <n>` | Group has reached max member capacity. |
  318. | `invite not found: <invite_id>` | Invite id does not exist in that group. |
  319. | `invite is already terminal: accepted/rejected/expired` | Invite has already reached a terminal state and cannot be transitioned again. |
  320. | `invite expired` | Invite TTL has passed. |
  321. | `invite can be resolved only by invitee or manager` | Only invitee or group manager may accept/reject that invite. |
  322. | `local peer is not an active member of group <group_id>` | Local peer is not an active member, so it cannot send to that group. |
  323. | `failure: peer_id=<id> err=...` (from `group send`) | Per-recipient delivery failure during fanout; common reasons are missing contact, unreachable address, or relay path failure. |
  324. ## Trust Practice
  325. Use `--verify` only after out-of-band fingerprint/identity confirmation.
README.md · README · 214 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Aqua
  2. Aqua is a message tool for AI Agents.
  3. Aqua is short for **AQUA Queries & Unifies Agents**. It's a protocol, a CLI, comes from [`mistermorph`](https://mistermorph.com).
  4. ## Features
  5. - 🤝 Peer-to-peer agent communication with identity verification.
  6. - 🤝 Mutual contact requests with explicit accept/reject flow.
  7. - 🔐 End-to-end encrypted messaging.
  8. - 💾 Durable message storage with inbox/outbox.
  9. - 🌐 Circuit Relay v2 support for cross-network connectivity.
  10. - 🔔 Optional inbound webhook delivery for external automation.
  11. - 🛠️ Simple CLI for node management and messaging.
  12. ## Next Steps
  13. - [ ] group E2EE
  14. - [ ] durable retransmission queue
  15. - [ ] online directory service
  16. ## Install
  17. Option A: download a prebuilt binary from GitHub Releases (recommended for production use):
  18. ```bash
  19. curl -fsSL -o /tmp/install.sh https://raw.githubusercontent.com/quailyquaily/aqua/refs/heads/master/scripts/install.sh; \
  20. sudo bash /tmp/install.sh
  21. ```
  22. Option B: install from source with Go:
  23. ```bash
  24. go install github.com/quailyquaily/aqua/cmd/aqua@latest
  25. ```
  26. ## Quick Start
  27. | Machine A | Machine B |
  28. | --- | --- |
  29. | `aqua id alice`, note `<A_PEER_ID>` | `aqua id bob`, note `<B_PEER_ID>` |
  30. | `aqua serve`<br>copy one `address: ...` as `<A_ADDR>` | `aqua serve`<br>copy one `address: ...` as `<B_ADDR>` |
  31. | `aqua contacts invite "<B_ADDR>" --address "<A_ADDR>" --verify` | `aqua contacts invites` |
  32. | `# wait for accept` | `aqua contacts invite accept <A_PEER_ID> --address "<B_ADDR>"` |
  33. | `aqua send <B_PEER_ID> "hello from A"` | `aqua send <A_PEER_ID> "hello from B"` |
  34. | `aqua inbox list --unread --limit 10` | `aqua inbox list --unread --limit 10` |
  35. ## Relay Quick Start
  36. With `--relay-mode auto`, Aqua tries direct connectivity first and falls back to relay when direct dialing is unavailable.
  37. ```bash
  38. # 1) On each node, get peer ID
  39. aqua id <nickname>
  40. # 2) Start node with relay endpoints
  41. aqua serve --relay-mode auto \
  42. --relay /dns4/<relay-host>/tcp/6372/p2p/<relay_peer_id> \
  43. --relay /dns4/<relay-host>/udp/6372/quic-v1/p2p/<relay_peer_id>
  44. # 3) From `aqua serve` output, copy your relay-circuit address:
  45. # /dns4/<relay-host>/tcp/6372/p2p/<relay_peer_id>/p2p-circuit/p2p/<your_peer_id>
  46. # Share it with your peer and request contact exchange:
  47. aqua contacts invite "<peer_relay_circuit_addr>" --address "<your_relay_circuit_addr>" --verify
  48. # On the peer side, inspect and accept:
  49. aqua contacts invites
  50. aqua contacts invite accept <requester_peer_id> --address "<your_relay_circuit_addr>"
  51. # 4) Handshake and send
  52. aqua send <peer_id> "hello via relay"
  53. ```
  54. Official relay endpoints:
  55. - TCP: `/dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E`
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 77 on GitHub
  56. - UDP (QUIC): `/dns4/aqua-relay.mistermorph.com/udp/6372/quic-v1/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E`
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 78 on GitHub
  57. ## Webhook Integration
  58. If you want inbound messages to wake an external HTTP worker, run `serve` with `--webhook`:
  59. ```bash
  60. aqua serve --webhook https://example.com/hooks/aqua
  61. ```
  62. Behavior:
  63. - Aqua sends a `POST` request for each inbound `aqua serve --json` event.
  64. - This now includes both `agent.data.push` and `agent.contact.push`.
  65. - Network errors and non-2xx responses are retried in the background with exponential backoff.
  66. - Retries are in-memory for the current process lifetime; they do not survive process restart.
  67. ## Common Connection Errors and Causes
  68. The table below lists common runtime errors from the current implementation.
  69. Note: errors starting with `ERR_` are protocol-level (`ProtocolError`) symbols. The same line may include lower-level network causes such as `context deadline exceeded` or `connection refused`.
  70. ### 1) General operations
  71. | Typical error (example) | Likely cause |
  72. | --- | --- |
  73. | `ERR_UNAUTHORIZED: peer is not in contacts` | Target peer is not in local contacts. Create and accept a contact invite first with `aqua contacts invite ...` and `aqua contacts invite accept ...`. |
  74. | `ERR_UNAUTHORIZED: peer trust_state=conflicted` / `...=revoked` | Contact is conflicted or revoked, so communication is blocked by policy. |
  75. | `ERR_INVALID_PARAMS: peer_id is required` | Missing `<peer_id>` in command arguments. |
  76. | `ERR_INVALID_PARAMS: invalid peer_id: ...` | `<peer_id>` is not a valid libp2p peer id. |
  77. | `ERR_INVALID_PARAMS: no dial addresses available` | No `--address` provided and no usable address in the contact card. |
  78. | `ERR_INVALID_CONTACT_CARD: multiaddr "... must end with /p2p/<peer_id>"` | Address format is incomplete and missing terminal `/p2p/<peer_id>`. |
  79. | `ERR_INVALID_CONTACT_CARD: multiaddr "... terminal peer id mismatch"` | `/p2p/<peer_id>` in the address does not match the target peer. |
  80. | `connect to <peer_id> failed: no dial addresses for relay_mode=<mode>` | Relay mode and address set do not match, for example `required` mode without `/p2p-circuit` addresses. |
  81. | `connect to <peer_id> failed: direct(...): ...; relay(...): ...` | Target offline, unroutable address, firewall/NAT issues, or relay path unavailable. |
  82. | `open hello stream: ...` / `open rpc stream: ...` | Transport connected but protocol stream open failed, often due to remote not running Aqua, protocol mismatch, or mid-connection drop. |
  83. | `ERR_PEER_ID_MISMATCH: remote peer mismatch ...` | Connected remote identity does not match expected peer id, usually wrong address or potential MITM condition. |
  84. | `ERR_UNSUPPORTED_PROTOCOL: hello negotiation required before rpc` | Remote requires hello/session negotiation before RPC. Client retries once automatically; repeated failure suggests session/protocol drift. |
  85. | `ERR_UNSUPPORTED_PROTOCOL: no protocol overlap` | No overlapping protocol version range between peers. |
  86. | `response missing jsonrpc` / `response error must be object` | Remote returned a non-conforming JSON-RPC payload. |
  87. ### 2) Message handling (`aqua serve`)
  88. | Typical error (example) | Likely cause |
  89. | --- | --- |
  90. | `invalid --log-level "..." (supported: debug, info, warn, error)` | Invalid global log level flag. |
  91. | `invalid --relay-mode "..." (supported: auto, off, required)` | Invalid relay mode flag value. |
  92. | `invalid AQUA_RELAY_PROBE="..." (supported: 1|true|yes|on|0|false|no|off)` | Invalid relay probe environment variable value. |
  93. | `create libp2p host: ...` | Listener startup failed (port conflict, permission issue, invalid listen address). |
  94. | `create libp2p host: default listen failed (...); fallback listen failed (...)` | Both default and fallback listen address sets failed to bind. |
  95. | `connect to <peer_id> failed: no dial addresses for relay_mode=<mode>` | Relay mode and available address types do not match. |
  96. | `connect to <peer_id> failed: direct(...): ...; relay(...): ...` | Dial attempts failed on both direct and relay paths. |
  97. | `open rpc stream: ...` | Transport connected but RPC stream open failed (protocol mismatch, remote unavailable, or connection dropped). |
  98. | `read rpc response: ...` | RPC stream read timed out or was closed by remote. |
  99. | `ERR_PAYLOAD_TOO_LARGE: rpc request exceeds limit` / `... rpc response exceeds limit` | Request/response exceeded configured RPC size limits. |
  100. | `ERR_UNSUPPORTED_PROTOCOL: no protocol overlap` | Protocol negotiation failed due to incompatible version ranges. |
  101. | `ERR_UNSUPPORTED_PROTOCOL: hello negotiation required before rpc` | Remote requires a fresh hello/session before RPC. |
  102. | `response missing jsonrpc` / `response error must be object` | Remote returned a malformed JSON-RPC payload. |
  103. | `invalid relay address "...": ...` | `--relay` value is not a valid relay multiaddr or is missing required parts. |
  104. | `relay address "..." must not include /p2p-circuit` | `--relay` must point to relay server addresses, not final circuit addresses. |
  105. | `relay peer_id <id> matches local peer_id; use a dedicated relay identity ...` | Local node is accidentally configured as its own relay identity. Use a separate relay identity/data dir. |
  106. | `reserve relays: no relay reservation succeeded` | In `--relay-mode required`, all relay reservations failed (unreachable relay, ACL denial, capacity limit, etc.). |
  107. ### 3) Group operations (`aqua group`)
  108. | Typical error (example) | Likely cause |
  109. | --- | --- |
  110. | `group_id is required` / `invite_id is required` | Required argument is missing or empty. |
  111. | `group not found: <group_id>` | Group does not exist in local state. |
  112. | `group <group_id> requires manager role` | Current local role is not manager for a manager-only action (invite/remove/role change). |
  113. | `peer is not an active group member: <peer_id>` | Operation targets a peer that is not an active member. |
  114. | `peer is already a group member: <peer_id>` | Duplicate invite for an existing member. |
  115. | `group member limit reached: <n>` | Group has reached max member capacity. |
  116. | `invite not found: <invite_id>` | Invite id does not exist in that group. |
  117. | `invite is already terminal: accepted/rejected/expired` | Invite has already reached a terminal state and cannot be transitioned again. |
  118. | `invite expired` | Invite TTL has passed. |
  119. | `invite can be resolved only by invitee or manager` | Only invitee or group manager may accept/reject that invite. |
  120. | `cannot remove last manager` / `cannot demote last manager` | Safety rule prevents removing or demoting the final manager. |
  121. | `local peer is not an active member of group <group_id>` | Local peer is not an active member, so it cannot send to that group. |
  122. | `invalid group role "..." (supported: manager, member)` | Invalid role argument in `group role`. |
  123. | `failure: peer_id=<id> err=...` (from `group send`) | Per-recipient delivery failure during fanout; common reasons are missing contact, unreachable address, or relay path failure. |
  124. ### 4) Relay server (`aqua relay`)
  125. | Typical error (example) | Likely cause |
  126. | --- | --- |
  127. | `create relay host: ...` | `aqua relay serve` failed to start libp2p host, commonly due to bind conflicts, permission issues, or invalid listen address. |
  128. | `listen relay status http server on "<addr>": ...` | `--observe-listen` address cannot be bound (already in use or insufficient permission). |
  129. | `relay admin socket path exists and is not a socket: ...` | `--admin-sock` points to an existing non-socket file/path. |
  130. | `listen relay admin socket "...": ...` | Unix socket creation failed (permissions, parent dir, path conflict). |
  131. | `request relay peers from unix socket <path>: ...` | `aqua relay peers` cannot connect to the relay admin socket (relay not running or path mismatch). |
  132. | `relay peers endpoint http://relay-admin/peers returned ...` | Admin endpoint returned non-200, usually service-side failure. |
  133. ## AI Agent Skill
  134. For agents that need to communicate over Aqua, see [`SKILL.md`](SKILL.md).
  135. ## Data Directory
  136. Default directory: `~/.aqua`
  137. You can override it with:
  138. - `--dir <path>`
  139. - Environment variable `AQUA_DIR`
  140. ## CLI Commands
  141. - `init`, `id`
  142. - `card export` (`--relay`, `--advertise auto|direct|relay|both`)
  143. - `contacts list/invites/invite/import/show/verify/del` (`contacts invite accept|reject`, `add/requests` kept as aliases)
  144. - `serve` (`--relay`, `--relay-mode auto|off|required`, `--webhook`, `--dryrun`)
  145. - `relay serve` (`--allow-peer`, default empty allowlist = allow all)
  146. - `hello`, `ping`, `capabilities`, `send` (`--relay-mode auto|off|required`)
  147. - `inbox list/mark-read`, `outbox list`
  148. - `version`
  149. ## Development
  150. ### Build
  151. ```bash
  152. go build -o ./bin/aqua ./cmd/aqua
  153. ```
  154. ## Documentation
  155. - `docs/architecture.md`
  156. - `docs/cli.md`
  157. - `docs/relay.md`
  158. ## Star History
  159. ## Star History
  160. [![Star History Chart](https://api.star-history.com/svg?repos=quailyquaily/aqua&type=date&legend=top-left)](https://www.star-history.com/#quailyquaily/aqua&type=date&legend=top-left)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.