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

The manual is for daily use of an existing runtime-cloud setup; the quickstart is for first proof. If you are still deciding whether federation is the right architecture, start with Runtime Cloud Federation.

Success means an operator or maintainer can explain the active topology, run the expected runtime-cloud action, and identify whether a failure is topology, policy, credentials, or runtime state.

Use Observability next when the daily-use question turns into evidence collection over time.

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

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