Reference on SAM

sam-node

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

sam-node is the mesh member that runs beside an agent or a service.

sam-node join [control-plane-url] [flags] enroll and store a credential
sam-node run [flags] run the node
sam-node reset [--all] [--yes] forget the credential or everything
sam-node skill install|list|show manage the agent skill document

Files

The data directory is --data-dir if set, otherwise $SAM_DATA_DIR, otherwise the user configuration directory of the operating system (~/.config/sam-mesh on Linux, ~/Library/Application Support/sam-mesh on macOS). It is created with mode 0700 and holds:

sam-control-plane

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

sam-control-plane admits nodes, mints credentials, holds the mesh policy and tracks routers. It is an HTTP server over SQLite or PostgreSQL.

sam-control-plane [flags] run the server
sam-control-plane admin ban --peer <id> ban a node directly in the database
sam-control-plane admin unban --peer <id> lift a ban

Flags

Flag	Default	Meaning
`--issuer`	required	OIDC issuer URL(s), comma-separated. The first is advertised to enrolling nodes on `/info`. Can also be set with `SAM_OIDC_ISSUER`.
`--allowed-audiences`	`sam-mesh-audience`	Audiences accepted in OIDC tokens, comma-separated.
`--oidc-client-id`	first audience	OAuth client ID advertised on `/info`, for providers where it differs from the audience.
`--insecure-skip-tls-verify`	`false`	Skip TLS verification when fetching issuer metadata and keys. For a cluster issuer served with the cluster CA, or a local development issuer.
`--bind-address`	`0.0.0.0:8080`	HTTP listen address.
`--db-driver`	`sqlite`	`sqlite` or `postgres`.
`--db-dsn`	`control-plane.db`	Database DSN. A PostgreSQL DSN contains a password, so the next two options are preferred for PostgreSQL.
`--db-dsn-path`		File containing the DSN. Overrides `--db-dsn`. Can also be set with `SAM_DB_DSN`.
`--admin-token-path`		File containing the bearer token for `/admin/*` and `POST /policies`. Can also be set with `SAM_ADMIN_TOKEN`. Without a token, the admin API cannot be used.
`--auto-approve-enrollment`	`false`	Issue credentials for valid bootstrap-token enrollments immediately instead of queueing them for approval.
`--biscuit-ttl`	`24h`	Lifetime of each credential. If the OIDC token expires sooner, the credential expires with it.
`--oidc-session-ttl`	`2160h` (90 days)	How long an OIDC enrollment may keep refreshing before the identity must log in again.
`--key-rotation-interval`	`24h`	How often a new signing key is generated. `0` disables rotation.
`--key-grace-period`	`1h`	How long a rotated-out key stays accepted. Credentials signed by a retired key cannot be verified or refreshed. Nodes and routers must pull `/keys` well within this window (`sam-node --control-plane-sync-interval`, `sam-router --keys-sync-interval`).
`--lease-duration`	`15m`	How long a router lease lasts without renewal.
`--node-retention`	`720h` (30 days)	How long the record of an enrolled node is kept after its session expires. Banned nodes are kept forever. `0` keeps every record.
`--mesh-reconnect-interval`	`30s`	How often the event publisher re-reads the router leases and dials any router it is not connected to.
`--log-level`	`info`	`debug`, `info`, `warn`, `error`. `LOG_FORMAT=json` selects JSON output.

HTTP API

Two encodings are in use. Routes that mesh components call use protobuf (application/x-protobuf), with messages defined in api/sam.proto. Routes for operators and the console use JSON. POST /policies accepts either.

sam-router

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

sam-router is a libp2p peer with a stable identity that new nodes connect to first. It hosts the DHT, relays traffic between nodes that cannot reach each other, and forwards the control plane’s signed events. It has no policy of its own.

sam-router [flags]

Enrollment

A router enrolls like a node, requesting sam:role:router, with one of:

Flag	Meaning
`--jwt-path`	File containing an OIDC token (a projected service account token, for example).
`--bootstrap-token-path`	File containing a bootstrap token minted with `"role": "sam:role:router"`.
`--oidc-token`, `--bootstrap-token`	The same tokens as values. Visible in process listings. The file forms are preferred.

