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.
Badge for your README
Markdown
[](/listings/quailyquaily--aqua)HTML
<a href="/listings/quailyquaily--aqua"><img src="/api/listings/quailyquaily--aqua/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- ---
- 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`.
- Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
- Line 22 on GitHub
- * 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
- * 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`
- Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
- Line 30 on GitHub
- - Official relay endpoint
- - 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
- - 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
- ## 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:
- ```bash
- aqua id <nickname>
- ```
- * `<nickname>` is optional. If omitted, the cmd only prints the peer ID and your information. If provided, the nickname will be updated
- 2. Get your relay-aware address (relay-circuit 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 55 on GitHub
- ```
- 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.
- 3. Serve for listening and message handling
- ```bash
- aqua serve --relay-mode auto \
- --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
- --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
- ```
- 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.
- 4. Send a contact invite using the other's relay-circuit address and include your own relay-circuit address:
- ```bash
- 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
- --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
- --verify
- ```
- in which,
- * `--address` exports your local signed contact card with a dialable address so the other side can accept and add you back.
- * `--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`.
- * `<TARGET_PEER_ID>` is the peer ID of the peer you want to communicate with.
- 5. On the receiver side, inspect and accept the pending invite:
- ```bash
- aqua contacts invites
- aqua contacts invite accept <REQUESTER_PEER_ID> \
- --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
- ```
- 6. Send message via `aqua send`:
- ```bash
- aqua send <TARGET_PEER_ID> "hello via relay"
- ```
- 7. Check unread messages:
- ```bash
- aqua inbox list --unread
- aqua inbox watch --once --mark-read --json
- ```
- ## Quick Start with Direct communication (for peers in the same network or with public addresses)
- 1. Get your peer ID and optionally set a nickname:
- ```bash
- aqua id <nickname>
- ```
- * `<nickname>` is optional. If omitted, the cmd only prints the peer ID and your information. If provided, the nickname will be updated
- 2. check your direct multiaddrs for sharing:
- ```bash
- aqua serve --dryrun
- ```
- 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.
- 3. Start serve for listening and message handling:
- ```bash
- aqua serve
- ```
- 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.
- 4. Send a contact invite using the other's address and include one of your own dialable addresses:
- ```bash
- aqua contacts invite "<TARGET_PEER_ADDR>" --address "<YOUR_PEER_ADDR>" --verify
- ```
- * `--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`.
- * `<TARGET_PEER_ADDR>` is other's direct address. Could be printed by `serve --dryrun`.
- * `<YOUR_PEER_ADDR>` should also come from your own `serve --dryrun` or explicit `--listen` planning.
- 5. On the receiver side, inspect and accept the pending invite:
- ```bash
- aqua contacts invites
- aqua contacts invite accept <REQUESTER_PEER_ID> --address "<YOUR_PEER_ADDR>"
- ```
- 6. Send:
- ```bash
- aqua send <PEER_ID> "hello"
- ```
- 7. Check unread messages:
- ```bash
- aqua inbox list --unread
- aqua inbox watch --once --mark-read --json
- ```
- ## Sending Message Operations
- Send message:
- ```bash
- aqua send <PEER_ID> "message content"
- ```
- Use explicit topic/content type when needed:
- ```bash
- aqua send <PEER_ID> "{\"event\":\"greeting\"}" \
- --content-type application/json
- ```
- Reply threading metadata (optional):
- ```bash
- aqua send <PEER_ID> "reply text" --reply-to <MESSAGE_ID>
- ```
- Send message in a session (optional, for dialogue semantics):
- ```bash
- aqua send <PEER_ID> "message content" --session-id <SESSION_ID>
- ```
- ## Group Operations
- Create and inspect groups:
- ```bash
- aqua group create --json
- aqua group list --json
- aqua group show <GROUP_ID> --json
- ```
- Manage invites and membership:
- ```bash
- aqua group invite <GROUP_ID> <PEER_ID> --json
- aqua group invites --json
- aqua group invite accept <GROUP_ID> --json
- aqua group invite reject <GROUP_ID> --json
- ```
- Send a group message:
- ```bash
- aqua group send <GROUP_ID> "hello group" --json
- ```
- Notes:
- - `aqua group invite` now creates a local pending invite and also delivers it over Aqua transport by default.
- - Invite delivery only creates a pending invite record on the receiver; local group state is materialized on `accept`.
- - Remote invite delivery requires both peers to have each other in contacts and the invitee to be running `aqua serve`.
- - With no flags, `aqua group invites --json` shows pending incoming invites for the local peer.
- - `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.
- - `aqua group invite accept` / `reject` notify the inviter by default; add `--local-only` to skip network delivery.
- - Current `aqua group send` is sender-side fanout to known members.
- - Incoming group messages use topic `group.message.v1`.
- - For agent mailbox processing, filter group traffic with:
- ```bash
- aqua inbox list --topic group.message.v1 --unread --json
- aqua inbox watch --topic group.message.v1 --mark-read --json
- ```
- ## Check inbox and outbox
- Inbox (received):
- ```bash
- aqua inbox list --unread --limit 20
- aqua inbox list --limit 20
- aqua inbox list --from-peer-id <PEER_ID> --limit 20
- aqua inbox watch --once --mark-read --json
- aqua inbox watch --batch-window 30s --json
- ```
- * `aqua inbox list --unread` is a pure unread filter and does not change message state.
- * Use `aqua inbox mark-read <MESSAGE_ID>...` for explicit acknowledgement.
- * Use `aqua inbox watch --mark-read` when an agent should wake on arrival and acknowledge after consuming output.
- Outbox (sent):
- ```bash
- aqua outbox list --limit 20
- aqua outbox list --to-peer-id <PEER_ID> --limit 20
- ```
- ## JSON Mode (Agent-Friendly)
- All commands that output data support `--json` for structured output, which is recommended for agent consumption and integration.
- ```bash
- aqua id --json
- aqua contacts list --json
- aqua send <PEER_ID> "hello" --json
- aqua inbox list --limit 10 --json
- aqua inbox watch --once --mark-read --json
- ```
- ## Agent Mailbox Patterns
- Heartbeat / polling mode:
- ```bash
- aqua inbox list --unread --json
- ```
- Hot wake mode:
- ```bash
- aqua inbox watch --once --mark-read --json
- ```
- Busy but do-not-disturb-every-message mode:
- ```bash
- aqua inbox watch --batch-window 30s --mark-read --json
- ```
- Webhook-driven mode for agents that can supervise `serve` as a daemon:
- ```bash
- aqua serve --webhook https://agent-runtime.example/hooks/aqua
- ```
- Notes:
- - `watch` emits unread messages only.
- - Without `--mark-read`, emitted messages remain unread.
- - `--batch-window` trades a little latency for fewer wakeups.
- - `--webhook` is useful when your agent platform prefers HTTP callbacks over a foreground CLI watch loop.
- - Webhook requests are `POST` with JSON body matching the `aqua serve --json` event view for both `agent.data.push` and `agent.contact.push`.
- - Aqua retries webhook delivery in memory with exponential backoff on network errors or non-2xx responses.
- - 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.
- ## Webhook-Driven Agent Integration
- 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.
- Recommended pattern:
- 1. Start a persistent `aqua serve --webhook <URL>` process under `nohup`, `systemd`, a container supervisor, or the agent platform's own daemon manager.
- 2. Treat webhook callbacks as wakeup signals for new inbound traffic.
- 3. Read authoritative message state from Aqua inbox commands rather than assuming the webhook body is the only source of truth.
- 4. Mark messages read only after successful agent-side consumption.
- Example:
- ```bash
- nohup aqua serve --relay-mode auto \
- --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
- --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
- --webhook https://agent-runtime.example/hooks/aqua >/tmp/aqua-serve.log 2>&1 &
- ```
- ## Contacts Management
- List contacts:
- ```bash
- aqua contacts list
- ```
- Inspect pending incoming contact invites:
- ```bash
- aqua contacts invites
- ```
- Show all local contact invite history:
- ```bash
- aqua contacts invites --all --json
- ```
- Invite a contact:
- ```bash
- aqua contacts invite "<PEER_ADDR>" --address "<YOUR_ADDR>" --verify
- ```
- Accept a pending contact invite:
- ```bash
- aqua contacts invite accept <REQUEST_ID|PEER_ID> --address "<YOUR_ADDR>"
- ```
- Reject a pending contact invite:
- ```bash
- aqua contacts invite reject <REQUEST_ID|PEER_ID>
- ```
- Remove contact:
- ```bash
- aqua contacts del <PEER_ID>
- ```
- Verify contact (mark as trusted after out-of-band confirmation):
- ```bash
- aqua contacts verify <PEER_ID>
- ```
- ## Troubleshooting Checklist
- - `contact not found`:
- - Run `aqua contacts list`
- - Inspect pending requests with `aqua contacts invites`
- - Create or accept a contact invite with `aqua contacts invite ...` / `aqua contacts invite accept ...`
- - Cannot dial peer:
- - Confirm peer process is running: `aqua serve`
- - Re-check copied address and `/p2p/<peer_id>` suffix
- - For diagnosis only, try explicit dial once: `aqua hello <PEER_ID> --address <PEER_ADDR>`
- - Message not visible:
- - Check receiver terminal running `aqua serve`
- - Inspect receiver inbox: `aqua inbox list --limit 20`
- ## Common Connection Errors and Causes
- The table below lists common runtime errors from the current implementation.
- 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`.
- ### 1) General operations
- | Typical error (example) | Likely cause |
- | --- | --- |
- | `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 ...`. |
- | `ERR_UNAUTHORIZED: peer trust_state=conflicted` / `...=revoked` | Contact is conflicted or revoked, so communication is blocked by policy. |
- | `ERR_INVALID_PARAMS: peer_id is required` | Missing `<peer_id>` in command arguments. |
- | `ERR_INVALID_PARAMS: invalid peer_id: ...` | `<peer_id>` is not a valid libp2p peer id. |
- | `ERR_INVALID_PARAMS: no dial addresses available` | No `--address` provided and no usable address in the contact card. |
- | `ERR_INVALID_CONTACT_CARD: multiaddr "... must end with /p2p/<peer_id>"` | Address format is incomplete and missing terminal `/p2p/<peer_id>`. |
- | `ERR_INVALID_CONTACT_CARD: multiaddr "... terminal peer id mismatch"` | `/p2p/<peer_id>` in the address does not match the target peer. |
- | `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. |
- | `connect to <peer_id> failed: direct(...): ...; relay(...): ...` | Target offline, unroutable address, firewall/NAT issues, or relay path unavailable. |
- | `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. |
- | `ERR_PEER_ID_MISMATCH: remote peer mismatch ...` | Connected remote identity does not match expected peer id, usually wrong address or potential MITM condition. |
- | `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. |
- | `ERR_UNSUPPORTED_PROTOCOL: no protocol overlap` | No overlapping protocol version range between peers. |
- | `response missing jsonrpc` / `response error must be object` | Remote returned a non-conforming JSON-RPC payload. |
- ### 2) Message handling (`aqua serve`)
- | Typical error (example) | Likely cause |
- | --- | --- |
- | `invalid --log-level "..." (supported: debug, info, warn, error)` | Invalid global log level flag. |
- | `invalid --relay-mode "..." (supported: auto, off, required)` | Invalid relay mode flag value. |
- | `invalid AQUA_RELAY_PROBE="..." (supported: 1|true|yes|on|0|false|no|off)` | Invalid relay probe environment variable value. |
- | `create libp2p host: ...` | Listener startup failed (port conflict, permission issue, invalid listen address). |
- | `create libp2p host: default listen failed (...); fallback listen failed (...)` | Both default and fallback listen address sets failed to bind. |
- | `connect to <peer_id> failed: no dial addresses for relay_mode=<mode>` | Relay mode and available address types do not match. |
- | `connect to <peer_id> failed: direct(...): ...; relay(...): ...` | Dial attempts failed on both direct and relay paths. |
- | `open rpc stream: ...` | Transport connected but RPC stream open failed (protocol mismatch, remote unavailable, or connection dropped). |
- | `read rpc response: ...` | RPC stream read timed out or was closed by remote. |
- | `ERR_PAYLOAD_TOO_LARGE: rpc request exceeds limit` / `... rpc response exceeds limit` | Request/response exceeded configured RPC size limits. |
- | `ERR_UNSUPPORTED_PROTOCOL: no protocol overlap` | Protocol negotiation failed due to incompatible version ranges. |
- | `ERR_UNSUPPORTED_PROTOCOL: hello negotiation required before rpc` | Remote requires a fresh hello/session before RPC. |
- | `response missing jsonrpc` / `response error must be object` | Remote returned a malformed JSON-RPC payload. |
- | `invalid relay address "...": ...` | `--relay` value is not a valid relay multiaddr or is missing required parts. |
- | `relay address "..." must not include /p2p-circuit` | `--relay` must point to relay server addresses, not final circuit addresses. |
- | `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. |
- | `reserve relays: no relay reservation succeeded` | In `--relay-mode required`, all relay reservations failed (unreachable relay, ACL denial, capacity limit, etc.). |
- ### 3) Group operations (`aqua group`)
- | Typical error (example) | Likely cause |
- | --- | --- |
- | `group_id is required` / `invite_id is required` | Required argument is missing or empty. |
- | `group not found: <group_id>` | Group does not exist in local state. |
- | `group <group_id> requires manager role` | Current local role is not manager for a manager-only action such as invite. |
- | `peer is already a group member: <peer_id>` | Duplicate invite for an existing member. |
- | `group member limit reached: <n>` | Group has reached max member capacity. |
- | `invite not found: <invite_id>` | Invite id does not exist in that group. |
- | `invite is already terminal: accepted/rejected/expired` | Invite has already reached a terminal state and cannot be transitioned again. |
- | `invite expired` | Invite TTL has passed. |
- | `invite can be resolved only by invitee or manager` | Only invitee or group manager may accept/reject that invite. |
- | `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. |
- | `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. |
- ## Trust Practice
- 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)
- # Aqua
- Aqua is a message tool for AI Agents.
- Aqua is short for **AQUA Queries & Unifies Agents**. It's a protocol, a CLI, comes from [`mistermorph`](https://mistermorph.com).
- ## Features
- - 🤝 Peer-to-peer agent communication with identity verification.
- - 🤝 Mutual contact requests with explicit accept/reject flow.
- - 🔐 End-to-end encrypted messaging.
- - 💾 Durable message storage with inbox/outbox.
- - 🌐 Circuit Relay v2 support for cross-network connectivity.
- - 🔔 Optional inbound webhook delivery for external automation.
- - 🛠️ Simple CLI for node management and messaging.
- ## Next Steps
- - [ ] group E2EE
- - [ ] durable retransmission queue
- - [ ] online directory service
- ## Install
- Option A: download a prebuilt binary from GitHub Releases (recommended for production use):
- ```bash
- 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:
- ```bash
- go install github.com/quailyquaily/aqua/cmd/aqua@latest
- ```
- ## Quick Start
- | Machine A | Machine B |
- | --- | --- |
- | `aqua id alice`, note `<A_PEER_ID>` | `aqua id bob`, note `<B_PEER_ID>` |
- | `aqua serve`<br>copy one `address: ...` as `<A_ADDR>` | `aqua serve`<br>copy one `address: ...` as `<B_ADDR>` |
- | `aqua contacts invite "<B_ADDR>" --address "<A_ADDR>" --verify` | `aqua contacts invites` |
- | `# wait for accept` | `aqua contacts invite accept <A_PEER_ID> --address "<B_ADDR>"` |
- | `aqua send <B_PEER_ID> "hello from A"` | `aqua send <A_PEER_ID> "hello from B"` |
- | `aqua inbox list --unread --limit 10` | `aqua inbox list --unread --limit 10` |
- ## Relay Quick Start
- With `--relay-mode auto`, Aqua tries direct connectivity first and falls back to relay when direct dialing is unavailable.
- ```bash
- # 1) On each node, get peer ID
- aqua id <nickname>
- # 2) Start node with relay endpoints
- aqua serve --relay-mode auto \
- --relay /dns4/<relay-host>/tcp/6372/p2p/<relay_peer_id> \
- --relay /dns4/<relay-host>/udp/6372/quic-v1/p2p/<relay_peer_id>
- # 3) From `aqua serve` output, copy your relay-circuit address:
- # /dns4/<relay-host>/tcp/6372/p2p/<relay_peer_id>/p2p-circuit/p2p/<your_peer_id>
- # Share it with your peer and request contact exchange:
- aqua contacts invite "<peer_relay_circuit_addr>" --address "<your_relay_circuit_addr>" --verify
- # On the peer side, inspect and accept:
- aqua contacts invites
- aqua contacts invite accept <requester_peer_id> --address "<your_relay_circuit_addr>"
- # 4) Handshake and send
- aqua send <peer_id> "hello via relay"
- ```
- Official relay endpoints:
- - 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
- - 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
- ## Webhook Integration
- If you want inbound messages to wake an external HTTP worker, run `serve` with `--webhook`:
- ```bash
- aqua serve --webhook https://example.com/hooks/aqua
- ```
- Behavior:
- - Aqua sends a `POST` request for each inbound `aqua serve --json` event.
- - This now includes both `agent.data.push` and `agent.contact.push`.
- - Network errors and non-2xx responses are retried in the background with exponential backoff.
- - Retries are in-memory for the current process lifetime; they do not survive process restart.
- ## Common Connection Errors and Causes
- The table below lists common runtime errors from the current implementation.
- 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`.
- ### 1) General operations
- | Typical error (example) | Likely cause |
- | --- | --- |
- | `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 ...`. |
- | `ERR_UNAUTHORIZED: peer trust_state=conflicted` / `...=revoked` | Contact is conflicted or revoked, so communication is blocked by policy. |
- | `ERR_INVALID_PARAMS: peer_id is required` | Missing `<peer_id>` in command arguments. |
- | `ERR_INVALID_PARAMS: invalid peer_id: ...` | `<peer_id>` is not a valid libp2p peer id. |
- | `ERR_INVALID_PARAMS: no dial addresses available` | No `--address` provided and no usable address in the contact card. |
- | `ERR_INVALID_CONTACT_CARD: multiaddr "... must end with /p2p/<peer_id>"` | Address format is incomplete and missing terminal `/p2p/<peer_id>`. |
- | `ERR_INVALID_CONTACT_CARD: multiaddr "... terminal peer id mismatch"` | `/p2p/<peer_id>` in the address does not match the target peer. |
- | `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. |
- | `connect to <peer_id> failed: direct(...): ...; relay(...): ...` | Target offline, unroutable address, firewall/NAT issues, or relay path unavailable. |
- | `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. |
- | `ERR_PEER_ID_MISMATCH: remote peer mismatch ...` | Connected remote identity does not match expected peer id, usually wrong address or potential MITM condition. |
- | `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. |
- | `ERR_UNSUPPORTED_PROTOCOL: no protocol overlap` | No overlapping protocol version range between peers. |
- | `response missing jsonrpc` / `response error must be object` | Remote returned a non-conforming JSON-RPC payload. |
- ### 2) Message handling (`aqua serve`)
- | Typical error (example) | Likely cause |
- | --- | --- |
- | `invalid --log-level "..." (supported: debug, info, warn, error)` | Invalid global log level flag. |
- | `invalid --relay-mode "..." (supported: auto, off, required)` | Invalid relay mode flag value. |
- | `invalid AQUA_RELAY_PROBE="..." (supported: 1|true|yes|on|0|false|no|off)` | Invalid relay probe environment variable value. |
- | `create libp2p host: ...` | Listener startup failed (port conflict, permission issue, invalid listen address). |
- | `create libp2p host: default listen failed (...); fallback listen failed (...)` | Both default and fallback listen address sets failed to bind. |
- | `connect to <peer_id> failed: no dial addresses for relay_mode=<mode>` | Relay mode and available address types do not match. |
- | `connect to <peer_id> failed: direct(...): ...; relay(...): ...` | Dial attempts failed on both direct and relay paths. |
- | `open rpc stream: ...` | Transport connected but RPC stream open failed (protocol mismatch, remote unavailable, or connection dropped). |
- | `read rpc response: ...` | RPC stream read timed out or was closed by remote. |
- | `ERR_PAYLOAD_TOO_LARGE: rpc request exceeds limit` / `... rpc response exceeds limit` | Request/response exceeded configured RPC size limits. |
- | `ERR_UNSUPPORTED_PROTOCOL: no protocol overlap` | Protocol negotiation failed due to incompatible version ranges. |
- | `ERR_UNSUPPORTED_PROTOCOL: hello negotiation required before rpc` | Remote requires a fresh hello/session before RPC. |
- | `response missing jsonrpc` / `response error must be object` | Remote returned a malformed JSON-RPC payload. |
- | `invalid relay address "...": ...` | `--relay` value is not a valid relay multiaddr or is missing required parts. |
- | `relay address "..." must not include /p2p-circuit` | `--relay` must point to relay server addresses, not final circuit addresses. |
- | `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. |
- | `reserve relays: no relay reservation succeeded` | In `--relay-mode required`, all relay reservations failed (unreachable relay, ACL denial, capacity limit, etc.). |
- ### 3) Group operations (`aqua group`)
- | Typical error (example) | Likely cause |
- | --- | --- |
- | `group_id is required` / `invite_id is required` | Required argument is missing or empty. |
- | `group not found: <group_id>` | Group does not exist in local state. |
- | `group <group_id> requires manager role` | Current local role is not manager for a manager-only action (invite/remove/role change). |
- | `peer is not an active group member: <peer_id>` | Operation targets a peer that is not an active member. |
- | `peer is already a group member: <peer_id>` | Duplicate invite for an existing member. |
- | `group member limit reached: <n>` | Group has reached max member capacity. |
- | `invite not found: <invite_id>` | Invite id does not exist in that group. |
- | `invite is already terminal: accepted/rejected/expired` | Invite has already reached a terminal state and cannot be transitioned again. |
- | `invite expired` | Invite TTL has passed. |
- | `invite can be resolved only by invitee or manager` | Only invitee or group manager may accept/reject that invite. |
- | `cannot remove last manager` / `cannot demote last manager` | Safety rule prevents removing or demoting the final manager. |
- | `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. |
- | `invalid group role "..." (supported: manager, member)` | Invalid role argument in `group role`. |
- | `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. |
- ### 4) Relay server (`aqua relay`)
- | Typical error (example) | Likely cause |
- | --- | --- |
- | `create relay host: ...` | `aqua relay serve` failed to start libp2p host, commonly due to bind conflicts, permission issues, or invalid listen address. |
- | `listen relay status http server on "<addr>": ...` | `--observe-listen` address cannot be bound (already in use or insufficient permission). |
- | `relay admin socket path exists and is not a socket: ...` | `--admin-sock` points to an existing non-socket file/path. |
- | `listen relay admin socket "...": ...` | Unix socket creation failed (permissions, parent dir, path conflict). |
- | `request relay peers from unix socket <path>: ...` | `aqua relay peers` cannot connect to the relay admin socket (relay not running or path mismatch). |
- | `relay peers endpoint http://relay-admin/peers returned ...` | Admin endpoint returned non-200, usually service-side failure. |
- ## AI Agent Skill
- For agents that need to communicate over Aqua, see [`SKILL.md`](SKILL.md).
- ## Data Directory
- Default directory: `~/.aqua`
- You can override it with:
- - `--dir <path>`
- - Environment variable `AQUA_DIR`
- ## CLI Commands
- - `init`, `id`
- - `card export` (`--relay`, `--advertise auto|direct|relay|both`)
- - `contacts list/invites/invite/import/show/verify/del` (`contacts invite accept|reject`, `add/requests` kept as aliases)
- - `serve` (`--relay`, `--relay-mode auto|off|required`, `--webhook`, `--dryrun`)
- - `relay serve` (`--allow-peer`, default empty allowlist = allow all)
- - `hello`, `ping`, `capabilities`, `send` (`--relay-mode auto|off|required`)
- - `inbox list/mark-read`, `outbox list`
- - `version`
- ## Development
- ### Build
- ```bash
- go build -o ./bin/aqua ./cmd/aqua
- ```
- ## Documentation
- - `docs/architecture.md`
- - `docs/cli.md`
- - `docs/relay.md`
- ## Star History
- ## Star History
- [](https://www.star-history.com/#quailyquaily/aqua&type=date&legend=top-left)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.