Skip to content
Librux Runtime Kernel for Robotics development
Librux Runtime Kernel for Robotics development

    CLI / Entry Points

    The stable user-facing command is librux. Installed runtimes also ship lbx as a short alias for the same command. After sourcing <prefix>/env.sh, <prefix>/bin is added to PATH, and operators should prefer the unified command form unless a guide explicitly calls out a lower-level binary.

    Read Runtime Configuration first when you need to understand what a command changes in config.yaml. This page focuses on the CLI entry points used to inspect, change, and operate an installed host.

    . <prefix>/env.sh
librux --help
lbx --help

    Every command on this page can be typed with either name.

    librux deploy status ./robot.deployment.yaml
lbx deploy status ./robot.deployment.yaml

    Product deployments normally manage daemons through systemd. Development workflows can start the same daemons directly through librux control or the lower-level binaries described below.

    Operator Commands

    Command Dispatches to Purpose
    librux status / lbx status librux-doctor show installed runtime status and diagnostics
    librux control [args] librux-control run the host control backend directly
    librux serve [args] librux-control alias for librux control
    librux config ... librux-config inspect or edit runtime configuration
    librux package ... librux-package validate or build managed packages
    librux launch ... librux-launch start, restart, stop, and inspect managed package leases
    librux deploy ... built in validate, plan, start, restart, stop, or inspect robot application deployments
    librux subsystem ... librux-subsystem inspect registered subsystem sessions and clean stale state
    librux resource status librux-launch list list active and recently reaped resource leases
    librux resource inventory librux-launch inventory show CPU, NIC, link-layer, CAN, and device inventory
    librux resource stop <lease> librux-launch stop <lease> stop a managed lease and terminate its process scope
    librux timesync doctor librux-timesync-doctor check time-sync readiness
    librux timesync run ... librux-timesync run a manual time-sync helper path
    librux timesync daemon ... librux-timesyncd run the managed time-sync companion directly
    librux system ... systemctl / journalctl operate Librux systemd units

    Common tutorials.

    . <prefix>/env.sh
librux --help
librux status
librux config --help
librux package --help
librux launch --help
librux deploy validate tutorials/deployments/teleop.deployment.yaml
librux subsystem status
librux resource inventory
librux timesync doctor
librux system status

    Configuration values can be inspected and overridden by key path.

    librux config get timed_exchange.inline_payload_threshold
librux config set timed_exchange.inline_payload_threshold 65536

    The same key-path model applies to product shell and security settings.

    librux config set product.name "Acme Robot Controller"
librux config set product.vendor "Acme Robotics"
librux config set control.frontend.mode custom
librux config set control.frontend.root /opt/acme/ui/dist
librux config set federation.security.mode required
librux config set federation.security.key_id robot-cell-a
librux config set federation.security.key_file /opt/librux/var/lib/security/federation.key

    Use librux config tui for the common settings form, or use librux config set for any supported dotted key. Secret material should usually live in root-owned files or environment variables rather than inline YAML.

    Deployment Commands

    Use deployment commands before publishing robot tutorials or product deployment manifests.

    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 checks the level declared by the manifest. A manifest with only instances and bindings is a subsystem composition. A manifest with robot adds robot slot and capability validation. A manifest with both robot and application also checks the selected app-role subsystem against required capabilities and optional platform compatibility labels from the profiles manifest field. plan prints the concrete instances and launch modes after validation succeeds.

    up reconciles missing or stale managed instances and keeps active matching instances by default. restart is the explicit replacement path; it stops active managed instances, cleans their runtime session state, and launches the desired state again.

    Lower-Level Runtime Tools

    The installed bundle also ships the individual tools used by librux. These are useful for scripts, debug sessions, and direct daemon launches.

    • librux-control - host control backend. Product installs usually run it as librux-control.service; development installs can run it directly with librux control --config "$LIBRUX_PREFIX/config.yaml".
    • librux-config - runtime config editor and get / set / unset helper.
    • librux-package - package validate and build.
    • librux-launch - managed package run, restart, inventory, list, status, and stop.
    • librux-subsystem - registered subsystem status, sessions, doctor, lifecycle transition requests, runtime bindings, and stale-state cleanup.
    • librux-doctor - aggregate runtime diagnostics.
    • librux-timesync - explicit Linux PTP/time-sync helper launcher.
    • librux-timesyncd - managed time-sync companion used by time_sync.management_mode=managed.
    • librux-timesync-doctor - focused time-sync readiness doctor.
    • librux-resourced - privileged resource companion for managed package leases, brokered resource FDs, affinity, cgroup placement, and cleanup.

    Linux installs additionally provide shell helpers.

    • librux-timesync-install - install linuxptp / ethtool prerequisites.
    • librux-device-policy-install - install Librux udev serial/USB device-node policy.
    • librux-system-service-install - register librux-control.service, librux-resourced.service, and librux-timesyncd.service.

    Direct Development Launch

    For a development install under a user prefix, keep the control backend in a separate terminal.

    . /opt/librux/env.sh
librux control --config "$LIBRUX_PREFIX/config.yaml"

    For product prefixes, prefer the system service.

    sudo systemctl status librux-control.service --no-pager

    librux dev control, librux dev resourced, and librux dev timesyncd are developer conveniences for starting one daemon directly. librux dev all is intentionally not implicit; start daemons in separate terminals when debugging their logs.

    Use librux launch run <package> --bind requirement=provider.interface when you want to start one managed subsystem package and wire its required interfaces without creating a full deployment. librux deploy up is the command for reconciling a complete robot and application composition. Launch bindings validate the local requirement name and target shape; deployment manifests validate the complete provider contract graph.

    Use librux launch restart <package> ... during iterative development when the same package instance is already running or stale. It uses the same --instance, --bind, --set, and --runtime-dir arguments as run, but the process is always relaunched through the managed detached path.

    If you start a subsystem without a required binding during development, it can remain registered in WaitingBinding instead of failing at process start. Use Runtime Graph in the Web Console, or the subsystem binding commands, to bind it after both sides are visible.

    librux subsystem bindings
librux subsystem bind app.cleaner.teleop.mobility compound.cleaner.mobility
librux subsystem bind app.cleaner.teleop.trash_disposal compound.cleaner.trash_disposal
librux subsystem unbind app.cleaner.teleop.mobility

    Runtime bindings override launch bindings for the running control backend. They are intended for interactive development and operator repair; keep deployment manifests as the reviewable source for product compositions.

    librux launch run prints a concise launch summary by default. Add --json when a script needs the full resource-service response, lease details, or machine-readable logs.

    Subsystem Sessions

    Subsystem processes do not need to be launched by a special development launcher. A Python or C++ subsystem can be started from its normal main, script, IDE, debugger, or test harness. The SDK registers a per-process session with the local control backend when the subsystem comes up.

    For a repeated development cycle, the backend treats the subsystem name and session identity together.

    • the same live session can refresh its own status
    • a stale or dead previous session with the same subsystem name can be replaced
    • a different session with the same subsystem name is rejected while the previous session is still active
    • late shutdown messages from an old session cannot remove the current session

    Use the subsystem commands to inspect or repair runtime state.

    librux subsystem status
librux subsystem status arm_controller
librux subsystem sessions --json
librux subsystem doctor arm_controller
librux subsystem bindings arm_controller
librux subsystem bind arm_controller.motion mobile_base.motion
librux subsystem unbind arm_controller.motion
librux subsystem pause arm_controller
librux subsystem resume arm_controller
librux subsystem reset arm_controller
librux subsystem fault arm_controller --reason "encoder timeout"
librux subsystem terminate arm_controller
librux subsystem kill arm_controller
librux subsystem cleanup arm_controller --stale
librux subsystem cleanup arm_controller --force

    Lifecycle commands are requests. The runtime validates the current state and delivers the request to the subsystem SDK hook through the registered notify endpoint. Watch librux subsystem status <name> or Runtime Graph for completion.

    terminate and kill are managed process actions, not lifecycle transitions. They require a resource lease from librux-resourced. terminate gives the process scope a SIGTERM grace window before escalation; kill sends SIGKILL immediately.

    cleanup --stale is the default-safe path and only removes inactive state. cleanup --force is for operator intervention when the current runtime view is known to be wrong.

    Version Provenance

    Installed runtime CLIs read the package version from the bundled release-manifest.json when available. Use --version on librux, librux-control, librux-config, librux-package, librux-launch, librux-subsystem, librux-doctor, librux-timesync, librux-timesyncd, librux-timesync-doctor, and librux-resourced when collecting runtime provenance. Source-tree builds without a release manifest may report the underlying package version instead.

    Source-Tree Helpers

    Source checkouts may include helper scripts for building or inspecting the tree. Those helpers are separate from the installed runtime CLIs listed above.