The mesh policy must bind the router’s identity to sam:role:router. The sam-mesh Helm chart handles this: its bootstrap job binds the router’s service account and mints a bootstrap token with max_usages equal to the replica count.

sam-one

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

sam-one runs a control plane, a router and the web console in one process on one port. The router’s libp2p transport is WebSocket on the same port as the HTTP API, so a node needs only one https URL. The same binary is also the admin client for a running instance.

sam-one [flags] run the mesh
sam-one token create|list|revoke|qr manage bootstrap tokens on a running instance
sam-one admin ban <peer-id> ban a node

Files

Everything lives in --data-dir (default .): sam.db (SQLite), the router key, join-token and admin-token when generated, and bin/ for a downloaded tunnel connector.

Node configuration file

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

sam-node.yaml declares what a node is (labels), what it publishes (services), what it requires from callers (attenuation) and what it requires from providers (egress). Both sam-node join and sam-node run read it from --config, by default ./sam-node.yaml. A missing file means an empty configuration. Unknown keys are an error, because a typo under attenuation would otherwise weaken the node without notice.

version: "v1alpha1"

labels:
 region: eu-west-1
 team: platform

services:
 - type: mcp
 name: code-reviewer
 description: "Reviews diffs"
 target_url: "http://127.0.0.1:7777/mcp"
 - type: mcp
 name: filesystem
 command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/srv/docs"]
 env:
 NODE_OPTIONS: "--max-old-space-size=256"
 - type: inference
 name: vllm
 target_url: "http://127.0.0.1:8000"
 target_auth_path: /etc/sam/vllm-key
 - type: a2a
 name: triage
 target_url: "http://127.0.0.1:9999"

attenuation:
 rules:
 - 'maintenance() <- time($t), $t > 2026-12-31T00:00:00Z;'
 checks:
 - 'check if label("team", "platform");'
 policies:
 - 'deny if service("mcp", "filesystem"), group("contractors");'
 - 'deny if maintenance();'

egress:
 require_labels:
 jurisdiction: eu

`version`

"v1alpha1", or omitted (read as v1alpha1). A node refuses a version it does not know.

Mesh policy

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

The mesh policy is one document held by the control plane: a list of roles and a list of bindings. It is posted as JSON (protojson of PolicyConfigUpdateRequest in api/sam.proto) to POST /policies, edited in the console, or given to sam-one --policy-file for first boot.

{
 "roles": [
 {
 "name": "sam:role:node",
 "allowed_services": ["system://sam.catalog"],
 "allowed_labels": ["region=*", "team=platform"]
 },
 {
 "name": "developer",
 "allowed_services": ["mcp://code-reviewer", "mcp://build-runner.*", "inference://*"],
 "allowed_targets": ["group:dev-nodes", "node:12D3KooWSpecialNode"],
 "allowed_agents": ["*.dev.acme.example"],
 "custom_datalog": ["tier(\"standard\");"]
 }
 ],
 "bindings": [
 { "role": "sam:role:node", "members": ["group:engineering", "user:system:serviceaccount:sam-nodes:calc-mcp-sam-node"] },
 { "role": "developer", "members": ["group:engineering"] }
 ]
}

The whole document is replaced on every post. Unknown fields are rejected, so a misspelt key fails the request instead of dropping a grant without notice.

Node API

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

The local API that sam-node run serves to agents and scripts on the same machine. It is available on TCP (--bind-addr, default 127.0.0.1:8080) and on a Unix socket (--socket-path, default <data-dir>/sam.sock).

Authentication

Listener	Requirement
TCP	`X-Sam-Authentication: Bearer <api-token>` on every request, or a client certificate when `--tls-ca` is set.
Unix socket	None. The socket has mode `0600`. Being able to open it is the credential.

Authorization is reserved for the credential of the service that is being called through the node, and the proxy path forwards it. The endpoints that never forward anything (/mcp, /v1/*, /sam/service/*, /metrics, /sam/identity, /sam/peer/*, /debug/*) also accept the API token in Authorization: Bearer, for clients that cannot set custom headers. The proxy path does not accept it there.