sam-mesh

# SAM Agent Skill

Use this skill when local tools cannot satisfy the task and the SAM mesh can.
Prefer local tools first. Reach into the SAM mesh only for the capability needed
to complete the task.

Pick the path that matches the need:

- The `sam-node` MCP tools are not callable yet:
  [Bootstrap A Node](#bootstrap-a-node).
- The task needs a plain HTTP call to the node, such as inference or a
  `local_proxy_url`: [Talk To The Node Over HTTP](#talk-to-the-node-over-http).
- The node is up but the mesh seems broken:
  [Diagnose The Node](#diagnose-the-node).
- The task needs a remote tool or capability:
  [Inspect The Mesh](#inspect-the-mesh).
- The task needs a model completion:
  [Use Mesh Inference](#use-mesh-inference).

## Bootstrap A Node

The mesh is reached through a local `sam-node`. When its MCP tools are missing,
guide the user through these steps. Propose each shell command and let the user
approve it before running anything.

1. Check the CLI: `sam-node --help`. If it is missing, install it with
   `curl -sL https://sam-mesh.dev/install.sh | bash` or
   `go install github.com/google/sam/cmd/sam-node@latest`.
2. Start the node in the background: `sam-node run --daemonize`. It returns as
   soon as the node answers, and prints the endpoint, the API token file, the
   log file, and how to stop it. It is idempotent, so run it again whenever you
   need to confirm a node is up.
3. If step 2 reports that the node is not enrolled, run the command it prints,
   `sam-node join --headless <control-plane-url>`. In headless mode SAM now
   prefers OAuth device flow automatically when the OIDC provider supports it,
   so no pasted callback code is required: it prints a verification URL/code
   and polls until login completes. If the provider does not expose a device
   endpoint, SAM falls back to OOB code-paste flow; show the URL/code to the
   user, wait for completion, then repeat step 2. For deterministic automation,
   force the flow with `--auth-mode device` (also `oob`, `browser`, or the
   default `auto`); `--auth-mode device` fails fast if the provider has no
   device endpoint. Enrollment is a one-time step per machine.
4. Read the node API token from the file named in step 2, then register the MCP
   endpoint `http://127.0.0.1:8080/mcp` with the header
   `X-Sam-Authentication: Bearer <token>`. Claude Code:
   `claude mcp add --transport http sam-mesh http://127.0.0.1:8080/mcp --header "X-Sam-Authentication: Bearer <token>"`.
   Antigravity: add the same URL as `serverUrl` with the same header to
   `~/.gemini/config/mcp_config.json`.
5. Tell the user to restart the agent session, since MCP tools load at startup.

MCP clients need that HTTP endpoint. For everything else — shell commands and
direct HTTP calls to the node — see
[Talk To The Node Over HTTP](#talk-to-the-node-over-http): the Unix socket gets
you in without a token.

If setup is stuck in a half-configured state, ask the user before starting over:
stop the node, run `sam-node reset --all --yes` for a clean slate, then go back
to step 2. That deletes the node's identity and its PeerID, and enrolling again
needs another login, so never do it to work around an unexplained error.

Put the node API token only in the agent's MCP configuration. Do not echo it
into the transcript, and do not commit it.

## Talk To The Node Over HTTP

The MCP tools need none of this. It applies when a task needs a plain HTTP
request to the node: the OpenAI-compatible `/v1` endpoints, or a
`local_proxy_url` returned by `discover_remote_services`.

There are two ways in. Try them in this order.

**1. The Unix socket, whenever there is one.** `get_mesh_info` reports it as
`local_api_socket`, by default `~/.config/sam-mesh/sam.sock`. It serves the same
API and takes no token at all: only the user who owns the socket can connect to
it, so the filesystem has already done the authenticating. Prefer it, because no
secret reaches a command line, the shell history, or the transcript.

```bash
curl --unix-socket ~/.config/sam-mesh/sam.sock http://localhost/v1/models
```

The host in the URL is a placeholder that curl ignores once it dials a socket.

**2. The TCP endpoint, with the node API token.** Use this when `get_mesh_info`
reports no `local_api_socket`, or when that path is not reachable from where you
run, for example a node inside a container. You already hold that token: it is
the header you were configured with to reach this MCP server in the first place.
Read it back from your own MCP client configuration — the `sam-mesh` entry in,
for example, `~/.gemini/config/mcp_config.json` or `~/.claude.json` — rather than
asking the user for it or reading the node's token file.

```bash
curl http://127.0.0.1:8080/v1/models -H "X-Sam-Authentication: Bearer <token>"
```

Never print the token or echo it into the transcript. `Authorization` is not the
node's credential: send it only when the destination service needs its own, and
it passes through to that service untouched.

## Diagnose The Node

Operator diagnostics are not MCP tools, so they never appear in the tool list.
A running node serves them under `/debug`, and the `sam-node` CLI wraps each
endpoint over the node's Unix socket — no token involved:

```bash
sam-node debug mesh-info                 # connected peers, DHT size, router peer ID
sam-node debug connectivity [peer-id]    # ping the SAM router, or a specific peer
sam-node debug network-info              # listen and observed addresses
sam-node debug token-info                # local auth token expiration and status
sam-node debug logs                      # recent log lines
sam-node debug connect-peer <multiaddr>  # manually dial a peer
```

Each command prints the endpoint's raw JSON, so it composes with `jq`. The same
data is one `curl` away when the CLI is not at hand:

```bash
curl --unix-socket ~/.config/sam-mesh/sam.sock http://localhost/debug/mesh-info
```

These endpoints answer even while the mesh is unreachable — that is the s