Skip to content

Runtime Cloud

Use this manual when:

  • the cloud/federation wiring already exists
  • you need the operator/developer manual for daily use
  • you are troubleshooting runtime-cloud actions, status, or policy in operation

Manual

Runtime Cloud Manual

This manual covers cloud-plane runtime communication for multi-runtime operation.

Use this pack for onboarding, profile selection, cross-site federation, fleet UI operation, and troubleshooting.

Read in Order

  1. Quickstart: docs/guides/RUNTIME_CLOUD_QUICKSTART.md
  2. Profile cookbook (dev, plant, wan): docs/guides/RUNTIME_CLOUD_PROFILE_COOKBOOK.md
  3. Federation guide: docs/guides/RUNTIME_CLOUD_FEDERATION_GUIDE.md
  4. UI walkthrough: docs/guides/RUNTIME_CLOUD_UI_WALKTHROUGH.md
  5. Troubleshooting: docs/guides/RUNTIME_CLOUD_TROUBLESHOOTING.md

Example Pack

  • examples/runtime_cloud/README.md
  • examples/runtime_cloud/runtime-a-dev.toml
  • examples/runtime_cloud/runtime-b-dev.toml
  • examples/runtime_cloud/runtime-plant.toml
  • examples/runtime_cloud/runtime-wan.toml
  • examples/runtime_cloud/dispatch-status-read.json
  • examples/runtime_cloud/preflight-cross-site-deny.json
  • examples/runtime_cloud/preflight-cross-site-allow.json

Scope Notes

  • This manual focuses on cloud-plane operations and federation behavior.
  • Realtime/T0 timing behavior is documented separately in runtime realtime communication docs.

Validation Gates

Use the runtime-cloud release gates when validating changes: - ./scripts/runtime_comms_bench_gate.sh - ./scripts/runtime_comms_fuzz_gate.sh - ./scripts/runtime_comms_conformance_gate.sh - ./scripts/runtime_cloud_security_profile_gate.sh - ./scripts/check_zenoh_baseline.sh

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

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