Skip to content
R2Kernel™ Runtime Kernel for Robotics 1.0.0rc10
R2Kernel™ Runtime Kernel for Robotics 1.0.0rc10

    Installation

    This page describes the published R2Kernel install flow. It focuses on getting the runtime and SDK onto a host. After installation, use Operate for service management, time sync, resource control, security, and validation.

    Supported Platforms

    R2Kernel runtime installation is Linux-only.

    Published runtime bundles currently target.

    • Linux x86_64
    • Linux aarch64

    The installed runtime uses Linux facilities such as systemd services, cgroup resource placement, Unix-domain local control channels, SocketCAN, device-node policy, and Linux time-sync tooling. macOS and Windows are useful for reading docs, preparing source trees, or editing SDK/tutorial code, but they are not runtime deployment targets.

    The documented commands assume Ubuntu / Debian. Other Linux distributions can work when equivalent packages and service facilities are available, but the published install path is validated first on Ubuntu / Debian.

    License Model

    The runtime binary payload is not Apache-2.0. Runtime installation requires manual acceptance of the R2Kernel runtime license/EULA during the installer review step. Automatic license acceptance is intentionally not supported.

    Public SDK source, tutorials, docs, and public spec payloads are distributed under the R2Kernel SDK open-source license group. Bundled third-party dependencies and declared SDK environment dependencies are disclosed under Open Source Notices.

    After installation, license and notice documents are stored under <prefix>/licenses (plural). This directory contains the files listed by the release manifest, typically including.

    • the R2Kernel download and installation data notice
    • the R2Kernel runtime license/EULA for runtime binaries and services
    • the Apache-2.0 license for public SDK/source payloads
    • Open Source Notices covering bundled third-party dependencies and declared SDK environment dependencies
    • third-party full license files, such as the yaml-cpp MIT license when the bundled Linux C++ SDK artifact is installed

    The presence of multiple files in <prefix>/licenses does not mean that the entire installed tree uses one license. It records the license and notice groups for the runtime, distribution logging notice, installed SDK artifacts, and open-source notices.

    Prerequisites

    On a minimal Ubuntu / Debian host.

    sudo apt update
sudo apt install -y ca-certificates curl wget python3 python3-venv

    Install python3-vcstool only when you plan to fetch the full matching source workspace through the entry repo's r2kernel.repos manifest.

    sudo apt install -y python3-vcstool

    The install snippets use curl by default. Equivalent wget -qO- ... | sh forms are also supported. Run the bootstrap script as the current user, not through sudo; it elevates only when needed, as described in Privileges And sudo.

    Current Release Install Command

    Use the install command from the published entry repository release page.

    INSTALL_URL="https://download.r2kernel.org/r2kernel/releases/1.0.0rc10/install.sh"
