toq protocol

Send and receive secure messages to other AI agents using the toq protocol. Use when the user wants to set up agent-to-agent communication, send or receive t...

Security Scan

The skill's instructions broadly match an agent-to-agent messaging tool, but the runtime guidance asks you to run an unverified install script, exposes your public IP to an external service, and encourages installing handlers that execute arbitrary commands based on incoming messages — all of which warrant caution before installing.

Purpose & Capability

Name and description (agent-to-agent secure messaging) align with the content: the SKILL.md documents installing a 'toq' daemon, opening port 9009, configuring DNS discovery, and registering handlers. Installing a binary and managing network/daemon settings is coherent with the stated purpose.

Instruction Scope

The instructions include high-impact runtime steps: (1) curl https://toq.dev/install.sh | sh (runs remote script), (2) using an external service (ifconfig.me) to detect your public IP (leaks an indicator about your host to that service), (3) guidance to create handlers that run arbitrary shell/python/node binaries which will be executed by the daemon when messages arrive. While handler execution is an expected feature of such a system, the SKILL.md gives examples that could easily let untrusted remote messages trigger code execution or exfiltrate files if connection/handler rules are misconfigured. The skill documents these risks but still directs the user to patterns that require careful sandboxing and approval controls.

Install Mechanism

There is no registry install spec; the runtime instructions recommend piping a shell script from https://toq.dev/install.sh into sh — a high-risk install pattern because it executes remote code without verification. Homebrew is listed as an alternative (lower risk) but the primary curl | sh option is present and notable. The domain toq.dev is not validated in the metadata, and the installer may write binaries and daemon units to the system.

Credentials

The skill itself does not request environment variables or credentials, which is proportionate. However, handlers are explicitly allowed to call external model APIs (OpenAI, Ollama, etc.) and the recommended LLM handler pattern invokes 'openclaw agent --local' — meaning handlers may access whatever credentials or provider config your agent has. Handlers and daemon logs also read/write files in your home directory; these are powerful capabilities that are reasonable for a messaging daemon but require user-managed privilege restrictions.

Persistence & Privilege

The skill suggests creating systemd/launchd service units to auto-start the daemon on boot. That's expected for persistent daemons and 'always' is not set in metadata. Still, creating a system service requires elevated privileges and grants the toq daemon persistent system presence, so users should review the binary and service file before enabling.

What to consider before installing

This skill is coherent with an agent-to-agent messaging tool but contains several risky recommendations you should treat cautiously: - Do NOT run curl https://toq.dev/install.sh | sh unless you have inspected that script and trust the toq.dev domain. Prefer a vetted package (Homebrew) or inspect the installer contents locally before executing. - The setup step uses ifconfig.me to learn your public IP — that makes an external service aware of your host. If you care about privacy, get your IP from a trusted source or from your cloud provider's console. - Handlers run arbitrary executables and will be invoked when remote agents send messages. Only register handlers you have reviewed and test them in an isolated environment (container or VM). Treat incoming messages as untrusted input. - Use approval or allowlist connection modes and keep exec approval enabled for OpenClaw so remote content cannot silently execute commands. Avoid 'open' mode unless you explicitly want public access. - If you plan to enable auto-start (systemd/launchd), inspect the service file and run the daemon with a least-privilege user account. Consider running in a container or dedicated VM. - Before installing, ask for the install script contents or an official binary checksum/signature. If you cannot verify the installer, decline or prefer manual installation from a trustworthy package source. If you want, I can: (a) fetch and show the contents of the recommended install script (if you provide it), (b) suggest a sandboxed container-based install workflow, or (c) produce a checklist of safe handler patterns and firewall rules to minimize exposure.

toq is a secure agent-to-agent communication protocol. Each agent is an endpoint identified by a toq address like toq://hostname/agent-name on port 9009.

Setup

Guide the user conversationally. Do not dump all steps at once.

Before anything else: "toq is in alpha. Great for experimenting with agent-to-agent communication, but avoid sending personal or sensitive data through it for now."

Step 1: Install toq

Check if installed:

which toq > /dev/null 2>&1 && toq --version

If not found, install:

curl -sSf https://toq.dev/install.sh | sh && export PATH="$HOME/.toq/bin:$PATH"

Or with Homebrew:

brew install toqprotocol/toq/toq

If toq is installed but not in PATH:

export PATH="$HOME/.toq/bin:$PATH"

Step 2: Configure

Ask for agent name (lowercase, hyphens allowed). Detect host IP:

PUBLIC_IP=$(curl -4 -s ifconfig.me) && LOCAL_IP=$(hostname -I 2>/dev/null | awk '{print $1}' || ipconfig getifaddr en0 2>/dev/null) && echo "Public: $PUBLIC_IP Local: $LOCAL_IP"

Run setup:

toq setup --non-interactive --agent-name=<name> --connection-mode=approval --adapter=http --host=<ip>

Step 3: Start

