Skip to content

Agent Mesh

update content

Antonio Ojea861551d24b65
diff --git a/README.md b/README.md
index 65910860..6fb52436 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,6 @@ Start exploring the Sovereign Agent Mesh:
Get a node running on the public testnet (`bananas.sam-mesh.dev`) in minutes:
- πŸš€ **[User Quick Start Guide](site/content/docs/quickstart.md)**: Connect and run a SAM node using binaries or Docker, and query the local MCP server.
- πŸ€– **[Agent Integration Guides](site/content/docs/integrations/_index.md)**: Connect Google Gemini, Claude, and other AI agents to your SAM node to dynamically discover and call tools across the mesh.
-- πŸ“– **[CLI Reference](site/content/docs/cli/reference.md)**: Comprehensive CLI reference and configurations.
- πŸ“‘ **[Testnet Validation Tutorial](site/content/docs/development/testnet-validation.md)**: Real-time verification, remote tool invocation, and HTTP stream proxies.
### For Developers & Contributors
diff --git a/site/content/docs/_index.md b/site/content/docs/_index.md
index aa6dc087..b4b115f9 100644
--- a/site/content/docs/_index.md
+++ b/site/content/docs/_index.md
@@ -24,7 +24,6 @@ The documentation here is intentionally small and aligned with what is implement
- [Quick Start](quickstart.md) - User Quick Start using Docker.
- [Hub Configuration](user/hub-configuration.md) - OIDC authentication, key rings, and custom policy rules in `policies.yaml`.
- [Agent Usage](user/agent-usage.md) - Node authorization flows, MCP endpoints, and how agents connect.
-- [CLI Reference](cli/reference.md) - CLI command usage reference.
- [Developer Guide](development/_index.md) - Building from source, local testing, and Kind setups.
- [Testing Guide](development/testing.md) - Detailed test layer and troubleshooting information.
- [Testnet Validation Tutorial](development/testnet-validation.md) - Real-time integration and MCP verification with public testnets.
diff --git a/site/content/docs/development/kubernetes-deployment.md b/site/content/docs/development/kubernetes-deployment.md
index 09a2605f..2c5460b7 100644
--- a/site/content/docs/development/kubernetes-deployment.md
+++ b/site/content/docs/development/kubernetes-deployment.md
@@ -90,31 +90,32 @@ To connect a `sam-node` to the hub, you just need the hub's external IP and port
To connect a `sam-node` to the hub for the first time, you need to enroll it. The node needs to authenticate with the hub using a JWT token.
-If you are using the **Mock OIDC Provider**, the node can fetch the token automatically from the mock provider's token endpoint.
+If you are using the **Mock OIDC Provider**, the node can fetch the token using OIDC Client Credentials flow:
1. **Get the Mock OIDC Service IP:**
```bash
MOCK_IP=$(kubectl get svc mock-oidc -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
```
-2. **Run the Node with Token URL:**
+2. **Run the Node to enroll:**
```bash
sam-node run \
- --hub "$HUB_IP:4002" \
- --token-url "http://$MOCK_IP:18080/token"
+ --hub "http://$HUB_IP:9090" \
+ --oidc-issuer "http://$MOCK_IP:18080" \
+ --client-id "sam-mesh-audience" \
+ --client-secret "sam-e2e-secret"
```
If you are using **Google OIDC**, you must obtain a valid Google ID token for your user and pass it via the `--jwt` flag:
```bash
sam-node run \
- --hub "$HUB_IP:4002" \
+ --hub "http://$HUB_IP:9090" \
--jwt "<your-google-id-token>"
```
-Once enrolled, identity is stored in the local database, and you can run without authentication flags:
+Once enrolled, the identity is stored in the local database (`agent.db`), and you can run subsequent times without OIDC credentials:
```bash
-sam-node run \
- --hub "$HUB_IP:4002"
+sam-node run
```
---
@@ -148,9 +149,13 @@ spec:
command: ["sam-node", "run"]
args:
- "--hub"
- - "sam-hub:4002"
- - "--token-url"
- - "http://mock-oidc:18080/token"
+ - "http://sam-hub:9090"
+ - "--oidc-issuer"
+ - "http://mock-oidc:18080"
+ - "--client-id"
+ - "sam-mesh-audience"
+ - "--client-secret"
+ - "sam-e2e-secret"
env:
- name: HOME
value: /data
@@ -169,25 +174,27 @@ The SAM project supports three primary flows for acquiring a JWT token to enroll
#### 1. Client Credentials Flow (Machine-to-Machine)
* **Description:** Defined in OAuth 2.0 RFC 6749, section 4.4. An application exchanges its application credentials (such as Client ID and Client Secret) for an access token.
* **Use Case:** For unattended services or deployments connecting to a production OIDC provider.
-* **How to use:** Pass the `--token-url`, `--client-id`, and `--client-secret` flags to `sam-node run`.
+* **How to use:** Pass the `--oidc-issuer`, `--client-id`, and `--client-secret` flags to `sam-node run`.
* **Example:**
```bash
sam-node run \
- --hub "hub.example.com:4002" \
- --token-url "https://oauth2.googleapis.com/token" \
+ --hub "http://hub.example.com:9090" \
+ --oidc-issuer "https://accounts.google.com" \
--client-id "$SAM_OIDC_ID" \
--client-secret "$SAM_OIDC_SECRET"
```
#### 2. Native App Authorization Code Flow (Human Intervention)
-* **Description:** For devices operated by humans, this uses the standard Authorization Code Flow with PKCE for native apps (RFC 8252). `sam-node` spins up a temporary local HTTP server, opens your browser, and receives the authentication token locally via an ephemeral loopback address.
+* **Description:** For devices operated by humans, this uses the standard Authorization Code Flow with PKCE for native apps (RFC 8252). The human operator runs `sam-node join` to open a web browser (or get a verification code via `--headless`), completes the login, and obtains a Biscuit token which is stored in the local database (`agent.db`).
* **Use Case:** When a human operator is enrolling a node manually via their local terminal.
-* **How to use:** When you omit the `--jwt` or `--token-url` flags (or pass the OIDC issuer flag interactively), the node opens the browser and completes the flow without needing to enter complex passwords in the CLI. Alternatively, you can obtain a token yourself and pass it via the `--jwt` flag.
+* **How to use:** Run `sam-node join <hub-url>` before running the node daemon. Alternatively, you can obtain a token yourself and pass it via the `--jwt` flag to `sam-node run`.
* **Example:**
```bash
-sam-node run \
- --hub "hub.example.com:4002" \
- --jwt "eyJhbGciOiJSUzI1NiIs..."
+# First, join interactively:
+sam-node join https://hub.example.com
+
+# Then start the node daemon:
+sam-node run
```
#### 3. Workload Identity Federation (Secretless Kubernetes)
@@ -198,7 +205,7 @@ sam-node run \
* **Example:**
```bash
sam-node run \
- --hub "hub.example.com:4002" \
+ --hub "http://hub.example.com:9090" \
--jwt-path "/var/run/secrets/kubernetes.io/serviceaccount/token"
```
> [!NOTE]
@@ -269,7 +276,7 @@ spec:
command: ["sam-node", "run"]
args:
- "--hub"
- - "sam-hub:4002"
+ - "http://sam-hub:9090"
- "--jwt-path"
- "/var/run/secrets/tokens/sam-token"
volumeMounts:
diff --git a/site/content/docs/development/policy.md b/site/content/docs/development/policy.md
index bbb5ce2f..d929b4c2 100644
--- a/site/content/docs/development/policy.md
+++ b/site/content/docs/development/policy.md
@@ -67,6 +67,9 @@ allow if group("engineering");
## 2. Hub Policy Schema (`policies.yaml`)
Admins define central permissions by mapping OIDC roles to specific capabilities.
+> [!IMPORTANT]
+> Wildcards (e.g. `*`) are explicitly disallowed in policy definitions. All allowed network targets and MCP servers must be explicitly listed.
+
```yaml
version: "v1alpha1"
roles:
@@ -74,7 +77,7 @@ roles:
network:
allowed_targets: ["db-agent.data-mesh"] # Who they can connect to
mcp:
- allowed_tools: ["query_database"] # What tools they can run
+ allowed_servers: ["db-agent"] # Allowed MCP server names
custom_datalog:
- 'department("analytics");' # Raw injected facts
```
diff --git a/site/content/docs/manifests/sam-hub.yaml b/site/content/docs/manifests/sam-hub.yaml
index 8d35a29a..7afdf99b 100644
--- a/site/content/docs/manifests/sam-hub.yaml
+++ b/site/content/docs/manifests/sam-hub.yaml
@@ -47,7 +47,7 @@ spec:
- "--mesh=public-mesh"
- "--issuer=$(SAM_OIDC_ISSUER)"
ports:
- - containerPort: 8080
+ - containerPort: 9090
name: public-port
env:
- name: SAM_HUB_KEY
@@ -81,7 +81,7 @@ spec:
app: sam-hub
ports:
- protocol: TCP
- port: 8080
- targetPort: 8080
+ port: 9090
+ targetPort: 9090
name: public-port
diff --git a/site/content/docs/user/agent-usage.md b/site/content/docs/user/agent-usage.md
index 9e1abfc9..6bbc34dd 100644
--- a/site/content/docs/user/agent-usage.md
+++ b/site/content/docs/user/agent-usage.md
@@ -19,13 +19,13 @@ sequenceDiagram
participant Agent as AI Agent (Gemini/Claude)
Note over User,Hub: Phase 1: Mesh Join (OIDC Authorization)
- User->>Node: sam-node join --hub <hub-url>
+ User->>Node: sam-node join <hub-url>
Node->>Hub: Get Hub OIDC Info
Hub-->>Node: OIDC Issuer, Client ID
Node->>User: Display Login URL & Code
User->>User: Login in Browser
Node->>Hub: Exchange Code for Biscuit Identity
- Node->>Node: Persist Biscuit in Local Store
+ Node->>Node: Persist Biscuit in Local Store (agent.db)
Note over User,Agent: Phase 2: Agent Tool Invocation
User->>Node: sam-node run --api-token "secret-key"
@@ -45,23 +45,23 @@ Before starting the node daemon, you must authorize your node and obtain a crypt
### Standard Login
Run the `join` command, pointing to the mesh control hub:
```bash
-sam-node join --hub https://bananas.sam-mesh.dev
+sam-node join https://bananas.sam-mesh.dev
```
* **Browser Flow**: The CLI will discover the OIDC credentials from the hub, print an OIDC authorization URL, and attempt to open your system's default web browser automatically.
-* **Approval**: Log in with your corporate or identity credentials (e.g. Google Accounts), approve the authorization request, and return to the terminal. The node will automatically exchange the credentials for a Biscuit token and save it to `~/.config/sam-mesh/identity.json`.
+* **Approval**: Log in with your corporate or identity credentials (e.g. Google Accounts), approve the authorization request, and return to the terminal. The node will automatically exchange the credentials for a Biscuit token and save it to `~/.config/sam-mesh/agent.db`.
### Headless (Server) Login
If you are running the node on a remote server via SSH (without a web browser), force headless out-of-band mode:
```bash
-sam-node join --hub https://bananas.sam-mesh.dev --headless
+sam-node join https://bananas.sam-mesh.dev --headless
```
The CLI will print a verification URL and code (e.g. `https://google.com/device` and `ABCD-EFGH`). Open this URL on your local laptop, enter the code, complete the login, and the remote terminal session will activate automatically.
### Automatic Token Renewal
To allow long-lived nodes to automatically renew their tokens in the background, request offline access (refreshes the OIDC session):
```bash
-sam-node join --hub https://bananas.sam-mesh.dev --offline-access
+sam-node join https://bananas.sam-mesh.dev --offline-access
```
---
diff --git a/site/content/docs/user/hub-configuration.md b/site/content/docs/user/hub-configuration.md
index 1d90c39f..6b272297 100644
--- a/site/content/docs/user/hub-configuration.md
+++ b/site/content/docs/user/hub-configuration.md
@@ -28,7 +28,7 @@ The hub is highly configurable. Each setting can be passed as a command-line fla
| `--listen` | *None* | `[]` | Comma-separated libp2p multiaddrs to listen on (e.g. `/ip4/0.0.0.0/tcp/9090`). |
| `--bind-address` | *None* | `:9090` | Host and port to listen on for the HTTP/HTTPS admin service. |
| `--policy-file` | *None* | `policies.yaml` | Path to the YAML file defining authorization roles and bindings. |
-| `--allowed-audiences` | *None* | `sam-audience` | Comma-separated list of allowed JWT audiences. |
+| `--allowed-audiences` | *None* | `sam-mesh-audience` | Comma-separated list of allowed JWT audiences. |
| `--insecure-skip-tls-verify` | *None* | `false` | Set to `true` to skip certificate validation for development/testing OIDC providers. |
| `--keys-db` | *None* | `keys.db` | Path to the BoltDB file storing public/private keys for token validation. |
| `--admin-token` | *None* | *None* | Secret token string required in the HTTP Header `Authorization: Bearer <token>` for admin operations. |
@@ -41,6 +41,9 @@ The hub is highly configurable. Each setting can be passed as a command-line fla
The hub dynamically issues permissions inside the Biscuit token based on identity claims (users or groups) mapped to specific roles in the policy file.
+> [!IMPORTANT]
+> For security reasons, wildcards (e.g. `*`) are explicitly disallowed in policy definitions. All allowed network targets and MCP servers must be explicitly listed.
+
### Example Policy Mapping
Create a `policies.yaml` file in the directory where you run `sam-hub`:
@@ -51,22 +54,25 @@ version: v1alpha1
roles:
developer-role:
network:
- allowedTargets:
+ allowed_targets:
- "10.0.0.0/8"
- "192.168.1.0/24"
mcp:
- allowedServers:
+ allowed_servers:
- "local-shell-tools"
- "git-helper"
admin-role:
network:
- allowedTargets:
+ allowed_targets:
- "10.0.0.0/8"
- "172.16.0.0/12"
+ - "192.168.1.0/24"
mcp:
- allowedServers:
- - "*" # Allow access to all MCP servers
+ allowed_servers:
+ - "local-shell-tools"
+ - "git-helper"
+ - "db-agent"
# Bind OIDC user emails or group claims to roles
bindings: