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

    Host Control REST API Guide

    The Host Control REST API is the HTTP API exposed by the control backend.

    Use it for operator tools, automation, monitoring, deployment checks, Web Console integration, package management, and configuration workflows. Do not use it from native subsystem hot paths. Subsystems should use the Subsystem SDK API.

    This page explains how to use the REST API. For the table-oriented route catalog, see Host Control REST Routes.

    Base Origin

    The API is served from the control backend origin.

    http://<host>:<control.api_port>

    The stable product-facing prefix is this.

    http://<host>:<control.api_port>/api/v1

    The /api/v1 prefix is required for Host Control REST and WebSocket routes. Unprefixed API routes were retired before the 1.0 release and return HTTP 404 instead of falling through to the system frontend.

    The same origin can also serve the bundled Web Console, a custom static product frontend, or no system frontend at all. Managed package frontend assets are separate from the system Console and are served under /api/v1/packages/<package-id>/ui/.

    Security

    When security is enabled, requests must pass two gates.

    • network admission through configured CIDR ranges
    • identity through a Web Console session cookie or API key

    External clients should send one of.

    Authorization: Bearer <api-key>

    X-Librux-API-Key: <api-key>

    Browser clients normally authenticate through /api/v1/auth/login and use the issued session cookie. See Web and API Security.

    Authenticated identities carry one of three standard roles.

    Role Intended use
    viewer read-only status, specs, events, and monitoring
    operator viewer access plus runtime operation such as Control WebSocket and app start/stop
    admin operator access plus config, package installation/removal, security, and service apply actions

    Health And Readiness

    Method Path Purpose
    GET /api/v1/health Lightweight process health and shared-memory manager connectivity
    GET /api/v1/ready Runtime readiness with HTTP 200 when accepted and 503 when not ready

    /api/v1/health and /api/v1/ready may be unauthenticated when security.health.unauthenticated=true. Network admission still applies.

    Runtime Status

    /api/v1/control/status is the main operator snapshot. It includes subsystem inventory, Event runtime state, timed exchange runtime state, federation state, time-sync state, resource state, managed package instances, and WebSocket bridge health.

    managed_instances is keyed by active resource lease ID. Each value identifies the installed package and instance that owns that lease, plus its instance UI route when a frontend is available. Stopped instances are omitted. Runtime clients can therefore resolve managed actions from the same live snapshot as subsystem_status without polling the package catalog separately.

    {
  "managed_instances": {
    "package-instance-lease-id": {
      "package_id": "vendor.package",
      "package_name": "Vendor Package",
      "instance_id": "robot.instance",
      "frontend": {
        "available": true,
        "url": "/api/v1/packages/vendor.package/ui/?instance=robot.instance&context=/api/v1/packages/vendor.package/instances/robot.instance/context"
      }
    }
  }
}

    Use /api/v1/control/specs when building a spec dictionary browser, and /api/v1/control/bindings when inspecting or changing runtime binding overrides. Every product-facing API route is available under /api/v1, for example /api/v1/control/status and /api/v1/control/bindings.

    For the full table, see Host Control REST Routes.

    Subsystem Lifecycle

    Request body example.

    {
  "transition": "pause",
  "reason": "operator request",
  "session_id": "optional-current-session-id"
}

    Valid transition names are start, pause, resume, stop, reset, fault, and degrade. The endpoint validates the current subsystem lifecycle state, session activity, and notify endpoint before accepting the request. Completion is observed through /api/v1/control/status or Runtime Graph after the next subsystem heartbeat.

    Managed process action request body example.

    {
  "action": "terminate",
  "session_id": "optional-current-session-id"
}

    Valid process actions are terminate and kill. They require the subsystem to have a managed resource lease. terminate sends SIGTERM with a grace window and may escalate to SIGKILL; kill sends SIGKILL immediately.

    For the full route table, see Host Control REST Routes.

    Configuration

    Prefer /api/v1/control/config/fields for ordinary UI or automation changes. Use raw override YAML only for advanced fields that do not yet have a structured form. Configuration writes require an admin identity when security is enabled.

    /api/v1/control/runtime/apply is the safe apply path for managed runtime changes. OS policy changes, unmanaged subsystem processes, and low-level device policy may still require manual service restart or host reboot.

    For the full route table, see Host Control REST Routes.

    Security Management

    API key secret values are returned once at creation time and are hidden afterwards. Security management requires an admin identity when security is enabled.

    For the full route table, see Host Control REST Routes.

    Managed Packages

    Managed package endpoints operate on installable packages. A package declares one subsystem entrypoint, its role, frontend assets, environment, package parameters, and resource claims in package.yaml. Packages may contain role: gateway, role: component, role: compound, or role: app subsystems. role: app means an application subsystem. It is not the install unit name.

    POST /api/v1/control/packages/install accepts the archive fields filename, content_base64, and replace. Installation registers one package record by package name. POST /api/v1/control/packages/{package_id}/start may include instance_id, params, and runtime_dir to create a concrete runtime instance from that installed package. If instance_id is omitted, the package id is used. Starting fails when the same instance id is already running. Starting with a different instance id creates another managed runtime instance, subject to resource-policy conflicts. stop and restart accept instance_id to target a specific instance. A stopped, terminated, or killed runtime instance is removed from the active package-instance registry. Reusing its instance id on a later start creates a new active instance with that id. Package installation/removal requires admin. Lifecycle operations require operator or admin when security is enabled.

    For the full route table, see Host Control REST Routes.

    Package Frontend Assets

    The /ui/ paths are static frontend delivery paths. Instance-scoped context and proxy paths are for browser GUI communication. They are not native subsystem transport APIs and should be backed by frontend.context.api or frontend.context.ws in the installed package manifest. During launch, those context endpoints become managed loopback listener grants. The package backend opens the listener through the resource broker; the browser only calls the same-origin proxy path.

    For product frontends, configure control.frontend.mode=custom and point control.frontend.root at the static SPA bundle. For headless/API-only hosts, use control.frontend.mode=disabled.

    For the full route table, see Host Control REST Routes.

    Stability Rule

    Treat these REST routes as host-control and operator integration APIs. Internal UDP messages, shared-memory layout, relay sockets, and codec FFI names are not part of this REST API surface.