toq up && toq doctor

Step 4: Security check

Present the walkthrough from references/security.md. Do not skip.

Step 5: What's next

Show status with toq status and present options:

• "Send a test message"
• "Set up a message handler"
• "Configure my allowlist"
• "Set up DNS"

Sending messages

The agent name in the address is validated during connection. Sending to toq://host/wrong-name will fail with a clear error if no agent with that name exists on that endpoint.

toq send toq://hostname/agent-name "message text"
toq send toq://hostname/agent-name "reply" --thread-id <id>
toq send toq://hostname/agent-name "goodbye" --thread-id <id> --close-thread

For agents on non-default ports, include the port in the address:

toq send toq://hostname:9010/agent-name "message text"

Approvals and permissions

Approval is bidirectional. Both sides must approve each other before messages flow. When alice sends to charlie, charlie must approve alice. When charlie replies, alice must approve charlie.

"When a new agent tries to talk to you, they go into a waiting list. You decide who gets in."

toq approvals                              # list pending
toq approve <key>                          # approve by key
toq approve --from "toq://host/*"          # approve by pattern
toq deny <key>                             # deny
toq block --from "toq://host/agent"        # block
toq unblock --from "toq://host/agent"      # unblock
toq permissions                            # list all rules

Wildcards: toq://* (all), toq://host/* (all on host), toq://*/name (name on any host).

Message handlers

Handlers auto-process incoming messages. See references/handlers.md for shell patterns and references/conversational.md for LLM handlers.

Save handler scripts to ~/handlers/. Consider testing scripts manually before registering:

mkdir -p ~/handlers
# Test with mock env vars:
TOQ_FROM="toq://test/agent" TOQ_TEXT="test message" TOQ_THREAD_ID="test-123" python3 ~/handlers/my-handler.py

After registering, check handler logs with toq handler logs <name> to verify behavior.

When the user wants custom behavior for incoming messages (auto-replies, forwarding, logging, task processing, notifications), suggest setting up a handler. Handlers are the primary way to automate responses and build agent workflows.

After creating handlers or any automated setup, always give the user a brief breakdown: what was created, where files live, and how it works. Keep it concise.

When multiple agents need to exchange structured messages (acks, status updates, task results), agree on a message format convention upfront. Agents set up independently may use different formats, causing parsing mismatches.

Register a shell handler:

toq handler add <name> --command "bash ~/handlers/my-handler.sh" [--from "toq://*/alice"]

Handlers can run any executable: bash, python, node, or any binary. The command is passed to sh -c, so pipes and redirects work.

toq handler add <name> --command "python3 ~/handlers/handler.py"
toq handler add <name> --command "node ~/handlers/handler.js"

Register an LLM handler:

toq handler add <name> --provider <provider> --model <model> --prompt "..." [--auto-close]

Manage handlers:

toq handler list
toq handler enable|disable <name>
toq handler remove <name>
toq handler logs <name>

Handler environment variables (set by the daemon, use these exact names):

• TOQ_FROM - sender address
• TOQ_TEXT - message text
• TOQ_THREAD_ID - thread ID for replies
• TOQ_ID - message ID
• TOQ_TYPE - message type
• TOQ_HANDLER - handler name
• TOQ_URL - daemon API URL

Full message JSON is also piped to stdin.

When a handler needs LLM reasoning, default to openclaw agent --local --message "..." which uses the configured model provider. Users can also call any model API directly if they prefer (e.g., curl to OpenAI, Ollama, or any other provider).

When forwarding messages between agents in a pipeline, embed the original sender address and thread ID in the message body so downstream agents can route responses back to the originator.

Multiple agents on one machine

Run multiple agents by using separate workspaces and ports:

# First agent (default workspace, port 9009)
toq setup --non-interactive --agent-name=alice --connection-mode=approval --host=<ip>
toq up

# Second agent (custom workspace, port 9010)
toq setup --non-interactive --agent-name=bob --connection-mode=approval --host=<ip> --config-dir ~/.toq-bob
toq config set port 9010 --config-dir ~/.toq-bob
toq up --config-dir ~/.toq-bob

All commands for the second agent need --config-dir ~/.toq-bob. The address includes the port: toq://hostname:9010/bob.

Common tasks

See references/commands.md for the full CLI reference.

• "What's my toq address?" -> toq whoami
• "Is toq running?" -> toq status
• "Run diagnostics" -> toq doctor
• "Show peers" -> toq peers
• "Check received messages" -> toq messages
• "Discover agents at a domain" -> toq discover <domain>
• "Change connection mode" -> toq config set connection_mode <mode> then toq down && toq up
• "Shut down toq" -> toq down

Emergency shutdown

toq down

If that fails:

pkill -f "toq up" && rm -f ~/.toq/toq.pid

Key management

Export and import require a TTY. Tell the user to run these manually:

• Export: toq export <path>
• Import: toq import <path>
• Rotate keys: toq rotate-keys