curl --proto '=https' --tlsv1.2 -fsSL "$INSTALL_URL" | sh

    Set INSTALL_URL in the shell where you run the later examples. Fetch the bootstrap over verified HTTPS; a checksum supplied by a script downloaded over HTTP cannot authenticate that script.

    Published release docs and entry-repository READMEs are stamped with the exact release asset URL during the release process. If you are preparing a different release channel, use that channel's entry-repository release page instead of copying a URL from another release.

    Download Endpoint

    The public install script is small. It downloads the platform-matching installer binary and the installer then resolves the runtime manifest through the R2Kernel distribution endpoint.

    In production, runtime artifacts are served through the R2Kernel distribution service. It records operational metadata such as install session ID, client IP, standard delivery-network request metadata, user agent, requested release and artifact, response status, requested artifact size (the stored size of the requested artifact, not bytes received), and failure reason. The distribution service is designed not to record HEAD requests.

    This data is used for artifact delivery, private artifact access, installation diagnostics, release adoption analysis, abuse investigation, and distribution reliability/security. The distribution endpoint does not collect application source code, subsystem payloads, runtime messages, robot data, host config files, shell history, or local files from the installing host. The complete notice is installed as DOWNLOAD-NOTICE-R2Kernel.txt under <prefix>/licenses and is included in the public source tree as DOWNLOAD_NOTICE.md.

    The current public install flow does not require a user install token. The installer may create an installation-session identifier so one installation attempt can be diagnosed consistently. For production installs, use the published install.sh without overriding its distribution settings.

    A distribution channel that does require an install token reads it from R2KERNEL_INSTALL_TOKEN or from a private file named by --install-token-file PATH (a regular file, mode 0600 or stricter, holding one token). The last --install-token-file (or deprecated --install-token) given takes precedence over R2KERNEL_INSTALL_TOKEN, and install.sh uses the same token for its own download of the installer. install.sh never puts the token on a command line: with a token configured, it requires curl 7.58 or later (the token is read from a private file and not sent to another host on a redirect); Wget is never used with a token, and no download is made without the token. An install token file that is not a private regular file holding one token stops install.sh before any download. --install-token TOKEN is deprecated because the process list exposes it.

    install.sh pins the SHA256 of the installer and of release-manifest.json and the release version; the installer refuses a manifest whose bytes or version differ. Release locations must be https://; R2KERNEL_ALLOW_PLAIN_HTTP=1 is an explicit opt-in for a trusted local mirror. Without that opt-in, curl in install.sh and the installer follow redirects only to https:// locations, and the installer follows at most 10. Without a token and without curl, install.sh downloads with Wget, which may follow a redirect to any location; the downloaded installer is still checked against the SHA256 pinned in install.sh.

    Interactive Install

    Default install.

    curl -fsSL "$INSTALL_URL" | sh

    The default install prefix is /opt/r2kernel. The rest of the documentation writes the selected install prefix as <prefix>; substitute your prefix in commands and paths. A relative --prefix (or R2KERNEL_PREFIX, or a prefix typed into the installer) is resolved against the current directory, and . and .. are resolved without following symbolic links; the installer uses that absolute path for the entry-point links, env.sh and service registration.

    The prefix must be a dedicated directory: /, /usr, /usr/local, /opt, home directories and world-writable or sticky directories are refused. An existing directory that is not empty is used only when it holds an earlier R2Kernel installation (its .r2kernel-prefix marker or an R2Kernel runtime); otherwise the installer stops and names the entries it found. In an R2Kernel prefix the installer replaces only what an earlier R2Kernel install created; a foreign bin, lib or other product entry stops installation with an error naming the path, and an existing prefix keeps its mode.

    Choose a development user prefix.

    curl -fsSL "$INSTALL_URL" | sh -s -- --prefix ~/.local/r2kernel

    When a TTY is available, the installer opens a terminal UI for license review, prefix selection, PATH integration, optional Console administrator login, and Linux system-service setup. Console login defaults OFF on a fresh installation; choosing New password (ON) always prompts for a masked password and confirmation and stores it before services start. For an existing valid configuration, choose Inherit (the default), OFF, or New password (ON). Inherit also applies to recovery installs where the configuration exists without a complete installation. Use the arrow keys or Space to select the displayed choice. Password and confirmation fields appear when New password (ON) is selected. That choice replaces only the installer-managed password; custom password sources require separate administration. Empty passwords are rejected; short passwords are allowed. OFF does not delete a password and changes only Console login. The existing API security setting is preserved. Inherit preserves the existing Console login profile. The separate Console Connection and Terminal step selects HTTP or Inherit for the connection and OFF or Inherit for Terminal. Each Inherit choice shows its current value and keeps that setting independently of administrator login. New installations use HTTP and Terminal OFF. In the wizard, system services default to Install only when the selected prefix can host root services (protected and, for a non-root run, existing); otherwise they default to Skip and Install is refused before anything is installed.

    Managed system-service installation starts the Console with HTTP. Terminal starts OFF. Reinstallation preserves existing Console HTTP/HTTPS and Terminal settings. Settings → Security → Console connection switches between HTTP and HTTPS (default HTTPS port 18443). Choose the device certificate and private key, generated uniquely on that device, or upload your own certificate and private key PEM files. User certificates must cover the current Console hostname or IP address. Save the connection settings, then choose Apply all saved settings (restart). Control restarts. After it restarts, choose Reconnect to Console to open the saved address when the protocol changes. The browser may require trust confirmation for a generated device certificate.

    The installer also asks for the Console port, using the current selected connection's port on an upgrade and HTTP port 18080 on a new installation. Existing explicitly configured ports are preserved, including legacy 8081/8443 and ui_port: 0 API sharing. The command-line option is --console-port PORT. Console connection settings provide the same port field for HTTP and HTTPS; switching the protocol recalls the saved port for that protocol. Save, apply the restart, then reconnect at the displayed new address. Port changes retain the saved certificate and private key.

    Only the selected Console protocol is served. HTTPS closes a separate HTTP Console listener. Shared product/API HTTP listeners keep their independent services and reject Console documents and management routes. The HTTPS management origin excludes installed product frontends, which retain their own authentication. HTTP and HTTPS Console sessions use separate cookies; sign in again after a connection change when Console login is ON. Product support URLs are optional.

    Settings → Terminal provides ON/OFF and optional session limits. Terminal uses HTTP/ws with an HTTP Console and HTTPS/wss with an HTTPS Console. There is no separate Terminal transport exception or risk acknowledgement. Save & apply Terminal closes existing Terminal sessions without restarting Control. Exact origins, listener admission, and OS account authentication remain enforced.

    The installer sets public runtime and SDK directories to 0755, public data files to 0644, and executable runtime files to 0755, so a restrictive shell umask does not prevent services from reading the installation. It also makes env.sh readable for users sourcing the installed environment. Reinstallation preserves existing configuration file contents, ownership and permissions. Private managed credential directories and password files remain protected; parent directories outside the selected installation prefix are not changed.

    Web Terminal provides local OS login in the environment running Control: the installed Linux host for a native installation, or the Pod container for a container deployment. It does not use or require an SSH server. The login broker uses the non-login (nologin) r2kernel service account; operators authenticate as an existing OS account. The installer does not create human OS accounts or change their passwords.

    Line-based prompt mode.

    curl -fsSL "$INSTALL_URL" | sh -s -- --no-tui

    Installer Options

    Every option that takes a value accepts both --option VALUE and --option=VALUE. Choices given as options, or as the R2KERNEL_* environment values listed by --help, are used as given; the TUI or line-based prompt asks only the remaining questions. Command-line options override environment values. Unknown options and missing values are errors.

    --prefix <path>
