The Problem

Deploying a trustworthy, peer‑to‑peer network for autonomous AI agents is currently a niche effort that requires stitching together multiple runtimes, identity services, and transport layers. Teams must manually provision control‑plane services, configure libp2p routers, and keep language‑specific adapters in sync, which leads to configuration drift and fragile deployments.

What This Does

sam (Sovereign Agent Mesh) delivers a ready‑to‑run collection of self‑contained projects that implement a zero‑config, zero‑trust mesh. The core binaries live under cmd/ – e.g. cmd/sam-control-plane/main.go, cmd/sam-router/main.go, and cmd/sam-node/main.go – and are built from the Go sources in internal/.

The control plane (internal/controlplane/server.go) stores node identities and policies; the router (cmd/sam-router/main.go) runs libp2p bootstrap and relay services; the node binary (cmd/sam-node/main.go) embeds a lightweight MCP sidecar for tool invocation.

Language‑specific adapters (Python, JavaScript, Dart) are in development/examples/ and sam-mcp-python/, showing how to plug a Gemini, Claude, or custom LLM into the mesh. The Helm chart in charts/sam-mesh/ and the Dockerfiles (Dockerfile.sam‑node, Dockerfile.sam‑control‑plane, etc.) give production‑grade deployment artifacts.

How It Is Wired

Execution begins at the Go main functions in cmd/. For a typical node launch:

  1. cmd/sam-node/main.go parses flags, reads the local identity file, and calls internal/node.Start.
  2. internal/node.Start creates a libp2p host, registers with the control‑plane via internal/controlplane/client.go, and launches the MCP sidecar (sam-mcp-python/src/sam_mcp/client.py if the Python adapter is enabled).
  3. The control‑plane server (internal/controlplane/server.go) listens on gRPC, handling RegisterNode, Authorize, and PolicyLookup calls. No circular imports are present; the import graph contains 24 internal modules with only 4 import edges, keeping the blast radius limited to the control‑plane package.
  4. The router (cmd/sam-router/main.go) runs the libp2p relays defined in the Helm chart templates, forwarding traffic between nodes.

The most connected module is development/examples/code-reviewer-pool/reviewer/lease-token (imported by two other modules) but it does not affect the core mesh. Files such as api/sam.pb.go and api/datalog.go expose protobuf‑generated RPC definitions used by the control‑plane and routers. Because the repository is a portfolio of eight independent projects, there is no single monolithic call chain; each binary owns its side‑effects (network sockets, file I/O, Docker builds).

How To Use It

# Clone the repo
git clone https://github.com/moses-y/sam
cd sam

# Build all Go binaries (Makefile defines targets)
make          # builds sam-control-plane, sam-router, sam-node, etc.

# Run a local control plane (example)
docker build -f Dockerfile.sam-control-plane -t sam-control-plane .
docker run -p 8080:8080 sam-control-plane

# Launch a node that connects to the local control plane
docker build -f Dockerfile.sam-node -t sam-node .
docker run -e CONTROL_PLANE=host.docker.internal:8080 sam-node

For language adapters, follow the development/examples/ README files. The quick‑start guide is in site/content/docs/quickstart.md.

Real‑World Use

A fintech firm can spin up a private SAM mesh inside a Kubernetes cluster (using charts/sam-mesh/). Their LLM‑driven compliance agents register as sam-node pods, discover each other via the control‑plane, and invoke policy‑checking tools through the MCP sidecar without hard‑coded endpoints. The mesh’s zero‑trust TLS handshake ensures that only authorized agents execute the tools.

Code Health & Issues

  • High – Continue‑on‑error in CI: .github/workflows/govulncheck.yml line 25. Remove or isolate the step.
  • Medium – npm lockfile not used: .github/workflows/* runs npm install. Switch to npm ci.
  • Medium – Unpinned base images: Dockerfile.nano-init uses golang:1.26.5. Pin by digest.
  • Medium – Large binary in repo: site/static/demo.gif (7.5 MiB). Move to Git LFS or external storage.
  • Low – Missing job timeouts: .github/workflows/deploy-github-pages.yml. Add timeout-minutes.
  • Low – Missing convention files: No .editorconfig, .gitattributes, or formatter config. Add them.

Measured static findings (60 total) include 29 deep‑nesting hotspots (e.g., cmd/sam-box/main.go), duplicated 6‑line blocks across >150 files, and 18 oversized files (e.g., api/sam.pb.go at 1,757 lines). Broad except: handlers appear in sam-mcp-python/src/sam_mcp/client.py.

The Bottom Line

sam provides a functional, container‑ready mesh for autonomous agents with clear entry points and a modest import graph, making it approachable for teams that need a P2P AI network. However, the codebase suffers from high cognitive load, duplicated logic, and several CI/ops hygiene gaps that should be addressed before adopting it in a production‑critical environment.