Advanced Federation

This exercise runs the same cleaner robot graph across two runtime hosts. It is not a separate federation demo. The gateway side stays near the simulator or hardware, and the compute side runs components, compound policy, and the app.

same cleaner graph + two runtime hosts = federated cleaner topology

1. What You Will Run

Use two hosts with the same Librux release installed.

Host	Cleaner responsibility
Gateway host	tutorial world, simulator API, and `gateway.device_gateway`
Compute host	`component.*`, `compound.cleaner`, and `app.cleaner.radar`

flowchart LR subgraph GH["Gateway host"] World["Tutorial world"] Gateway["gateway.device_gateway"] end subgraph CH["Compute host"] Mobile["component.mobile"] Arm["component.manipulation"] Grip["component.gripper"] Perception["component.perception"] Compound["compound.cleaner"] App["app.cleaner.radar"] end Gateway --> World Mobile -. "federated binding" .-> Gateway Arm -. "federated binding" .-> Gateway Grip -. "federated binding" .-> Gateway Perception -. "federated binding" .-> Gateway Compound --> Mobile Compound --> Arm Compound --> Grip Compound --> Perception App --> Compound

librux deploy up is host-local. It does not SSH into the peer host. In this exercise, you start each host's local processes directly, then validate the combined graph with the cleaner external deployment manifest.

2. Configure Both Hosts

On the gateway host, expose the control backend on a reachable address and list the compute host as a peer.

. /opt/librux/env.sh
librux config set control.api_host 0.0.0.0
librux config set control.advertise_host <gateway-host>
librux config set federation.peers '[{"host":"<compute-host>","api_port":8001}]'
librux config validate
sudo systemctl restart librux-control.service

On the compute host, do the inverse.

. /opt/librux/env.sh
librux config set control.api_host 0.0.0.0
librux config set control.advertise_host <compute-host>
librux config set federation.peers '[{"host":"<gateway-host>","api_port":8001}]'
librux config validate
sudo systemctl restart librux-control.service

The two hosts must reach each other on control API port 8001. On an untrusted network, enable Web/API security and federation transport security before exposing the hosts.

librux config set federation.security.mode required
librux config set federation.security.key_id cleaner-lab
librux config set federation.security.key_file /opt/librux/var/lib/security/federation.key

Use compatible key material on both hosts before restarting librux-control.service.

3. Start The Gateway Host

Run the tutorial world on the gateway host.

. /opt/librux/env.sh
cd /opt/librux
python3 tutorials/run_sim_world.py --host 0.0.0.0

In another gateway-host terminal, start only the gateway subsystem.

. /opt/librux/env.sh
cd /opt/librux
librux launch run tutorials/subsystems/gateway.device_gateway \
  --instance gateway.device_gateway \
  --set simulator.url=http://127.0.0.1:8092 \
  --detach

Check that the gateway is registered locally.

librux launch list
librux subsystem bindings gateway.device_gateway

The gateway host owns the simulator or hardware resource boundary. Nothing on the compute host should open the simulator or hardware directly.

4. Start The Compute Host

On the compute host, start each component and bind it to the federated gateway interfaces.

. /opt/librux/env.sh
cd /opt/librux
librux launch run tutorials/subsystems/component.mobile \
  --instance component.mobile \
  --bind actuator_servo=gateway.device_gateway.actuator_servo \
  --detach

librux launch run tutorials/subsystems/component.manipulation \
  --instance component.manipulation \
  --bind actuator_servo=gateway.device_gateway.actuator_servo \
  --detach

librux launch run tutorials/subsystems/component.gripper \
  --instance component.gripper \
  --bind digital_io=gateway.device_gateway.digital_io \
  --detach

librux launch run tutorials/subsystems/component.perception \
  --instance component.perception \
  --bind perception_sensor=gateway.device_gateway.perception_query \
  --detach

Start the compound subsystem.

librux launch run tutorials/subsystems/compound.cleaner \
  --instance compound.cleaner \
  --bind mobility=component.mobile.mobile_base \
  --bind manipulation=component.manipulation.manipulator \
  --bind gripper=component.gripper.gripper \
  --bind perception=component.perception.perception \
  --bind actuator_servo=gateway.device_gateway.actuator_servo \
  --bind digital_io=gateway.device_gateway.digital_io \
  --detach

Start the radar app on the compute host.

librux launch run tutorials/subsystems/app.cleaner.radar \
  --instance app.cleaner.radar \
  --bind mobility=compound.cleaner.mobility \
  --bind trash_disposal=compound.cleaner.trash_disposal \
  --bind perception=compound.cleaner.perception_query \
  --detach

5. Validate The Split Cleaner Graph

The installed tutorial includes an external deployment manifest for this development-style bring-up.

librux deploy validate tutorials/deployments/dev/radar.deployment.yaml
librux deploy status tutorials/deployments/dev/radar.deployment.yaml
librux subsystem bindings

Expected result.

compute-host instances are local managed processes
gateway.device_gateway is visible through federation
component requirements bind to the gateway provider interfaces
compound.cleaner provides the capabilities required by app.cleaner.radar
the development deployment is external, so it validates and observes but does not start or stop these manually launched processes

If the gateway appears as missing, check federation peer configuration, firewall rules for port 8001, and the gateway host's advertised address.

6. Observe The Federated Cleaner

Open the world viewer from the gateway host.

http://<gateway-host>:8091/

Open the compute host Web Console separately if you want to inspect the runtime graph where the app and components are local.

http://<compute-host>:8001/

The world viewer should show the same cleaner behavior as the single-host radar deployment. The difference is ownership. Gateway resource policy stays on the gateway host, while application and component workloads stay on the compute host.

7. Cleanup

On the compute host, terminate the manually launched processes.

librux subsystem terminate app.cleaner.radar
librux subsystem terminate compound.cleaner
librux subsystem terminate component.perception
librux subsystem terminate component.gripper
librux subsystem terminate component.manipulation
librux subsystem terminate component.mobile

On the gateway host, terminate the gateway and stop the tutorial world terminal.

librux subsystem terminate gateway.device_gateway

Stop the world terminal with Ctrl-C.

What This Proves

federation is a host-level runtime relation, not a new subsystem role
subsystem manifests and bindings remain the same across host boundaries
deployment validation can describe a split graph without starting remote processes
gateway-host resource policy can stay near the hardware
compute-host app and component policy can stay near CPU or GPU resources
the cleaner graph can move from single host to multi-host without changing application intent

For timing-sensitive multi-host work, combine this with Time Sync Operations before enabling real actuators.