Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
Add documentation for scale experiment scripts
Antonio Ojeada11147beed9
diff --git a/scripts/README.md b/scripts/README.mdnew file mode 100644index 00000000..beaa2001--- /dev/null+++ b/scripts/README.md@@ -0,0 +1,39 @@+# SAM Scale Experiment Scripts++This directory contains the automation scripts to run massive scale experiments of the SAM mesh network using Google Cloud Platform (GCP) and Firecracker microVMs.++## Architecture Overview++The scale testing environment is designed to minimize cloud costs while simulating highly realistic isolated workloads:+- **GCP Minion VMs**: Large host machines (e.g., `n2-standard-64`) with nested virtualization enabled.+- **Firecracker MicroVMs**: Dozens of lightweight VMs running on each Minion VM, ensuring strong isolation.+- **Chaos Agent (`cmd/chaos-agent`)**: A LangChain-based Python workload running inside the MicroVM that connects transparently to the Mesh via an MCP loop, fuzzing the endpoints.++## Step-by-Step Guide++### 1. Build the MicroVM Image+Run the `build-rootfs.sh` script locally. This uses Docker to create an Alpine Linux `rootfs.ext4` containing your `chaos-agent` and network proxies (tun2proxy/socat).++```bash+# Build locally and automatically upload to your Google Cloud Storage bucket+./scripts/build-rootfs.sh gs://my-sam-bucket/scale-test+```++### 2. Provision the Cloud Minions+Use the `provision-scale-vm.sh` script to bulk-create your GCP Minion VMs. The script automatically compiles your local `sam-node` and `sam-box` binaries, uploads them, and configures the VMs via `cloud-init.yaml`.++```bash+# Provision 100 VMs using your local binaries and rootfs+./scripts/provision-scale-vm.sh --prefix sam-minions --count 100 --local-binaries gs://my-sam-bucket/scale-test+```++### 3. Launch MicroVMs+Once the GCP Minions boot up, their `cloud-init` automatically downloads Firecracker, your rootfs, and the latest SAM binaries.+SSH into a Minion VM (or use a startup-script wrapper) and run the launcher:++```bash+# Launch 20 isolated microVMs per host+/opt/microvm/launch-microvms.sh 20+```++Each microVM is spawned with a dedicated `sam-box` running on the host. Network traffic is transparently routed out of the guest using `tun2proxy` over Firecracker VSOCK, hitting the local `sam-box` UDS endpoint.