--existing-prefix overwrite|abort
--path-mode none|print|shell-rc
--shell-rc <path>
--system-services install|skip
--system-service-config <path>
--console-login on|off
--console-password-file <private-file>
--console-transport http|inherit
--terminal off|inherit
--console-port <port>
--install-token-file <private-file>
--no-tui
--non-interactive

    To see the installer's own list of options and environment values, pass --help through the bootstrap script.

    curl -fsSL "$INSTALL_URL" | sh -s -- --help

    --existing-prefix overwrite approves installing into an earlier R2Kernel prefix that already contains files; the installer then replaces only what an earlier R2Kernel install created. It does not make other non-empty directories usable: a non-empty directory without an R2Kernel installation is refused with or without the option. --existing-prefix abort stops at any non-empty prefix instead. Without the option, the installer asks.

    --non-interactive (alias --yes) never prompts. A decision that has no safe default is an error that names the option to pass, for example --existing-prefix overwrite|abort for a non-empty prefix. Services default to skip; --system-services install requires running as root. A release that requires license acceptance is refused, because license acceptance is manual only (see Manual License Review). Published runtime releases require acceptance of the runtime license, so install them with the TUI or --no-tui and preset the other choices with options.

    Privileges And sudo

    install.sh parses every argument and checks the prefix location with the downloaded and verified installer, as the invoking user, before any sudo prompt; invalid arguments fail without elevation. Checks that need the release, the prefix contents or root run after elevation, before anything is downloaded or installed. install.sh elevates only when the selected prefix is not writable by the current user or --system-services install is selected, and only when the prefix is protected (root-owned, not a symbolic link, not group/other writable):

    • a prefix in your home directory installs without sudo
    • system service registration needs a protected prefix such as the default prefix
    • an installer running as root refuses a prefix that is not protected; re-run install.sh with --prefix PATH for a user prefix
    • with --non-interactive, install.sh uses sudo -n, which fails instead of prompting for a password

    Through sudo, install.sh forwards exactly the installer's documented R2KERNEL_* environment values that are set, never the install token. It removes its temporary directory on exit or interruption and exits with the installer's status.

    Manual License Review

    Runtime license acceptance is manual only. Official runtime manifests require the installer to show the required license document and require you to accept the license in the TUI or line-based prompt (no acceptance record is written). The installer intentionally rejects automatic license acceptance flags, and --non-interactive refuses a release that requires license acceptance.

    Default manual flow.

    curl -fsSL "$INSTALL_URL" | sh

    Line-based manual prompt instead of the full-screen TUI.

    curl -fsSL "$INSTALL_URL" | sh -s -- --no-tui

    Product prefix and system services.

    curl -fsSL "$INSTALL_URL" | sh -s -- \
  --prefix <prefix> \
  --system-services install

    The Console options below are part of Installer Options.

    --console-login and --console-password-file select explicit Console setup. --console-transport and --terminal independently select the connection and Terminal policy. Omitting them preserves an existing value; a fresh install uses HTTP and Terminal OFF. Explicit http and off reset those settings without changing administrator credentials or API authentication. HTTPS and Terminal ON can be enabled in Settings after installation. --console-login on --console-password-file explicitly sets a new password, replacing an existing installer-managed credential when present. Supply a protected password input file, never a password in command arguments. For script compatibility only, --console-login on without a file retains an existing credential; without an existing credential, unattended installation requires the file and interactive setup prompts for a new password. This reuse behavior is not a separate interactive choice. With no flags, existing configuration is inherited and a fresh installation defaults OFF. When login remains OFF and no password exists, the first visitor can register a password later in Settings → Security without a setup code. Keep that initial Console on a trusted management surface.

    Service registration can also run as a separate step: install with --system-services skip, then register the services with the installed helper.

    curl -fsSL "$INSTALL_URL" | sh -s -- \
  --prefix <prefix> \
  --system-services skip

sudo <prefix>/bin/r2kernel system install --prefix <prefix> \
  --console-password-store <prefix>/var/lib/security

    Use a root-owned, service-readable prefix such as the default prefix for product deployments. User-home prefixes remain useful for development.

    Installed Layout

    The installer writes.

    • runtime payload under <prefix>/runtime
    • executables under <prefix>/runtime/bin
    • runtime libraries under <prefix>/runtime/lib
    • Web Console assets under <prefix>/runtime/frontend
    • public spec files under <prefix>/runtime/spec
    • runtime support tools under <prefix>/runtime/tools
    • C++ SDK under <prefix>/sdk/cpp
    • Python SDK wheel under <prefix>/sdk/python
    • guided tutorial source under <prefix>/tutorials
    • license and notice documents under <prefix>/licenses
    • service unit sources under <prefix>/systemd
    • runtime state, logs, and control service home under <prefix>/var
    • shell environment helper under <prefix>/env.sh
    • uninstaller under <prefix>/bin/r2kernel-uninstall

    Top-level entry points.

    • <prefix>/bin -> <prefix>/runtime/bin
    • <prefix>/spec -> <prefix>/runtime/spec
    • <prefix>/config.yaml -> <prefix>/runtime/config.yaml

    Source the environment helper before using installed SDK/runtime commands or tutorials.

    . <prefix>/env.sh

    This sets R2KERNEL_PREFIX, updates PATH, and configures spec/runtime library paths for the installed SDK.

    Loading this environment is a per-shell action. In the installer, choose whether to leave shell files unchanged, print the commands for manual use, or explicitly register automatic loading in your own shell profile. Automatic registration is optional; it is not needed for administrator configuration commands. sudo uses its own environment and does not inherit the PATH created by env.sh.

    For a protected system prefix such as the default prefix, Linux service registration also installs /usr/local/bin/r2kernel-config, pointing at that installation's actual configuration. It never overwrites an unrelated command. To edit system configuration, use:

    sudo /usr/local/bin/r2kernel-config

    On systems whose sudo search path includes /usr/local/bin, the shorter sudo r2kernel-config also works. No environment helper is required. User-home installations do not create this system-wide entry; use their local CLI instead. Runtime code and system-level configuration remain root-protected. Managed Linux service installation prepares a separate private Control settings store so the Web Console and CLI can save supported operational settings, including login and Terminal policy, without making the runtime directory writable. System-owned fields remain read-only in the GUI; use the administrator CLI for those changes. Existing base configuration, overrides, and credentials are preserved during updates. Saving configuration does not automatically restart services.

    Linux Services

    On Linux, the installer can register.

    • r2kernel-control.service
    • r2kernel-resourced.service
    • r2kernel-timesyncd.service
    • r2kernel-terminal-login.service
    • r2kernel-https-settings.service

    The control service runs without root privileges. The resource service, the time-sync supervisor, the Terminal login service and the HTTPS settings service run as root: they keep the narrow root authority needed for resource brokering, host-level clock management, local OS login and protected TLS material.

    The system service installer creates a r2kernel resource group by default. The control service and managed SDK package processes use that group for the local runtime boundary. Managed package launches preserve it as a supplementary group, so application code does not need to patch runtime ownership or permissions.

    Service unit files live under <prefix>/systemd. The installer links them from /etc/systemd/system so uninstall can remove the links and then the entries R2Kernel manages in the prefix. Runtime sockets use /run/r2kernel, owned by root:r2kernel with mode 3770 (group inheritance and sticky protection), and are recreated when services start. The SDK control plane uses /run/r2kernel/control.sock by default; managed launch paths pass the resolved path to application processes as R2KERNEL_CONTROL_SOCKET.

    After joining the runtime group, open a new login session before using its sockets from an existing shell. The installer supplies the IPC group to managed services and <prefix>/env.sh. Managed shared memory and Linux named semaphores use that exact group and mode 0660; direct execution without an IPC group uses owner-only 0600. Unknown owners or permissive legacy objects are rejected. Stop all legacy processes before inspecting, migrating, or recreating IPC: changing permissions cannot revoke descriptors that a process already opened. Only registered legacy shared-memory objects whose durable registry proves their exact inode and size may be restricted in place by root while preserving their inode. This migration does not apply to named semaphores. Semaphore creation publishes the exact secure permissions above; opening an existing semaphore (including create-if-present) requires it already to satisfy the owner, group, mode, size, regular-file, and single-link checks. Unknown 0666 semaphores are rejected without changing their identity or permissions, even when root requests creation. Inspect their origin and users explicitly after stopping processes, then remove and recreate them through secure creation; do not widen permissions or adopt a first-seen object as trusted. See Manager and Device Authorization.

    If service setup was skipped, run the exact command printed by the installer. For a new install using the default managed Console credential store:

    sudo <prefix>/bin/r2kernel system install --prefix <prefix> \
  --console-password-store <prefix>/var/lib/security

    For a dedicated config using that same newly prepared managed store:

    sudo <prefix>/bin/r2kernel system install \
  --prefix <prefix> \
  --config /path/to/config.yaml \
  --console-password-store <prefix>/var/lib/security

    The helper prepares the private Control settings and credential stores before starting services and verifies access as the non-root service user. The explicit credential-store option applies only to the installation's managed default store. It supports an empty store (Console OFF with later first registration), an installer-created password, and a verified legacy root-owned default store. For a supported legacy store, migration preserves credential contents and restricts ownership and permissions to the service user. Unexpected files, unsafe links, mixed ownership, or a custom credential location cause an explicit error rather than an automatic ownership change. Provision custom stores separately; a dedicated configuration pointing elsewhere cannot use the default-store command.

    For details, see Time Sync Operations and Resource Control.

    Uninstall

    To remove a product install.

    sudo <prefix>/bin/r2kernel-uninstall --prefix <prefix>

    To remove a prefix that you own as a non-root user, such as ~/.local/r2kernel installed with system services skipped, run the uninstaller as that user without sudo. When you own the prefix and the prefix path is not a symbolic link, the uninstaller does not elevate through sudo; --no-sudo declines elevation explicitly.

    <prefix>/bin/r2kernel-uninstall

    A user-owned prefix is removed only by its owner, and only when nobody else can change the path to it:

    • no directory on the path is a symbolic link;
    • each directory is owned by root or by you;
    • no directory is writable by another user. World-writable directories, including sticky ones such as /tmp, are refused. A group-writable directory is refused unless its group is your private group, meaning no other account holds that group. A directory with a POSIX access ACL (any entry beyond the owner, group and other permissions) is refused. NFSv4 ACLs are not inspected.

    The prefix must have no registered R2Kernel services. None of your processes may use it, and it must have no R2Kernel registry with registered pools or shared-memory objects that belong to you.

    Before changing anything, the uninstaller checks that you can remove every R2Kernel entry, and the prefix directory too when it would end up empty. A refusal therefore leaves the prefix unchanged.

    Root refuses a prefix that another user owns, also when the uninstaller elevated through sudo: that user could replace an entry with a symbolic link while root removes the tree. Rerun the command as the owner.

    Without root, the uninstaller cannot see the files of other users' processes or of non-dumpable processes. It checks those by command line only and reports how many there were.

    The uninstaller loads the protected same-prefix IPC policy itself; the command does not require sourcing env.sh under sudo or preserving ambient variables with sudo -E. It validates the actual protected resource-service unit's --config and resolved socket against <prefix>/etc/resource-service-identity.json. Service registration writes this identity; an existing supported installation without that file establishes it from its actual protected unit and effective config before stopping services. A divergent recorded identity, ambiguous command/environment, or unsafe config/override is refused before stopping. External --config files and explicitly configured custom sockets are supported: retirement selects their exact registry, never the default config's or an ambient environment's registry.

    The uninstaller stops declared dependent consumers before the core services, then rejects remaining processes using the prefix through executable, working directory, library mappings, file descriptors, or command arguments, even when they have no registered pool. Only the helper itself and its exact privileged sudo ancestor chain are excluded, not unrelated sudo or same-UID processes. It retires the selected registered resources before removing units or the prefix. A policy mismatch, live reference, or service-stop failure refuses cleanup and retains recovery metadata and units; some services may already be stopped. Correct the refusal and rerun, or restart the retained units to recover. External configs, unrelated registries, and global runtime directories are not deleted. Persistent external registry lock inodes and empty metadata remain; they are synchronization boundaries, not installation ownership records.

    Successful managed uninstall removes only the selected prefix's upgrade journal, under the same coordinator lock used for teardown. A live journal owner, unsafe journal, changed unit selection, or failed teardown preserves recovery state and refuses cleanup rather than erasing it. Journals for other prefixes remain intact.

    System accounts are kept by default. --remove-users considers only exact name/UID or name/GID identities recorded as created by this installation in its protected service-identity metadata, and only when no other installation, service, process or group membership still references them. Pre-existing, reassigned, shared and legacy unrecorded accounts are retained. A retained group also retains a same-named user when deleting it could implicitly delete that group. Optional account cleanup failure after successful prefix retirement exits with status 3 and names that partial outcome; it is not a successful account deletion or a rollback of prefix removal.

    The uninstaller requires the prefix's .r2kernel-prefix marker or an R2Kernel runtime and refuses the same shared system locations and home directories as the installer. It removes only what R2Kernel manages (runtime, its entry-point links, sdk, tutorials, licenses, var, systemd, env.sh, etc, management-tls and the marker); other entries, including foreign files in etc, are kept and listed, and the prefix directory is removed only when it is empty.

    An entry-point link is R2Kernel's when it names <prefix>/runtime/<name>. That holds in normal form, or through another spelling of the prefix directory such as a path through a symbolic link. It also holds for a dangling relative link of the form an earlier installer wrote for a relative --prefix. A prefix installed through a symbolic-link ancestor is therefore removed completely, from its physical path.

    For an installation made with system services skipped, removal is conservative: the prefix, whether root-owned and protected or owned by you as described above, must be unused, with no owned services, process references, or ambiguous or nonempty runtime state. For a user-owned prefix, only your own registries and shared-memory objects count; those of root and of other users are not this prefix's state. Valid empty registries alone are not live use. This path removes only R2Kernel's entries of that prefix, not unrelated global resources. A known managed installation with missing or unsafe policy metadata fails closed rather than being treated as an unused no-service installation.

    Use --dry-run for read-only observational preflight without stopping services, retiring pools, migrating permissions, creating registry state, or writing installation metadata. A root-owned prefix needs root for --dry-run as well; a user-owned prefix is dry-run by its owner without sudo. It inspects policy and unit/link ownership, actual config/override, registry structure/permissions and recorded pool identities, and prefix consumers outside the exact selected service cgroups. Missing registry state is reported as absent, not treated as an inspected empty file. Exclusive registry locking and final live-reference checks are explicitly deferred until managed services have stopped; a successful dry-run is not an assertion that final teardown will succeed. For exact registered legacy pools eligible for the existing protected migration, the observation names them and marks permission migration deferred; it does not report their current permissions as satisfying the installed policy.

    Managed inspection requires root to read protected registries and process state, including dry-runs. Unreadable or malformed state fails, rather than being reported as success. The launcher elevates through sudo when needed, including dry-runs, except for a prefix the caller owns; --no-sudo explicitly declines that elevation and does not relax safety checks. An unused no-service prefix retains its observational path without a blanket root requirement, but any unreadable safety dependency still refuses removal.

    Verification

    . <prefix>/env.sh
