Skip to content
R2Kernel Runtime Kernel for Robotics v1.0.0rc1
R2Kernel Runtime Kernel for Robotics v1.0.0rc1

    Runtime Configuration

    R2Kernel is a configurable robotics runtime. Before choosing a CLI command or a browser tool, identify which part of the installed host you are configuring.

    The installed product prefix is usually.

    /opt/r2kernel

    The active runtime config is this.

    /opt/r2kernel/runtime/config.yaml

    The installer also provides a convenience entry point.

    /opt/r2kernel/config.yaml -> /opt/r2kernel/runtime/config.yaml

    r2kernel config set, r2kernel config unset, and r2kernel config tui write a sibling override file instead of rewriting the base file.

    /opt/r2kernel/runtime/config.override.yaml

    The running configuration is the base config.yaml plus that override file when it exists.

    Source the installed environment before using the installed tools.

    . /opt/r2kernel/env.sh

    Ways To Change Configuration

    Use one of these surfaces depending on where you are operating from.

    Surface Use
    r2kernel config tui interactive form for common settings
    r2kernel config get/set/unset scripted or SSH-based override changes by dotted key
    Web Console Settings browser-based editing and apply actions
    direct YAML editing site automation or reviewable base/override changes

    Examples.

    r2kernel config paths
r2kernel config print
r2kernel config get control.api_port
r2kernel config set product.name "Acme Robot Controller"
r2kernel config validate

    When you edit YAML directly, validate before restarting services.

    r2kernel config validate
sudo systemctl restart r2kernel-control.service

    Some settings are read only at service startup. Browser apply actions and CLI commands may tell you when a restart is required.

    Configuration Areas

    The common operator-facing areas are these.

    Area Representative keys What it controls
    Product identity product.name, product.vendor, product.support_url names shown to product-facing clients and the Web Console
    Host control control.api_host, control.api_port, control.advertise_host REST, WebSocket, Web Console, and peer reachability
    System frontend control.frontend.mode, control.frontend.root bundled Console, custom product shell, or headless API mode
    Package storage packages.install_dir, packages.additional_paths, packages.max_upload_bytes managed package storage, external package discovery, and upload limit
    Resource authority resource_service.mode managed resource lease behavior
    Web/API security security.enabled, security.network.allow_cidrs, security.api.*, security.web.* browser login, API auth, source-network gates, and sessions
    Federation federation.peers, federation.transport, federation.security.* cross-host peer list, Event forwarding, and federation security
    Time sync time_sync.enabled, time_sync.nic, time_sync.role, time_sync.leader_host clock readiness and managed time-sync behavior
    Control transport timed_exchange.* timed exchange relay and local payload policy
    Shared memory shm_manager.* event shared-memory pool sizing

    The installed default keeps the bundled Web Console enabled on port 8001. Before exposing a host beyond a trusted local network, configure Web/API security and source-network policy.

    Minimal Product Identity

    Product metadata is safe to change first because it affects display and API metadata, not the native runtime hot path.

    r2kernel config set product.name "Acme Robot Controller"
r2kernel config set product.vendor "Acme Robotics"
r2kernel config set product.support_url "https://support.example.com"

    Product-facing clients can read these values through Host Control status and capability APIs. The Web Console Settings page exposes the same fields.

    Host And Frontend Policy

    The control backend serves REST APIs, WebSocket facade endpoints, and the system frontend from the configured API host and port.

    control:
  api_host: "0.0.0.0"
  api_port: 8001
  frontend:
    mode: "bundled"   # bundled, custom, or disabled

    Use bundled for the R2Kernel Web Console. Use custom when a product should serve its own static operator UI from /. Use disabled for a headless host that exposes Host Control APIs without a system frontend.

    For the detailed product UI policy, see Product Frontend Modes.

    Security Before Exposure

    The default install is intentionally local/trusted-network oriented. Before binding the host to a reachable network, configure security.

    r2kernel config set security.enabled true
r2kernel config set security.api.require_auth true
r2kernel config set security.network.allow_cidrs '["127.0.0.1/32", "::1/128", "192.168.60.0/24"]'

    Store API tokens and web passwords in root-owned files or environment variables rather than inline YAML. See Web and API Security for the full pattern.

    Package And Runtime State

    Managed package state should stay inside the R2Kernel product prefix. Product installs use a writable package state location under the prefix so installed packages survive runtime replacement while remaining owned by the control service.

    Check the active value before changing it.

    r2kernel config get packages.install_dir

    Relative paths resolve beside the active config.yaml. Prefer absolute paths for site-specific product deployments when ambiguity would be risky.

    To make existing package trees available without copying them into the managed install directory, add package directories or package roots to packages.additional_paths.

    packages:
  install_dir: "/opt/r2kernel/var/lib/packages"
  additional_paths:
    - "/srv/robot-packages"
    - "../development/my-package"

    An entry may point directly to a directory containing package.yaml, or to a root whose immediate child directories contain package.yaml. Relative entries resolve beside the active config.yaml. R2Kernel validates and exposes these external packages through Runtime, including their frontend and contract specs, but never copies or deletes their source directories. Remove an external package by removing its entry from additional_paths and applying the configuration.

    Next Tools

    After the configuration model is clear.

    1. Use CLI Tools for SSH, automation, service checks, package lifecycle, and runtime diagnostics.
    2. Use Web Console Manual for browser-based operation on a host.
    3. Use Time Sync Operations, Web and API Security, Resource Control, and Deployment Checks for production-readiness checks.
    4. Use Product Frontend Modes when a product should replace or disable the bundled Web Console.