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
2026-05-26 08:42:48 +02:00
parent 22c4192c76
commit 9f44ca9e6d
3 changed files with 629 additions and 0 deletions
--- 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.
--- a/docs/hermes/guides/hermes-open-island-guide.md
+++ 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 <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 <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)
--- a/docs/hermes/guides/open-island-joining-guide.md
+++ 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)