r2kernel --help
r2kernel status
r2kernel config --help
r2kernel package --help
r2kernel launch --help
r2kernel resource inventory
r2kernel timesync doctor --json

    If services were installed.

    sudo systemctl status r2kernel-control.service --no-pager
sudo systemctl status r2kernel-resourced.service --no-pager
sudo systemctl status r2kernel-timesyncd.service --no-pager
sudo systemctl status r2kernel-terminal-login.service --no-pager
sudo systemctl status r2kernel-https-settings.service --no-pager

    Interactive Linux installs default to system-service setup when systemd is available and the selected prefix can host root services. Noninteractive plans default to skipping services unless --system-services install is passed.

    When upgrading a prefix with registered Linux services, the installer stops systemd units that declare runtime dependencies, including application supervisors, before stopping Control and the resource service. It performs this shutdown before replacing runtime or SDK files. After installation, it verifies the resource socket and Control readiness, then restores the units that were active before the upgrade. Previously inactive units remain inactive; services registered for the first time are started. The standalone service installer uses the same sequence when replacing service definitions.

    Before stopping existing services, the installer verifies the selected SDK artifacts and prepares a versioned Python environment, including dependencies, wrapper imports and native-library compatibility. A failure at this preparation stage leaves the running installation and its selected Python environment in place. Dependency installation requires an accessible package index or a compatible local pip cache; the runtime bundle alone is not an offline dependency bundle.

    Preparation is serialized per Python environment store. A retry may rebuild an owned, protected, incomplete digest directory only when it is neither selected nor used by a live preparation. Completed environments are validated and reused; unsafe, selected, or live preparations are preserved and reported, not deleted. Do not remove a preparation lock file to force a concurrent installer through.

    Before changing client authority or stopping existing services, service registration preflights the protected installed policy, creator identities, configuration, key material, and cgroup root. Adding another client updates both the creator and resource-authority policies while retaining administrator grants.

    --system-services skip skips service registration, but still coordinates an upgrade of existing services belonging to the selected prefix. Fresh installs without registered services retain the usual skip behavior. Dependencies must be declared in systemd units; separately launched applications must be stopped before replacing the runtime. Another prefix's runtime services are left alone.

    If shutdown fails before file replacement, the installer attempts to restore the original active set and reports any recovery failure. If replacement or readiness fails, it keeps the affected services stopped and records the original active set in a protected journal under /run/r2kernel-upgrade. Re-run the installer with the same prefix to complete the interrupted installation and restore that set. Do not manually start services against a partially replaced runtime. Service-store preparation and the service helper's --dry-run do not stop services.

    A dangling registered-unit source is not repaired by creating an empty prefix or rerunning service registration: both reach the same protected-source check. Inspect the named unit with systemctl show UNIT -p FragmentPath -p SourcePath and restore its exact protected, matching source before retrying. The diagnostic names the unit, fragment/source and target; it is not an automatic reset facility.

    Installed SDK Payload

    The installer places SDK payloads under <prefix>/sdk, but it does not install the Python wheel into your active virtual environment. It also installs the guided tutorial source under <prefix>/tutorials, so normal tutorial use does not require a separate SDK source checkout.

    The installed service and CLI use the managed Python environment selected under <prefix>/sdk/python/current. Activating a separate shell virtual environment does not change the interpreter used by managed package processes. Packages that explicitly select another interpreter must provide their dependencies there. The installer also copies the supporting transport fixtures under <prefix>/runtime/tools/qa/fixtures, exposed through the installed tools alias.

    Linux C++ SDK release payloads bundle yaml-cpp internally, so installed-user C++ tutorial builds do not depend on a distro-specific libyaml-cpp.so.* at runtime.

    The reusable local Control transport requires matching runtime and SDK versions. When upgrading from the earlier inline/large-payload transport, update the runtime, Python environments, and SDK-linked subsystem binaries together, then restart those processes. A protocol mismatch is an error, not an automatic downgrade. Application API contracts and host-to-host TCP are unchanged.

    License Files

    The installer keeps release-manifest license and notice documents under <prefix>/licenses. Use this directory as the installed license record for the runtime EULA, public SDK/source notices, bundled third-party licenses, and the download/install data notice.

    Next Step

    Continue with Quickstart. Use Operate for host operation and Develop for SDK/tutorial workflows.