Developer Guide on SAM

Kubernetes Deployment and Local Testing Guide

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to deploy the sam-hub in a Kubernetes cluster and how to test it locally using kind and cloud-provider-kind.

[!TIP] This guide focuses on local development sandboxing. For production-grade Kubernetes deployments (GKE, EKS, AKS), see the Production Kubernetes Deployment guide.

This guide supports using either Google OIDC or a Mock OIDC Provider for authentication. The mock provider is recommended for quick local testing as it does not require creating external credentials.

Release Tracks, Autoupdate, and Autoscaling

Mon, 01 Jan 0001 00:00:00 +0000

Sovereign Agent Mesh (SAM) is deployed to public endpoints using automated environments, release tracks, and self-healing/scaling infrastructure.

1. Release Tracks

The public deployment has two isolated release tracks:

A. Testnet Track (Bananas)

Domain Name: bananas.sam-mesh.dev
Source Branch: Tracks the main branch.
Deployment Trigger: Automatically deployed on every new push/commit to the main branch.
Target Tag: The deployment is tagged with the Git commit SHA (github.sha).
Purpose: Serves as the staging/testing playground for the latest features and continuous integration.

B. Production Track (Hub)

Domain Name: hub.sam-mesh.dev
Source Branch: Tracks semantic version tags matching v*.*.*.
Deployment Trigger: Automatically deployed whenever a new version tag is pushed to GitHub.
Target Tag: The deployment is tagged with the exact Git release tag (e.g. v1.0.0).
Purpose: Stable, audited release track for production workloads.

2. Autoupdate Mechanism

Updates to both release tracks are fully automated via a robust Continuous Deployment pipeline:

SAM Policy & Authorization Reference

Mon, 01 Jan 0001 00:00:00 +0000

SAM uses a decentralized authorization model powered by Biscuit. The sam-hub authenticates users via OIDC and injects Facts into their token based on policies.yaml. The sam-node operates offline, evaluating the token against baseline rules and optional local attenuation policies.

1. OIDC to Biscuit Translation

The Hub automatically translates OIDC claims into undeniable cryptographic facts:

OIDC Claim / Data	Biscuit Fact	Description
`sub`	`user("<sub-id>")`	The unique subject ID from the identity provider.
`email`	`email("<email>")`	The user’s email address (if present).
`groups`	`group("<group-name>")`	One fact is injected for each group the user possesses.
`roles` / Resolved Roles	`role("<role-name>")`	One fact is injected for each role mapped or direct role.
Peer ID	`node("<peer-id>")`, `client_peer_id("<peer-id>")`	Binds the token to the specific agent’s libp2p cryptographic identity.
Expiration	`expiration(<date>)`	The token expiration date based on the OIDC session.

1.1 Translating Identity to Capability: OIDC to Biscuit

The core innovation of the SAM Network’s security model is translating standard web identity (OIDC JSON Web Tokens defined in OpenID Connect Core 1.0) into decentralized capability tokens (Biscuits). This translation happens securely at the sam-hub during the authentication phase.

Testing

Mon, 01 Jan 0001 00:00:00 +0000

Current testing is intentionally minimal and aligned with the current binaries.

Test Layers

Go tests: make test
BATS CLI tests: make test-e2e
Containerized BATS mesh tests: make test-e2e-container

Commands

make build
make test
make test-e2e
make test-e2e-container

Go Tests

Run all Go tests with race detection:

make test

Run only integration package:

go test ./tests/integration/...

BATS CLI Tests

These tests validate current command behavior for:

sam-node
sam-hub

Run:

make test-e2e

Containerized Mesh BATS

The container framework is implemented in:

Testnet & Mesh Validation Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial guides you through validating your local environment integration with the public Sovereign Agent Mesh (SAM) testnets (bananas.sam-mesh.dev or hub.sam-mesh.dev). You will learn how to verify your node’s connection, discover remote MCP services, and invoke remote tools.

Prerequisites

Before starting, ensure you have:

Compiled the local binaries (sam-node and mcp-client) by running:
```
make build
```

An active local sam-node container or process running and successfully joined to the target public testnet. For example, join via:

bin/sam-node join https://bananas.sam-mesh.dev

And run via:

docker run --name sam-node \
 -v ~/.config/sam-mesh:/data \
 -p 5001:5001/udp -p 5002:5002 -p 8080:8080 \
 sam-node:local \
 run --data-dir /data \
 --hub https://bananas.sam-mesh.dev \
 --bind-addr 0.0.0.0:8080 \
 --api-token secret-token \
 --log-level debug

Step 1: Verifying Local Connection to the Testnet

Check the logs of your local sam-node to ensure it has successfully joined and is online: