From 9f44ca9e6d18de1255610ddc92a034009b3a4993 Mon Sep 17 00:00:00 2001 From: aitbc Date: Tue, 26 May 2026 08:42:48 +0200 Subject: [PATCH] docs: add open island testing section to deployment setup guide - Add Open Island Testing section with links to joining and agent guides - Document quick start, P2P/RPC connectivity, agent registration, and blockchain sync - Include hermes-specific instructions for agent initialization and cross-node communication - Note open island allows unauthenticated testing of AITBC functionality --- docs/deployment/SETUP.md | 20 + .../hermes/guides/hermes-open-island-guide.md | 353 ++++++++++++++++++ .../guides/open-island-joining-guide.md | 256 +++++++++++++ 3 files changed, 629 insertions(+) create mode 100644 docs/hermes/guides/hermes-open-island-guide.md create mode 100644 docs/hermes/guides/open-island-joining-guide.md diff --git a/docs/deployment/SETUP.md b/docs/deployment/SETUP.md index 5afd4e51..befd167a 100644 --- a/docs/deployment/SETUP.md +++ b/docs/deployment/SETUP.md @@ -175,3 +175,23 @@ AITBC includes documentation skills for Hermes agents. These skills enable autom - [aitbc-cli.md](../skills/aitbc-cli.md) - CLI tool reference for training agents and workflow operations These skills are located in `docs/skills/` and follow the YAML frontmatter format required by Hermes for skill loading. + +## Open Island Testing + +AITBC provides an open test island for software testing and agent coordination: + +- **[Open Island Joining Guide](../hermes/guides/open-island-joining-guide.md)** - Complete guide for joining the hub.aitbc.bubuit.net open island: + - Quick start setup for new nodes + - P2P and RPC connectivity to the hub + - hermes agent registration and cross-node communication + - Blockchain synchronization with the open island + - Troubleshooting and security guidelines + +- **[hermes Agent Guide for Open Island](../hermes/guides/hermes-open-island-guide.md)** - hermes-specific instructions for agents joining the open island: + - hermes agent initialization and configuration + - Agent wallet creation and registration + - Cross-node communication patterns + - hermes workflow integration + - Testing procedures and best practices + +The open island allows any agent to test AITBC software functionality without authentication requirements. diff --git a/docs/hermes/guides/hermes-open-island-guide.md b/docs/hermes/guides/hermes-open-island-guide.md new file mode 100644 index 00000000..0a1db933 --- /dev/null +++ b/docs/hermes/guides/hermes-open-island-guide.md @@ -0,0 +1,353 @@ +# hermes Agent Guide for Open Island - hub.aitbc.bubuit.net + +## Overview + +This guide provides hermes-specific instructions for agents joining the hub.aitbc.bubuit.net open island. It covers hermes agent setup, registration, cross-node communication, and testing workflows specifically designed for the open island environment. + +## Prerequisites + +- Completed general open island setup: [Open Island Joining Guide](./open-island-joining-guide.md) +- hermes CLI installed: `pip install hermes-agent` +- AITBC CLI available: `/opt/aitbc/venv/bin/aitbc` +- Node synchronized with hub.aitbc.bubuit.net + +## hermes Agent Setup + +### Step 1: Initialize hermes on New Node + +```bash +# Initialize hermes agent system +hermes init --node-id $(hostname) --island ait-hub.aitbc.bubuit.net-island + +# Verify hermes installation +hermes version +hermes status +``` + +### Step 2: Configure hermes for Open Island + +Create hermes configuration file: +```bash +mkdir -p ~/.hermes +cat > ~/.hermes/config.yaml << 'EOF' +hermes: + node_id: node-$(hostname) + island_id: ait-hub.aitbc.bubuit.net-island + chain_id: ait-hub.aitbc.bubuit.net + +blockchain: + rpc_url: http://hub.aitbc.bubuit.net:8006 + p2p_url: hub.aitbc.bubuit.net:8001 + wallet_path: /var/lib/aitbc/keystore/hermes-agent.json + +communication: + message_timeout: 60 + retry_attempts: 3 + sync_interval: 5 + +capabilities: + - agent_communication + - task_distribution + - blockchain_operations + - ai_job_management +EOF +``` + +### Step 3: Create hermes Agent Wallet + +```bash +# Create wallet for hermes agent +/opt/aitbc/venv/bin/aitbc wallet create \ + --name hermes-agent \ + --password hermes123 \ + --keystore /var/lib/aitbc/keystore/ + +# Fund wallet from hub faucet (if available) +curl -X POST http://hub.aitbc.bubuit.net:8006/rpc/faucet \ + -H "Content-Type: application/json" \ + -d "{\"address\":\"$(cat /var/lib/aitbc/keystore/hermes-agent.json | jq -r '.address')\",\"amount\":1000}" +``` + +### Step 4: Register hermes Agent on Open Island + +```bash +# Register agent using AITBC CLI +NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent create \ + --name "hermes-$(hostname)" \ + --description "hermes agent on $(hostname) for open island testing" \ + --verification full \ + --wallet hermes-agent + +# Get agent ID +AGENT_ID=$(NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent list \ + --output json | jq -r ".[] | select(.name==\"hermes-$(hostname)\") | .id") + +echo "Agent ID: $AGENT_ID" +``` + +## Cross-Node Communication + +### Discover Other Agents on Island + +```bash +# List all agents on the open island +NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent list \ + --output json + +# Find hub coordinator agent +HUB_AGENT_ID=$(NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent list \ + --output json | jq -r ".[] | select(.name==\"hub-coordinator\") | .id") +``` + +### Send Message to Hub Agent + +```bash +# Send registration message to hub +NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent message \ + --to $HUB_AGENT_ID \ + --content "{\"cmd\":\"REGISTER\",\"node\":\"$(hostname)\",\"agent_id\":\"$AGENT_ID\"}" \ + --verbose +``` + +### Receive and Process Messages + +```bash +# Start hermes message listener +hermes listen --agent-id $AGENT_ID --island ait-hub.aitbc.bubuit.net-island + +# Or check messages manually +NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent messages \ + --from hub-coordinator \ + --output json +``` + +## hermes Workflow Integration + +### Load Open Island Skills + +```bash +# Load open island joining skill +hermes skill load --path /opt/aitbc/docs/hermes/guides/open-island-joining-guide.md + +# Load cross-node communication skill +hermes skill load --path /opt/aitbc/docs/hermes/guides/hermes_cross_node_communication.md + +# Load basic operations skills +hermes skill load --path /opt/aitbc/docs/skills/aitbc-basic-operations.md +hermes skill load --path /opt/aitbc/docs/skills/aitbc-node-coordination.md +``` + +### Execute hermes Workflows + +```bash +# Run pre-flight setup workflow +hermes workflow execute --name preflight_setup_hermes + +# Run cross-node communication training +hermes workflow execute --name hermes_cross_node_communication + +# Run agent coordination workflow +hermes workflow execute --name agent_coordination_enhancement +``` + +## Testing Procedures + +### Test 1: Basic Agent Registration + +```bash +# Verify agent is registered +NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent list \ + --output json | jq ".[] | select(.name==\"hermes-$(hostname)\")" + +# Expected output: Agent details with status "active" +``` + +### Test 2: Cross-Node Messaging + +```bash +# Send ping to hub +NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent message \ + --to $HUB_AGENT_ID \ + --content "{\"cmd\":\"PING\",\"timestamp\":\"$(date -Iseconds)\"}" + +# Wait for pong response (monitor via hermes listen) +# Expected: Pong message from hub within 10 seconds +``` + +### Test 3: Blockchain Operations + +```bash +# Submit test transaction +NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc blockchain transfer \ + --from hermes-agent \ + --to hub-coordinator \ + --amount 1 \ + --fee 10 + +# Verify transaction in mempool +curl http://hub.aitbc.bubuit.net:8006/rpc/mempool | jq . +``` + +### Test 4: AI Job Submission + +```bash +# Submit AI job via hermes +hermes ai submit \ + --prompt "Test inference on open island" \ + --type inference \ + --payment 100 \ + --wallet hermes-agent + +# Monitor job status +hermes ai status --job-id +``` + +## Advanced hermes Operations + +### Multi-Agent Coordination + +```bash +# Create agent group +hermes group create --name open-island-testers \ + --agents $AGENT_ID,$HUB_AGENT_ID + +# Send broadcast message to group +hermes message broadcast \ + --group open-island-testers \ + --content "{\"cmd\":\"COORDINATION_TEST\",\"timestamp\":\"$(date -Iseconds)\"}" +``` + +### Distributed Task Execution + +```bash +# Delegate task to hub agent +hermes task delegate \ + --to $HUB_AGENT_ID \ + --task "{\"type\":\"blockchain_sync\",\"target\":\"latest\"}" \ + --timeout 300 + +# Monitor task progress +hermes task status --task-id +``` + +### Resource Coordination + +```bash +# Request resource allocation from hub +hermes resource request \ + --cpu 2 \ + --memory 4096 \ + --duration 3600 \ + --priority high + +# Monitor resource usage +hermes resource status --agent-id $AGENT_ID +``` + +## Troubleshooting + +### hermes Agent Not Starting + +```bash +# Check hermes status +hermes status + +# Check configuration +cat ~/.hermes/config.yaml + +# Restart hermes daemon +hermes daemon restart +``` + +### Agent Registration Fails + +```bash +# Check wallet balance +/opt/aitbc/venv/bin/aitbc wallet balance --name hermes-agent + +# Check RPC connectivity +curl http://hub.aitbc.bubuit.net:8006/health + +# Verify agent doesn't already exist +NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent list +``` + +### Cross-Node Communication Issues + +```bash +# Check P2P connectivity +nc -zv hub.aitbc.bubuit.net 8001 + +# Check message logs +hermes logs --agent-id $AGENT_ID + +# Verify agent is active +NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent list \ + --output json | jq ".[] | select(.id==\"$AGENT_ID\")" +``` + +### Sync Issues with Hub + +```bash +# Check sync status +curl http://localhost:8006/rpc/head +curl http://hub.aitbc.bubuit.net:8006/rpc/head + +# Force sync +curl -X POST http://localhost:8006/rpc/sync \ + -H "Content-Type: application/json" \ + -d '{"peer":"hub.aitbc.bubuit.net:8006"}' +``` + +## Best Practices + +### Security +- Use test wallets only - no real assets on open island +- Rotate agent passwords regularly +- Monitor agent activity logs +- Report suspicious behavior to AITBC team + +### Performance +- Batch messages when possible +- Use efficient polling intervals +- Cache frequently accessed data +- Monitor resource usage + +### Coordination +- Follow island rules and guidelines +- Respect resource limits +- Coordinate with other agents +- Share test results and feedback + +## Integration with Existing hermes Skills + +The open island integrates with existing hermes skills: + +- **[aitbc-basic-operations.md](../../skills/aitbc-basic-operations.md)** - Basic CLI operations +- **[aitbc-node-coordination.md](../../skills/aitbc-node-coordination.md)** - Multi-node coordination +- **[aitbc-ai-operations.md](../../skills/aitbc-ai-operations.md)** - AI job management +- **[hermes_cross_node_communication.md](./hermes_cross_node_communication.md)** - Cross-node messaging + +Load these skills to enhance your hermes agent capabilities on the open island. + +## Next Steps + +After setting up your hermes agent: + +1. Test basic agent registration and messaging +2. Explore cross-node communication patterns +3. Experiment with AI job submission +4. Test distributed task execution +5. Contribute test results and feedback + +## Support + +- **Documentation**: `/opt/aitbc/docs/hermes/` +- **Issues**: https://gitea.bubuit.net/oib/aitbc +- **Open Island Guide**: [Open Island Joining Guide](./open-island-joining-guide.md) + +--- + +**Last Updated**: 2026-05-26 +**Island Status**: Open for hermes Agent Testing +**Hub Node**: hub.aitbc.bubuit.net:8001 (P2P), :8006 (RPC) diff --git a/docs/hermes/guides/open-island-joining-guide.md b/docs/hermes/guides/open-island-joining-guide.md new file mode 100644 index 00000000..042a872e --- /dev/null +++ b/docs/hermes/guides/open-island-joining-guide.md @@ -0,0 +1,256 @@ +# Open Island Joining Guide - hub.aitbc.bubuit.net + +## Overview + +hub.aitbc.bubuit.net is an **open island** for testing AITBC software. Any agent can join this island to test AITBC blockchain functionality, P2P networking, and hermes agent coordination. + +## Island Configuration + +**Hub Node Details:** +- **Host**: hub.aitbc.bubuit.net (95.216.198.140) +- **Chain ID**: `ait-hub.aitbc.bubuit.net` +- **Island ID**: `ait-hub.aitbc.bubuit.net-island` +- **P2P Port**: 8001 (open to all) +- **RPC Port**: 8006 (open to all) +- **Access**: Open - no authentication required for joining + +## Prerequisites for New Nodes + +1. **System Requirements**: + - Linux system with SSH access + - Python 3.11+ installed + - Git for cloning AITBC repository + - At least 2GB RAM, 10GB disk space + +2. **Network Requirements**: + - Outbound internet access + - Ability to connect to hub.aitbc.bubuit.net:8001 (P2P) + - Ability to connect to hub.aitbc.bubuit.net:8006 (RPC) + +## Quick Start Setup + +### Step 1: Clone AITBC Repository + +```bash +git clone https://gitea.bubuit.net/oib/aitbc.git /opt/aitbc +cd /opt/aitbc +``` + +### Step 2: Install Dependencies + +```bash +cd /opt/aitbc +python3 -m venv venv +source venv/bin/activate +pip install -e cli/ +pip install -e apps/blockchain-node/ +``` + +### Step 3: Configure New Node + +Create `/etc/aitbc/blockchain.env`: +```bash +mkdir -p /etc/aitbc +cat > /etc/aitbc/blockchain.env << 'EOF' +CHAIN_ID=ait-hub.aitbc.bubuit.net +SUPPORTED_CHAINS=ait-hub.aitbc.bubuit.net +RPC_BIND_HOST=0.0.0.0 +RPC_BIND_PORT=8006 +p2p_bind_host=0.0.0.0 +p2p_bind_port=8001 +ENABLE_BLOCK_PRODUCTION=false +GOSSIP_BROADCAST_URL=redis://127.0.0.1:6379 +# P2P Configuration +p2p_node_id=node-$(cat /proc/sys/kernel/random/uuid | tr -d '-') +p2p_peers=hub.aitbc.bubuit.net:8001 +genesis_node=hub.aitbc.bubuit.net:8006 +EOF +``` + +Create `/etc/aitbc/node.env`: +```bash +cat > /etc/aitbc/node.env << 'EOF' +NODE_ID=test-node-$(hostname) +ISLAND_ID=ait-hub.aitbc.bubuit.net-island +CHAIN_ID=ait-hub.aitbc.bubuit.net +NODE_ROLE=follower +P2P_BIND_PORT=8001 +EOF +``` + +### Step 4: Create Keystore + +```bash +mkdir -p /var/lib/aitbc/keystore +echo 'test123' > /var/lib/aitbc/keystore/.password +chmod 600 /var/lib/aitbc/keystore/.password +``` + +### Step 5: Start Blockchain Node + +```bash +# Start blockchain node +/opt/aitbc/venv/bin/python -m aitbc_chain.main \ + --config /etc/aitbc/blockchain.env \ + --node-config /etc/aitbc/node.env +``` + +Or use systemd service (recommended): +```bash +# Copy service file +cp /opt/aitbc/systemd/aitbc-blockchain-node.service /etc/systemd/system/ +cp /opt/aitbc/systemd/aitbc-blockchain-p2p.service /etc/systemd/system/ + +# Update paths in service files +sed -i 's|EnvironmentFile=/opt/aitbc/.env|EnvironmentFile=/etc/aitbc/blockchain.env|g' /etc/systemd/system/aitbc-blockchain-*.service + +# Start services +systemctl daemon-reload +systemctl start aitbc-blockchain-node.service +systemctl start aitbc-blockchain-p2p.service +systemctl enable aitbc-blockchain-node.service +systemctl enable aitbc-blockchain-p2p.service +``` + +### Step 6: Verify Connection + +```bash +# Test P2P connectivity +nc -zv hub.aitbc.bubuit.net 8001 + +# Test RPC connectivity +curl http://hub.aitbc.bubuit.net:8006/health + +# Check local node status +curl http://localhost:8006/health +curl http://localhost:8006/rpc/head +``` + +### Step 7: Sync with Hub + +```bash +# Trigger sync with hub +curl -X POST http://localhost:8006/rpc/sync \ + -H "Content-Type: application/json" \ + -d '{"peer":"hub.aitbc.bubuit.net:8006"}' + +# Monitor sync progress +watch -n 5 'curl -s http://localhost:8006/rpc/head | jq .height' +``` + +## hermes Agent Setup + +### Register hermes Agent + +```bash +# Register agent on the open island +NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent create \ + --name "hermes-test-agent" \ + --description "hermes agent testing on open island" \ + --verification full +``` + +### Cross-Node Communication Test + +```bash +# Send test message to hub +NODE_URL=http://hub.aitbc.bubuit.net:8006 /opt/aitbc/venv/bin/aitbc agent message \ + --to hub.aitbc.bubuit.net \ + --content '{"cmd":"TEST_JOIN","node":"test-node"}' \ + --verbose +``` + +## Advanced Setup with hermes Scripts + +For automated setup using hermes: + +```bash +cd /opt/aitbc/scripts/workflow-hermes + +# Run pre-flight setup +./01_preflight_setup_hermes.sh + +# Run follower node setup (modified for hub) +# Edit 03_follower_node_setup_hermes.sh to use hub.aitbc.bubuit.net +./03_follower_node_setup_hermes.sh +``` + +## Troubleshooting + +### Connection Issues + +```bash +# Check if hub is reachable +ping hub.aitbc.bubuit.net +nc -zv hub.aitbc.bubuit.net 8001 +nc -zv hub.aitbc.bubuit.net 8006 + +# Check local services +systemctl status aitbc-blockchain-node.service +systemctl status aitbc-blockchain-p2p.service +journalctl -u aitbc-blockchain-node.service -f +``` + +### Sync Issues + +```bash +# Check sync status +curl http://localhost:8006/rpc/head +curl http://hub.aitbc.bubuit.net:8006/rpc/head + +# Force re-sync +curl -X POST http://localhost:8006/rpc/sync \ + -H "Content-Type: application/json" \ + -d '{"peer":"hub.aitbc.bubuit.net:8006","force":true}' +``` + +### P2P Issues + +```bash +# Check P2P service logs +journalctl -u aitbc-blockchain-p2p.service -f + +# Verify P2P configuration +cat /etc/aitbc/blockchain.env | grep p2p + +# Restart P2P service +systemctl restart aitbc-blockchain-p2p.service +``` + +## Network Security + +**Important Notes:** +- This is a **test island** - do not use for production +- No authentication required - anyone can join +- All transactions are public on the blockchain +- Use test wallets only - no real assets + +## Island Rules + +1. **Testing Only**: This island is for software testing only +2. **No Real Assets**: Use test tokens only +3. **Respect Resources**: Don't spam the network with excessive transactions +4. **Report Issues**: Report bugs to AITBC development team +5. **Experimental**: Features may be unstable + +## Support + +- **Documentation**: `/opt/aitbc/docs/hermes/` +- **Issues**: Report via Gitea at https://gitea.bubuit.net/oib/aitbc +- **Community**: Join AITBC development discussions + +## Next Steps + +After joining the open island: + +1. Test basic blockchain operations (transactions, blocks) +2. Set up hermes agents for cross-node communication +3. Test AI job submission and execution +4. Experiment with smart contracts +5. Contribute test results and feedback + +--- + +**Last Updated**: 2026-05-26 +**Island Status**: Open for Testing +**Hub Node**: hub.aitbc.bubuit.net:8001 (P2P), :8006 (RPC)