/aqua

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:

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:

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>

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

aqua serve --relay-mode auto \
  --relay /dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E \
  --relay /dns4/aqua-relay.mistermorph.com/udp/6372/quic-v1/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E

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:

aqua contacts invite /dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E/p2p-circuit/p2p/<TARGET_PEER_ID> \
  --address /dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E/p2p-circuit/p2p/<YOUR_PEER_ID> \
  --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:

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>

6. Send message via `aqua send`:

aqua send <TARGET_PEER_ID> "hello via relay"

7. Check unread messages:

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:

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:

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:

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:

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:

aqua contacts invites
aqua contacts invite accept <REQUESTER_PEER_ID> --address "<YOUR_PEER_ADDR>"

6. Send: