Robot/Application/Deployment Manifests

This page defines the manifest shape used to compose one robot application.

Subsystem Role

Every subsystem manifest declares exactly one role.

kind: librux.subsystem
version: 1

subsystem:
  name: component.motion
  role: component

Supported roles are these.

app
component
gateway
compound

Robot slots accept component, gateway, and compound. The application subsystem is attached by the deployment.

Robot Manifest

librux.robot.yaml describes the app-less platform, including kinematics, parts, slots, and capabilities. The file name keeps the top-level robot vocabulary, but the thing it contributes to robot = platform + application + deployment is the platform definition.

kind: librux.robot
version: 1

robot:
  name: cleaner_2d
  model: tutorial-cleaner-2d
  profiles:
    - tutorial.robot_cleaner.cleaner_2d.v1

kinematics:
  source: ./frontend
  base_frame: cleaner_base
  tool_frame: cleaner_gripper

parts:
  base:
    kind: mobile_base
    frame: cleaner_base
  device_bus:
    kind: simulated_device_bus
    frame: world

slots:
  mobile_base_controller:
    role: component
    part: base
    contract: component.mobile_base.v1
  actuator_gateway:
    role: gateway
    part: device_bus
    contract: api.actuator.servo.v1

capabilities:
  mobility.teleop:
    capability: capability.mobility.teleop.v1
    implementation:
      kind: compound_subsystem
      subsystem: compound.cleaner
      interface: mobility
      contract: capability.mobility.teleop.v1
    features:
      - manual_drive
  arm_device:
    contract: api.actuator.servo.v1
    implementation:
      kind: direct_binding
      subsystem: gateway.arm
      interface: arm
      contract: api.actuator.servo.v1
      control: servo_joint

robot.profiles is the manifest field for optional platform compatibility labels. These labels are useful when an application intentionally targets a specific robot family, but capability requirements are the main app compatibility surface. They are labels, not spec profiles. slots describe which component, gateway, and compound contracts must be filled, and which subsystem role will fill each slot. Slot contracts must be public Librux spec contracts from the installed dictionary.

component slots normally use component.*
gateway slots use api.*
compound slots may use capability.* or be left contractless when the slot is only the compound provider identity

Tutorial/private contracts are allowed inside subsystem bindings only; they cannot define robot slots. capabilities are the application-facing contract surface of the platform. The preferred form uses a capability.* semantic spec and points at a compound-provided public interface. That keeps applications independent from gateway topology, controller vendor, and device channel layout.

A platform may also expose a narrow public api.* or component.* contract through kind: direct_binding. Treat this as an explicit low-level outlet, not as a portable semantic capability. A direct_binding implementation names exactly one control, procedure, or operation endpoint from the referenced contract. More complex behavior should use kind: compound_subsystem.

Application Role Subsystem

An application is a subsystem. Its subsystem.yaml uses subsystem.role: app and may include an application.requires_robot section to describe the capabilities, and optionally the platform compatibility labels, it needs.

kind: librux.subsystem
version: 1

subsystem:
  name: app.pick_place
  role: app

application:
  requires_robot:
    profiles:
      - librux.robot.manipulator_pick_place.v1
    capabilities:
      pick_place:
        capability: capability.manipulation.reach.v1
        features:
          - trajectory_tracking

requires:
  manipulation:
    capability: capability.manipulation.reach.v1

provides:
  app:
    contract: api.robot.application.control.v1

The application does not choose a vendor-specific controller. It declares the robot capabilities it needs, optionally constrains the platform compatibility labels, then consumes the platform through normal subsystem requires bindings. api.robot.application.control.v1 is not a robot capability. It is the standard operator/frontend control surface for an app subsystem: start, stop, and status. App-specific commands should use an app-specific public or internal API, or a managed package frontend endpoint. App-specific behavior files are implementation details; Librux does not require a scenario manifest.

Deployment Manifest

librux.deployment.yaml describes a desired runtime composition. It can be a partial subsystem composition, an app-less platform bring-up, or a full robot application deployment.

kind: librux.deployment
version: 1

robot: ./librux.robot.yaml
application: ./app/subsystem.yaml

instances:
  app.pick_place:
    package: ./packages/pick_place
    launch: managed
  compound.robot:
    package: ./packages/compound
    slots:
      compound: capabilities
    launch: managed
  gateway.arm:
    package: ./packages/sim_arm_gateway
    slots:
      arm_gateway: arm
    launch: managed

bindings:
  app.pick_place.capabilities:
    to: compound.robot.capabilities
  compound.robot.arm_gateway:
    to: gateway.arm.arm

Top-level fields.

Field	Required	Meaning
`kind`	yes	Must be `librux.deployment`.
`version`	yes	Deployment manifest schema version.
`robot`	no	Robot manifest. When present, platform slot and capability implementation validation is enabled.
`application`	no	App-role subsystem manifest selected as the top-level app. When present, `robot` must also be present and the app's platform label and capability requirements are checked.
`instances`	yes	Concrete subsystem instances to validate, launch, or observe. Application, component, gateway, and compound subsystems all appear here.
`bindings`	yes	Wiring from each required interface to the selected provider interface.

Deployment levels.

Level	`robot`	`application`	Meaning
Subsystem composition	absent	absent	Partial subsystem set for development, tutorial stages, or binding checks. It can launch packages and validate subsystem bindings, but it is not robot validation.
Platform bring-up	present	absent	App-less platform. Robot slots, slot contracts, capability implementations, and subsystem bindings are validated. This is useful for hardware or simulation bring-up before an app is attached.
Full robot application	present	present	One application is mapped onto one compatible platform. App requirements, robot slots, capabilities, instances, and bindings are all validated.

instances and top-level application intentionally have different jobs. An application subsystem must appear in instances when it should run. The top-level application field marks that same subsystem as the selected app for robot compatibility validation. Without the top-level field, a deployment can still launch a process named app.*, but Librux will not know that it should validate that app's robot requirements against the robot manifest.

Instance fields.

Field	Meaning
`manifest`	direct subsystem manifest path for validation-only or external instances
`package`	package directory containing `package.yaml`; required for managed `deploy up`
`slots`	mapping from robot slot name to the public provided interface name on this instance
`launch`	`managed`, `external`, or `federated`
`host`	optional host hint for federated deployments
`params`	string parameters for package or subsystem specialization

One subsystem instance can satisfy multiple robot slots when it provides multiple public Librux spec interfaces. For example, a physical gateway subsystem may fill actuator_gateway, digital_output_gateway, and perception_gateway by mapping them to actuator_servo, digital_io, and perception_query respectively.

Validation rules.

if application is present, robot must also be present
application must point at an app role subsystem
deployment must include the referenced application subsystem as an instance or subsystem
if robot is present, all required robot slots must be filled
if robot is present, non-app instances with slots must reference known robot slots
if robot is present, managed non-app robot instances must be assigned to a robot slot
if robot is present, instance role must match slot role
if robot is present, robot slot contracts must reference public Librux specs
if robot is present, each slots value must name a public interface on that instance, and that interface contract must match the robot slot contract
if application is present, application-required platform compatibility labels must be provided by the robot manifest when the app declares profiles constraints
if application is present, application-required capabilities must exist and match contracts
if robot is present, capability implementations reference deployed public interfaces and matching contracts
all required subsystem bindings must exist
binding source and target contracts must match

CLI

librux deploy validate ./librux.deployment.yaml
librux deploy plan ./librux.deployment.yaml
librux deploy plan ./librux.deployment.yaml --json
librux deploy up ./librux.deployment.yaml
librux deploy restart ./librux.deployment.yaml
librux deploy status ./librux.deployment.yaml
librux deploy down ./librux.deployment.yaml

validate prints a short success message. plan also prints the concrete instances, roles, slots, and launch modes. --json returns the same data in a machine-readable form for CI and release scripts.

up reconciles the desired deployment with the current runtime state.

missing managed instances are launched through librux-resourced
already active matching managed instances are kept
stale managed sessions are cleaned and relaunched
active managed instances are replaced only with --replace
external instances are checked but not started
federated instances are skipped by the local host

restart is the explicit replacement form of up --replace. It is useful when you want the deployment manifest to remain the source of truth but still force all active managed instances in that manifest through a stop, cleanup, and launch cycle.

down stops only managed instances owned by the local runtime. It does not terminate external or federated processes.