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

    Distribution And Licensing

    Librux uses a split distribution model.

    • Entry repository - installer bootstrap, source-checkout manifest, and release metadata.
    • SDK repository - public Python and C++ SDK source, public spec files, tutorials, benchmarks, tutorial support code, and C ABI headers required for C++ source builds.
    • Docs site - published documentation.
    • Download server - installer-consumed runtime and SDK binary artifacts.

    The runtime implementation is delivered through the installer. Public source repositories support SDK use, tutorials, integration, and review, but normal users install the runtime through the entry repository's installer command.

    The installer and release manifest describe which installable artifacts are installed, which license group each artifact belongs to, and whether explicit license acceptance is required.

    Runtime Payload

    Runtime payloads include the following.

    • control backend binaries
    • runtime support libraries
    • default runtime config
    • installed fallback specs
    • frontend assets
    • Linux service helpers
    • time-sync and resource companion tools

    Runtime installation requires acceptance of the Librux runtime license.

    Private Distribution Endpoint

    Runtime and installer binary artifacts are stored in a private object bucket. The bucket itself is not exposed to users. The installer talks to a distribution API that resolves the requested release and returns short-lived download URLs for the files referenced by the release manifest. Those URLs contain server-signed download tokens, but the current public install flow does not require a user-supplied install token.

    The expected production shape is this.

    install.sh
  -> GET /v1/artifact?version=<version>&file=<installer>
  -> librux-installer --distribution-url https://download.librux.org
       -> GET /v1/resolve?version=<version>&platform=linux&arch=<arch>
       -> GET <server-signed download URL>

    The distribution API logs download metadata such as request time, install session ID, client IP, CDN request metadata, user agent, release version, channel, platform, architecture, artifact name, response status, byte count, and failure reason. It does not require the R2/S3 object bucket to be public.

    install.sh creates a LIBRUX_INSTALL_ID when the caller does not provide one. The bootstrap artifact request, installer resolve request, and signed artifact downloads all carry that ID so a single installation attempt can be analyzed as one session.

    This logging is disclosed in the runtime EULA, in the installer license/notice review step, in DOWNLOAD_NOTICE.md, and in the installed <prefix>/licenses/DOWNLOAD-NOTICE-Librux.txt file. The distribution endpoint does not collect application source code, subsystem payloads, runtime messages, robot data, host configuration files, shell history, or files from the installing host.

    Public Source And SDK Payloads

    The public source payloads are split by role.

    • librux
    • installer bootstrap
    • librux.repos source-checkout manifest
    • release metadata
    • librux-sdk
    • Python SDK source
    • C++ SDK source
    • public spec files
    • runtime C ABI headers needed by the C++ SDK
    • tutorials
    • benchmark runners
    • tutorial support code
    • librux-docs
    • documentation source

    librux-demo is a separate robotics application demo repository. It is not prepared or published by the core librux-dev release pipeline.

    The Linux C++ SDK archive may bundle yaml-cpp as an internal static dependency when that artifact is built for installed-user tutorials. The corresponding MIT license is included with the release assets and installed under <prefix>/licenses, while the installer presents bundled and declared third-party disclosures through Open Source Notices.

    Source Checkout Manifest

    The entry repository carries a librux.repos manifest for source checkouts. This follows the robotics multi-repo pattern used by vcstool.

    repositories:
  librux-sdk:
    type: git
    url: http://git.librerobotics.org/justin.kang/librux-sdk.git
    version: v<version>
  librux-docs:
    type: git
    url: http://git.librerobotics.org/justin.kang/librux-docs.git
    version: v<version>

    The manifest is a source synchronization aid, not the runtime installer. Runtime installation still goes through the installer bootstrap.

    Release Manifest

    release-manifest.json is the install-time artifact map served by the download server or returned by the distribution API. Its JSON field is named components, but those entries are release artifacts, not Librux runtime subsystems.

    Important fields include the following.

    • release_version
    • release_tag
    • license_groups
    • publish_channels
    • components
    • install
    • install_bundles
    • repositories
    • download_base_url
    • distribution_url

    Each artifact entry records its artifact file, platform, license group, and delivery channel. Installers use this metadata to select the matching platform payload, show license information, install default SDK artifacts, and verify checksums.

    Example shape.

    {
  "schema_version": 3,
  "release_version": "<version>",
  "release_tag": "v<version>",
  "download_base_url": "https://download.librux.org/librux/releases/<version>",
  "distribution_url": "https://download.librux.org",
  "repositories": {
    "entry": {
      "url": "http://git.librerobotics.org/justin.kang/librux.git",
      "version": "v<version>"
    },
    "sdk": {
      "url": "http://git.librerobotics.org/justin.kang/librux-sdk.git",
      "version": "v<version>"
    },
    "docs": {
      "url": "http://git.librerobotics.org/justin.kang/librux-docs.git",
      "version": "v<version>"
    }
  },
  "license_groups": {
    "runtime": {
      "license_id": "LicenseRef-Librux-Runtime-Proprietary",
      "category": "proprietary",
      "acceptance_required": true
    },
    "sdk": {
      "license_id": "Apache-2.0",
      "category": "open-source",
      "acceptance_required": false
    },
    "download-privacy": {
      "license_id": "NoticeRef-Librux-Download-Data",
      "category": "privacy-notice",
      "acceptance_required": false
    },
    "open-source-notices": {
      "license_id": "NoticeRef-Librux-Open-Source",
      "category": "open-source-notice",
      "acceptance_required": false
    }
  },
  "components": [
    {
      "name": "runtime-linux-x86_64",
      "kind": "runtime-bundle",
      "publish_channel": "runtime-binary",
      "license_group": "runtime",
      "file": "librux-runtime-<version>-linux-x86_64.tar.gz",
      "required_by_default": true
    },
    {
      "name": "cpp-sdk-linux-x86_64",
      "kind": "cpp-sdk",
      "publish_channel": "sdk-binary",
      "license_group": "sdk",
      "file": "librux-client-cpp-<version>-linux-x86_64.tar.gz",
      "required_by_default": true
    }
  ]
}

    Installer Behavior

    The installer uses the manifest for these actions.

    • select the platform-matching runtime bundle
    • install the default Python and C++ SDK payloads
    • show the runtime license, download notice, Librux SDK license, and Open Source Notices
    • write <prefix>/env.sh
    • register Linux system services when requested
    • keep checksums and artifact metadata available for validation

    See Installation for the user-facing install flow.

    Release Automation

    The internal development workspace prepares the split distribution in two phases.

    Preparation.

    python3 tools/release/prepare_librux_release.py \
  --release-tag v<version> \
  --repo-base-url http://git.librerobotics.org/justin.kang

    This builds Linux artifacts, exports the public repository trees, writes the librux.repos manifest, and assembles the download-server release directory. Use --repo-base-url https://github.com/librerobotics for a GitHub publish, or pass the individual --entry-repo-url, --sdk-repo-url, and --docs-repo-url values when one repository needs a different origin.

    Publication.

    python3 tools/release/publish_librux_release.py \
  --release-root release/librux \
  --entry-repo-dir /path/to/librux \
  --sdk-repo-dir /path/to/librux-sdk \
  --docs-repo-dir /path/to/librux-docs \
  --distribution-r2-bucket librux-artifacts \
  --distribution-channel beta \
  --commit --tag --push \
  --create-entry-release --forge gitea \
  --server-url http://git.librerobotics.org \
  --entry-repo-slug justin.kang/librux \
  --token-env GITEA_TOKEN

    The publication step operates on already-prepared payloads. This keeps build verification separate from server and repository mutation.

    The Cloudflare Worker implementation and setup notes live under tools/distribution/cloudflare-worker. The R2 upload helper is tools/release/publish_distribution.py; publish_librux_release.py can call it directly when --distribution-r2-bucket is provided. Uploads target the remote R2 bucket by default; --local is only for local Wrangler storage tests.

    Download logs are summarized with this command.

    python3 tools/distribution/analyze_downloads.py \
  --wrangler tools/distribution/cloudflare-worker/node_modules/.bin/wrangler \
  --config tools/distribution/cloudflare-worker/wrangler.toml

    The report groups successful resolves, artifact downloads, failures, and install sessions from the D1 download_events table.