Runtime Cloud Federation¶

Use this guide when:

you are still deciding topology
the system crosses one LAN/site boundary
transport and control-plane policy need to be designed together

Quickstart¶

Runtime Cloud Quickstart¶

Goal: bring two runtimes online, verify discovery/state projection, and perform cross-runtime dispatch with deterministic preflight.

1) Prerequisites¶

trust-runtime available in PATH
Two terminals
curl and jq
Linux/macOS shell

2) Bootstrap Two Runtime Projects¶

Create project folders once (first run creates bundle layout):

mkdir -p ~/trust-cloud-demo
trust-runtime play --project ~/trust-cloud-demo/runtime-a
# Stop with Ctrl+C after startup messages appear.
trust-runtime play --project ~/trust-cloud-demo/runtime-b
# Stop with Ctrl+C after startup messages appear.

3) Apply Known-Good Dev Profile Configs¶

cp examples/runtime_cloud/runtime-a-dev.toml ~/trust-cloud-demo/runtime-a/runtime.toml
cp examples/runtime_cloud/runtime-b-dev.toml ~/trust-cloud-demo/runtime-b/runtime.toml

If ports 18081, 18082, 5201, or 5202 are already in use on your host, update listen values in the copied runtime.toml files before startup.

The example configs include explicit mesh baseline keys: - runtime.mesh.role = "peer" - runtime.mesh.connect = [] - runtime.mesh.zenohd_version = "1.7.2"

4) Start Both Runtimes¶

Terminal 1:

trust-runtime play --project ~/trust-cloud-demo/runtime-a

Terminal 2:

trust-runtime play --project ~/trust-cloud-demo/runtime-b

5) Verify Runtime Cloud State¶

curl -s http://127.0.0.1:18081/api/runtime-cloud/state | jq '{context: .context, nodes: .topology.nodes, edges: .topology.edges}'

Expected: - context.connected_via exists - topology.nodes contains runtime-a and runtime-b - topology.edges shows communication links

6) Preflight a Cross-Runtime Read¶

curl -s http://127.0.0.1:18081/api/runtime-cloud/actions/preflight \
  -H 'content-type: application/json' \
  -d @examples/runtime_cloud/dispatch-status-read.json | jq

Expected: - allowed: true - no denial_code

7) Dispatch Cross-Runtime Read and Verify Audit Link¶

curl -s http://127.0.0.1:18081/api/runtime-cloud/actions/dispatch \
  -H 'content-type: application/json' \
  -d @examples/runtime_cloud/dispatch-status-read.json | jq

Expected: - top-level ok: true - results[0].runtime_id == "runtime-b" - results[0].audit_id present

8) Optional: Local Config Apply Through Runtime Cloud Dispatch¶

curl -s http://127.0.0.1:18081/api/runtime-cloud/actions/dispatch \
  -H 'content-type: application/json' \
  -d '{
    "api_version": "1.0",
    "request_id": "req-quickstart-cfg-1",
    "connected_via": "runtime-a",
    "target_runtimes": ["runtime-a"],
    "actor": "spiffe://trust/default-site/engineer-1",
    "action_type": "cfg_apply",
    "dry_run": false,
    "payload": { "params": { "log.level": "debug" } }
  }' | jq

Expected: - ok: true - per-target audit_id present

9) Next Steps¶

docs/guides/RUNTIME_CLOUD_PROFILE_COOKBOOK.md
docs/guides/RUNTIME_CLOUD_FEDERATION_GUIDE.md
docs/guides/RUNTIME_CLOUD_UI_WALKTHROUGH.md

Federation Guide¶

Runtime Cloud Federation Guide¶

Goal: enable cross-site runtime cloud control safely with explicit allowlists and auditable outcomes.

Important: - The TOML blocks in this document are policy overlays, not complete runtime.toml files. - Start from a generated baseline (trust-runtime wizard --path <project>), then merge these sections. - For complete runnable examples, use examples/runtime_cloud/runtime-*.toml.

1) Federation Model¶

A local site can act on remote-site runtimes through runtime cloud dispatch
Cross-site write actions are denied by default in wan unless explicitly allowlisted
Dry-run preflight is mandatory before cross-site writes
Mesh/version baseline must stay aligned to Zenoh 1.7.2 across runtimes/gateways unless an approved exception exists

2) Runtime ID and Actor Conventions¶

Use consistent identities:

Runtime IDs: <site>/<runtime> (example: site-b/runtime-b)
Actor identities: spiffe://trust/<site>/<principal>

3) Baseline WAN Configuration¶

On the egress runtime (originating cross-site actions):

# Overlay only
[runtime.control]
auth_token = "REPLACE_WITH_LONG_RANDOM_TOKEN"

[runtime.web]
auth = "token"
tls = true

[runtime.tls]
mode = "self-managed"
cert_path = "./certs/runtime.crt"
key_path = "./certs/runtime.key"

[runtime.cloud]
profile = "wan"

[runtime.cloud.wan]
allow_write = []

4) Verify Default Cross-Site Deny¶

curl -s http://127.0.0.1:18081/api/runtime-cloud/actions/preflight \
  -H 'content-type: application/json' \
  -d @examples/runtime_cloud/preflight-cross-site-deny.json | jq

Expected: - allowed: false - denial_code: "permission_denied" - reason references cross-site write + explicit allowlist requirement

5) Add Explicit Allowlist Rule¶

# Overlay only
[runtime.cloud.wan]
allow_write = [
  { action = "cfg_apply", target = "site-b/*" }
]

Re-run preflight:

curl -s http://127.0.0.1:18081/api/runtime-cloud/actions/preflight \
  -H 'content-type: application/json' \
  -d @examples/runtime_cloud/preflight-cross-site-allow.json | jq