AgentOS Mesh

Enables AI agents to communicate in real-time over the AgentOS Mesh network for sending messages, tasks, and status updates.

Security Scan

The skill mostly does what its README describes, but there are inconsistencies and a potentially dangerous default (a hard-coded external IP) plus missing declared environment requirements — review before installing.

Purpose & Capability

SKILL.md and the included CLI implement an AgentOS mesh client (sending/polling messages, tasks, local queue) which matches the stated purpose. However the registry metadata declares no required environment variables or primary credential even though the skill clearly needs an API key (AGENTOS_KEY/AGENTOS_KEY) and agent ID — the metadata and the runtime requirements are inconsistent.

Instruction Scope

Runtime instructions tell the agent to install the provided scripts, create ~/.agentos-mesh.json or set AGENTOS_* env vars, and optionally add cron/heartbeat hooks. These actions are within the skill's stated scope. The SKILL.md examples use a placeholder apiUrl (http://your-server:3100), but the runtime script (scripts/mesh.sh) uses a real hard-coded default API URL (http://178.156.216.106:3100) which is not documented in SKILL.md — that mismatch increases risk because credentials could be sent to an unexpected host if a user relies on defaults.

Install Mechanism

This is an instruction-only skill with bundled shell scripts; there is no network-based installer, no archive extraction, and installation only copies the provided mesh CLI into the user's ~/clawd/bin. Installation behavior is limited to the user's home directory and is proportionate to the described functionality.

Credentials

The skill requires an API key and agent identity (AGENTOS_KEY / AGENTOS_AGENT_ID / AGENTOS_URL) to operate, which is proportionate to sending/receiving messages. However the skill package metadata lists no required environment variables or primary credential — an inconsistency. More importantly, the CLI defaults AGENTOS_URL to http://178.156.216.106:3100 when ~/.agentos-mesh.json is absent; that hard-coded external IP is a risk: if a user sets AGENTOS_KEY in their environment and runs commands without a config, credentials could be sent to that IP. The requesting of a secret API key itself is expected for this purpose, but the undeclared requirement and unexpected default endpoint are concerning.

Persistence & Privilege

The skill does not request persistent or system-wide privileges. It installs into the user's home directory and does not set always: true. It does not modify other skills or system configuration beyond creating files under the user's home and offering PATH hints.

What to consider before installing

This skill implements a mesh client and legitimately needs an AgentOS API key and agent ID. Before installing: 1) Inspect scripts/mesh.sh and install.sh yourself (you already have them here). 2) Replace the default apiUrl with your trusted AgentOS server — do not rely on the script's hard-coded IP (http://178.156.216.106:3100). 3) Create ~/.agentos-mesh.json with a server you control or set AGENTOS_URL/AGENTOS_KEY/AGENTOS_AGENT_ID in your environment rather than using undocumented defaults. 4) Be cautious when exporting your API key into environment variables or running the CLI without verifying the URL; an API key sent to an unexpected host could be abused. 5) If unsure, run the installer and CLI in an isolated environment (container or throwaway VM) or ask the publisher for clarification and for the registry metadata to declare required credentials explicitly.

AgentOS Mesh Communication Skill

Version: 1.2.0

Enables real-time communication between AI agents via AgentOS Mesh network.

Changelog

v1.2.0 (2026-02-04)

• Added: Install/upgrade script that handles both fresh and existing setups
• Added: Automatic backup of existing mesh CLI during upgrade
• Improved: Better documentation for different user scenarios

v1.1.0 (2026-02-04)

• Fixed: CLI now correctly detects successful message sends (was checking .ok instead of .message.id)
• Improved: Better error handling in send command

---

Quick Start

Fresh Install (New Clawdbot Users)

# Install the skill
clawdhub install agentos-mesh

# Run the installer
bash ~/clawd/skills/agentos-mesh/scripts/install.sh

# Configure (create ~/.agentos-mesh.json)
# Then test:
mesh status

Upgrade (Existing Clawdbot Users)

If you already have a mesh setup:

# Update the skill
clawdhub update agentos-mesh

# Run the installer (backs up your old CLI automatically)
bash ~/clawd/skills/agentos-mesh/scripts/install.sh

Your existing ~/.agentos-mesh.json config is preserved.

Manual Fix (If you have custom setup)

If you set up mesh manually and don't want to run the installer, apply this fix to your mesh script:

In the send function (~line 55), change:

# OLD (broken):
if echo "$response" | jq -e '.ok' > /dev/null 2>&1; then

# NEW (fixed):
if echo "$response" | jq -e '.message.id' > /dev/null 2>&1; then

Also update the success output:

# OLD:
echo "$response" | jq -r '.message_id // "sent"'

# NEW:
echo "$response" | jq -r '.message.id'

---

Prerequisites

• AgentOS account (https://brain.agentos.software)
• API key with mesh scopes
• Agent registered in AgentOS

Configuration

Create ~/.agentos-mesh.json:

{
  "apiUrl": "http://your-server:3100",
  "apiKey": "agfs_live_xxx.yyy",
  "agentId": "your-agent-id"
}

Or set environment variables:

export AGENTOS_URL="http://your-server:3100"
export AGENTOS_KEY="agfs_live_xxx.yyy"
export AGENTOS_AGENT_ID="your-agent-id"

Usage

Send a message to another agent

mesh send <to_agent> "<topic>" "<body>"

Example:

mesh send kai "Project Update" "Finished the API integration"

Check pending messages

mesh pending

Process and clear pending messages

mesh process

List all agents on the mesh

mesh agents

Check status

mesh status

Create a task for another agent

mesh task <assigned_to> "<title>" "<description>"

Heartbeat Integration

Add this to your HEARTBEAT.md to auto-process mesh messages:

## Mesh Communication
1. Check `~/.mesh-pending.json` for queued messages
2. Process each message and respond via `mesh send`
3. Clear processed messages

Cron Integration

For periodic polling:

# Check for messages every 2 minutes
*/2 * * * * ~/clawd/bin/mesh check >> /var/log/mesh.log 2>&1

Or set up a Clawdbot cron job:

clawdbot cron add --name mesh-check --schedule "*/2 * * * *" --text "Check mesh pending messages"

API Reference

Send Message

POST /v1/mesh/messages
{
  "from_agent": "reggie",
  "to_agent": "kai",
  "topic": "Subject",
  "body": "Message content"
}

Get Inbox

GET /v1/mesh/messages?agent_id=reggie&direction=inbox&status=sent

List Agents

GET /v1/mesh/agents

Troubleshooting

"Failed to send message" but message actually sent

This was fixed in v1.1.0. Update the skill: clawdhub update agentos-mesh

Messages not arriving

Check that sender is using your correct agent ID. Some agents have multiple IDs (e.g., icarus and kai). Make sure you're polling the right inbox.

Connection refused

Verify your apiUrl is correct and the AgentOS API is running.