Spaces:

OpenRAL
/

README

Running

File size: 21,398 Bytes

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>OpenRAL: Runtime for VLA Robot Agents</title>
  <style>
    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }

    :root {
      --black: #0f0f0f;
      --off-white: #f8f7f4;
      --mid: #6b6b6b;
      --border: #e0ddd8;
      --accent: #1a1a1a;
      --code-bg: #f1f0ed;
      --green: #16a34a;
      --yellow: #ca8a04;
      --red: #dc2626;
    }

    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
      background: var(--off-white);
      color: var(--black);
      line-height: 1.6;
      font-size: 15px;
    }

    a { color: var(--black); text-underline-offset: 3px; }
    a:hover { opacity: 0.65; }

    /* ── Layout ── */
    .page { max-width: 860px; margin: 0 auto; padding: 48px 24px 80px; }

    /* ── Header ── */
    .header {
      display: flex;
      align-items: center;
      gap: 20px;
      margin-bottom: 32px;
      padding-bottom: 32px;
      border-bottom: 1px solid var(--border);
    }
    .header img { width: 56px; height: auto; flex-shrink: 0; }
    .header-text h1 { font-size: 28px; font-weight: 700; letter-spacing: -0.5px; }
    .header-text p { color: var(--mid); margin-top: 4px; font-size: 15px; max-width: 580px; }

    /* ── Badges ── */
    .badges { display: flex; flex-wrap: wrap; gap: 8px; margin: 20px 0 32px; }
    .badge {
      display: inline-flex;
      align-items: center;
      gap: 5px;
      padding: 4px 10px;
      border: 1px solid var(--border);
      border-radius: 20px;
      font-size: 12px;
      font-weight: 500;
      text-decoration: none;
      color: var(--black);
      background: white;
      white-space: nowrap;
    }
    .badge:hover { background: var(--code-bg); opacity: 1; }

    /* ── Sections ── */
    h2 { font-size: 18px; font-weight: 700; margin: 40px 0 16px; letter-spacing: -0.3px; }
    h3 { font-size: 14px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.5px; color: var(--mid); margin: 28px 0 12px; }
    p { margin-bottom: 12px; color: #2a2a2a; }

    /* ── Pitch block ── */
    .pitch {
      background: white;
      border: 1px solid var(--border);
      border-radius: 10px;
      padding: 24px;
      margin-bottom: 32px;
    }
    .pitch ul { padding-left: 20px; }
    .pitch li { margin-bottom: 8px; }
    .pitch li strong { font-weight: 600; }

    /* ── Code block ── */
    pre {
      background: var(--code-bg);
      border: 1px solid var(--border);
      border-radius: 8px;
      padding: 16px 20px;
      font-family: "SF Mono", "Fira Code", "Cascadia Code", monospace;
      font-size: 13px;
      line-height: 1.65;
      overflow-x: auto;
      margin-bottom: 24px;
    }
    code { font-family: inherit; }
    p code, li code, td code {
      background: var(--code-bg);
      border: 1px solid var(--border);
      border-radius: 4px;
      padding: 1px 5px;
      font-size: 12.5px;
    }

    /* ── Tables ── */
    .table-wrap { overflow-x: auto; margin-bottom: 24px; }
    table { width: 100%; border-collapse: collapse; font-size: 13.5px; }
    th {
      text-align: left;
      padding: 8px 12px;
      border-bottom: 2px solid var(--border);
      font-weight: 600;
      color: var(--mid);
      font-size: 12px;
      text-transform: uppercase;
      letter-spacing: 0.4px;
    }
    td { padding: 9px 12px; border-bottom: 1px solid var(--border); vertical-align: top; }
    tr:last-child td { border-bottom: none; }
    tr:hover td { background: #faf9f6; }

    /* ── License dot ── */
    .lic { display: inline-block; width: 8px; height: 8px; border-radius: 50%; margin-right: 4px; vertical-align: middle; }
    .lic-green { background: var(--green); }
    .lic-yellow { background: var(--yellow); }
    .lic-red { background: var(--red); }

    /* ── Robot grid ── */
    .robot-group { margin-bottom: 20px; }
    .robot-group h3 { margin-top: 0; }
    .robot-chips { display: flex; flex-wrap: wrap; gap: 6px; }
    .chip {
      padding: 4px 10px;
      border-radius: 16px;
      font-size: 12.5px;
      font-weight: 500;
      border: 1px solid var(--border);
      background: white;
    }
    .chip-green { border-color: #86efac; background: #f0fdf4; }
    .chip-blue { border-color: #93c5fd; background: #eff6ff; }
    .chip-gray { background: var(--code-bg); }

    /* ── Footer ── */
    .footer {
      margin-top: 56px;
      padding-top: 24px;
      border-top: 1px solid var(--border);
      display: flex;
      flex-wrap: wrap;
      gap: 20px;
      font-size: 13px;
      color: var(--mid);
    }
    .footer a { color: var(--mid); }

    @media (max-width: 600px) {
      .header { flex-direction: column; align-items: flex-start; gap: 12px; }
    }
  </style>
</head>
<body>
<div class="page">

  <!-- Header -->
  <div class="header">
    <img src="/spaces/OpenRAL/README/resolve/main/openral-logo.svg" alt="OpenRAL logo" />
    <div class="header-text">
      <h1>OpenRAL</h1>
      <p>An open-source operating layer for embodied AI, OpenRAL unifies fast policies, slow reasoning, and classical control into one typed, traceable, safety-first runtime for deployable robot agents.</p>
    </div>
  </div>

  <!-- Badges -->
  <div class="badges">
    <a class="badge" href="https://github.com/OpenRAL/openral">⬛ GitHub</a>
    <a class="badge" href="https://openral.github.io/openral/">📄 Docs</a>
    <a class="badge" href="https://discord.gg/3paXT2bVyB">💬 Discord</a>
    <span class="badge">Apache-2.0</span>
    <span class="badge">ROS 2 Jazzy</span>
    <span class="badge">Python 3.12</span>
    <span class="badge">lerobot 0.6.0</span>
  </div>

  <!-- What is it -->
  <div class="pitch">
    <p>A VLA model alone can't run on your robot. It needs a camera pipeline, an observation normaliser, an action de-normaliser, a safety wrapper, a replanning layer when it fails, and a way to log everything for later fine-tuning. <strong>OpenRAL is that infrastructure.</strong></p>
    <br/>
    <ul>
      <li><strong>Typed runtime</strong>: eight well-defined layers connected by Pydantic v2 contracts. No magic globals, no hidden retries.</li>
      <li><strong>rSkill format</strong>: Hub repos containing weights, a <code>rskill.yaml</code> manifest, quantisation hints, latency budgets, and reproducible <code>eval/</code>. Install like a model.</li>
      <li><strong>Dual-system planning</strong>: a fast visuomotor policy (S1, 30–200 Hz) and a slow LLM planner (S2) emitting typed tool-calls. Replanning is bounded and explicit.</li>
      <li><strong>Safety kernel</strong>: deny-by-default, Python proposes, C++ disposes. <code>ROSSafetyViolation</code> is never silently caught.</li>
    </ul>
  </div>

  <!-- Quick start -->
  <h2>Get started</h2>
  <pre><code># Install (no clone needed)
curl -fsSL https://raw.githubusercontent.com/OpenRAL/openral/master/scripts/install.sh | bash
openral doctor

# Browse and install a skill
openral rskill list
openral rskill install OpenRAL/rskill-smolvla-libero

# Run a simulated rollout
just sim-libero

# Deploy to hardware
openral deploy run --config deployments/so100_pickplace.yaml</code></pre>

  <!-- rSkills -->
  <h2>Policy rSkills</h2>
  <p>Each rSkill is a self-contained Hub repo: <code>rskill.yaml</code> manifest, <code>model.safetensors</code> weights, <code>eval/</code> results, and a model card with runnable examples. Install with <code>openral rskill install OpenRAL/rskill-&lt;name&gt;</code>. The table below shows a representative subset of the 19 VLA policy rSkills; classical motion planners ship as separate <code>ros_action</code> rSkills (see below).</p>

  <div class="table-wrap">
    <table>
      <thead><tr><th>rSkill</th><th>Backbone</th><th>Target robot</th><th>License</th></tr></thead>
      <tbody>
        <tr>
          <td><code>rskill-smolvla-libero</code></td>
          <td>SmolVLA</td><td>Franka Panda</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-smolvla-metaworld</code></td>
          <td>SmolVLA</td><td>Rethink Sawyer</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-smolvla-maniskill-franka</code></td>
          <td>SmolVLA × ManiSkill3</td><td>Franka Panda</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-xvla-libero</code></td>
          <td>xVLA (Florence-2)</td><td>Franka Panda</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-act-libero</code></td>
          <td>ACT</td><td>Franka Panda</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-act-aloha</code></td>
          <td>ACT</td><td>ALOHA bimanual</td>
          <td><span class="lic lic-green"></span>MIT</td>
        </tr>
        <tr>
          <td><code>rskill-act-aloha-insertion</code></td>
          <td>ACT (peg insertion)</td><td>ALOHA bimanual</td>
          <td><span class="lic lic-green"></span>MIT</td>
        </tr>
        <tr>
          <td><code>rskill-diffusion-pusht</code></td>
          <td>Diffusion Policy</td><td>PushT 2-D</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-molmoact2-libero-nf4</code></td>
          <td>MolmoAct2 NF4 (~5.5 B)</td><td>Franka Panda</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-molmoact2-so101-nf4</code></td>
          <td>MolmoAct2 NF4</td><td>SO-101</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-smolvla-robotwin</code></td>
          <td>SmolVLA × RoboTwin 2.0</td><td>ALOHA AgileX (dual-arm)</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-smolvla-so101-pick-place-pen</code></td>
          <td>SmolVLA</td><td>SO-101</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-3d-diffuser-actor-rlbench</code></td>
          <td>3D Diffuser Actor</td><td>Franka Panda (RLBench)</td>
          <td><span class="lic lic-green"></span>MIT</td>
        </tr>
        <tr>
          <td><code>rskill-rldx1-ft-rc365-nf4</code></td>
          <td>RLDX-1 (RoboCasa 365)</td><td>Panda Mobile</td>
          <td><span class="lic lic-red"></span>RLWRLD non-commercial</td>
        </tr>
        <tr>
          <td><code>rskill-rldx1-ft-libero-nf4</code></td>
          <td>RLDX-1 fine-tuned</td><td>Franka Panda</td>
          <td><span class="lic lic-red"></span>RLWRLD non-commercial</td>
        </tr>
        <tr>
          <td><code>rskill-rldx1-ft-gr1-nf4</code></td>
          <td>RLDX-1 (GR1 bimanual)</td><td>Fourier GR1</td>
          <td><span class="lic lic-red"></span>RLWRLD non-commercial</td>
        </tr>
        <tr>
          <td><code>rskill-rldx1-ft-simpler-widowx-nf4</code></td>
          <td>RLDX-1 (SimplerEnv)</td><td>WidowX</td>
          <td><span class="lic lic-red"></span>RLWRLD non-commercial</td>
        </tr>
        <tr>
          <td><code>rskill-gr00t-n17-libero</code></td>
          <td>GR00T N1.7</td><td>Franka Panda</td>
          <td><span class="lic lic-green"></span>NVIDIA Open Model</td>
        </tr>
        <tr>
          <td><code>rskill-openvla-oft-simpler-widowx-nf4</code></td>
          <td>OpenVLA-OFT NF4 (RLinf PPO, ManiSkill3)</td><td>WidowX</td>
          <td><span class="lic lic-green"></span>MIT</td>
        </tr>
      </tbody>
    </table>
  </div>

  <h2>ROS-action rSkills</h2>
  <p><code>kind: ros_action</code>. Classical motion planners packaged as rSkills, so the S2 reasoner dispatches a MoveIt or Nav2 motion exactly like a learned policy (this is the "VLA <em>and</em> classical controllers" thesis). No weights; they wrap a ROS 2 action server.</p>
  <div class="table-wrap">
    <table>
      <thead><tr><th>rSkill</th><th>Planner</th><th>What it does</th><th>License</th></tr></thead>
      <tbody>
        <tr>
          <td><code>rskill-moveit-eef-pose</code></td>
          <td>MoveIt MoveGroup</td><td>Collision-free motion to a 6-DOF Cartesian end-effector pose (e.g. a pre-grasp)</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-moveit-joints</code></td>
          <td>MoveIt MoveGroup</td><td>Collision-free motion to a target joint configuration (e.g. a policy's in-distribution start pose)</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-moveit-look-at</code></td>
          <td>MoveIt MoveGroup</td><td>Aim a wrist-mounted camera at a 3-D point so a later perception query / grasp sees the object framed</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-nav2-navigate-to-pose</code></td>
          <td>Nav2 NavigateToPose</td><td>Drive a mobile base to an absolute (<code>map</code>) or relative (<code>base_link</code>) goal pose</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
      </tbody>
    </table>
  </div>

  <h2>Perception detector rSkills</h2>
  <p><code>kind: detector</code>. Emit <code>ObjectsMetadata</code> (2D detections lifted to 3D via depth) rather than an <code>Action</code>. Plug directly into the <code>openral deploy</code> graph and fold into World State.</p>
  <div class="table-wrap">
    <table>
      <thead><tr><th>rSkill</th><th>Backbone</th><th>Notes</th><th>License</th></tr></thead>
      <tbody>
        <tr>
          <td><code>rskill-rtdetr-coco-r18</code></td>
          <td>RT-DETR R18</td><td>Lightweight ONNX</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-rtdetr-v2-r50vd</code></td>
          <td>RT-DETR v2 R50vd</td><td>Higher accuracy</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-omdet-turbo-indoor</code></td>
          <td>OmDet-Turbo (Swin-tiny)</td><td>Real-time open-vocab; ~230-class indoor vocabulary, unprompted background producer</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-omdet-turbo-locator</code></td>
          <td>OmDet-Turbo (Swin-tiny)</td><td>On-demand <code>locate_in_view</code>: lightweight in-process "find X"</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-locateanything-3b-nf4</code></td>
          <td>LocateAnything-3B</td><td>Open vocabulary (out-of-process NF4 sidecar)</td>
          <td><span class="lic lic-red"></span>NVIDIA non-commercial</td>
        </tr>
      </tbody>
    </table>
  </div>

  <h2>Scene-understanding VLM rSkill</h2>
  <p><code>kind: vlm</code>. A scene VLM that answers open-ended questions about the current view. It powers the S2 reasoner's <strong>read-only</strong> <code>query_scene</code> tool for task-progress / success verification ("did the grasp succeed?"); it holds no actuation authority (ADR-0047). Runs out-of-process in an NF4 sidecar served by <code>scene_vlm_node</code>.</p>
  <div class="table-wrap">
    <table>
      <thead><tr><th>rSkill</th><th>Backbone</th><th>Notes</th><th>License</th></tr></thead>
      <tbody>
        <tr>
          <td><code>rskill-qwen35-4b-nf4</code></td>
          <td>Qwen3.5-4B NF4 (~2.5 GB)</td><td>Reasoner <code>query_scene</code> tool · role <code>s2</code></td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
      </tbody>
    </table>
  </div>

  <h2>Reward-monitor rSkills</h2>
  <p><code>kind: reward</code>. A robotic <strong>reward / progress-monitor</strong> model that runs <strong>in parallel with a VLA</strong> and scores the live rollout, emitting per-frame normalised progress (0–1) and success probability. It powers the S2 reasoner's <strong>read-only</strong> <code>query_task_progress</code> tool ("is the task succeeding right now?"); advisory, never on the control path (ADR-0057). Runs out-of-process in an NF4 sidecar served by <code>reward_monitor_node</code>; the pre-quantized checkpoint is meta-loaded directly as 4-bit.</p>
  <div class="table-wrap">
    <table>
      <thead><tr><th>rSkill</th><th>Backbone</th><th>Notes</th><th>License</th></tr></thead>
      <tbody>
        <tr>
          <td><code>rskill-robometer-4b-nf4</code></td>
          <td>Robometer-4B / Qwen3-VL-4B NF4 (~3.3 GB)</td><td>Reasoner <code>query_task_progress</code> tool · role <code>s2</code> · fits 8 GB alongside a small VLA</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
        <tr>
          <td><code>rskill-topreward-qwen3vl-4b-nf4</code></td>
          <td>TOPReward (zero-shot) / Qwen3-VL-4B NF4 (3.13 GB)</td><td>Reasoner <code>query_task_progress</code> tool · role <code>s2</code> · per-frame progress via lerobot prefix sweep · fits 8 GB</td>
          <td><span class="lic lic-green"></span>Apache-2.0</td>
        </tr>
      </tbody>
    </table>
  </div>

  <!-- License legend -->
  <p style="font-size:12.5px; color: var(--mid);">
    <span class="lic lic-green"></span> Free for any use &nbsp;
    <span class="lic lic-yellow"></span> Research-permissive weights (check upstream terms) &nbsp;
    <span class="lic lic-red"></span> Non-commercial: requires <code>OPENRAL_ACCEPT_NONCOMMERCIAL=1</code>
  </p>

  <!-- rSkill manifest format -->
  <h2>rSkill manifest format</h2>
  <pre><code># rskills/smolvla-libero/rskill.yaml (excerpt)
name: "OpenRAL/rskill-smolvla-libero"
version: "0.1.0"
license: "apache-2.0"
role: "s1"
embodiment_tags: ["franka_panda"]
sensors_required:
  - modality: "rgb"
    vla_feature_key: "observation.images.camera1"
latency_budget_ms: 120
quantization: null</code></pre>

  <!-- Robots -->
  <h2>Supported robots</h2>

  <div class="robot-group">
    <h3>Hardware + sim</h3>
    <div class="robot-chips">
      <span class="chip chip-green">SO-100</span>
      <span class="chip chip-green">SO-101</span>
      <span class="chip chip-green">ALOHA bimanual</span>
    </div>
  </div>

  <div class="robot-group">
    <h3>Sim: HW bring-up in progress</h3>
    <div class="robot-chips">
      <span class="chip chip-blue">Franka Panda</span>
      <span class="chip chip-blue">UR5e</span>
      <span class="chip chip-blue">UR10e</span>
    </div>
  </div>

  <div class="robot-group">
    <h3>Sim (eval only)</h3>
    <div class="robot-chips">
      <span class="chip chip-gray">Unitree H1</span>
      <span class="chip chip-gray">Unitree G1</span>
      <span class="chip chip-gray">Flexiv Rizon 4</span>
      <span class="chip chip-gray">Enactic OpenArm v2</span>
      <span class="chip chip-gray">Anvil OpenARM 2.0</span>
      <span class="chip chip-gray">Rethink Sawyer</span>
      <span class="chip chip-gray">Fourier GR1</span>
      <span class="chip chip-gray">ALOHA AgileX (dual-arm)</span>
      <span class="chip chip-gray">Panda Mobile</span>
      <span class="chip chip-gray">Google Robot</span>
      <span class="chip chip-gray">WidowX</span>
      <span class="chip chip-gray">PushT 2D</span>
    </div>
  </div>

  <!-- Benchmarks -->
  <h2>Benchmarks</h2>
  <p>12 benchmark scenes across LIBERO, MetaWorld, ManiSkill3, SimplerEnv, RoboCasa, gym-aloha, and gym-pusht. Every rSkill ships reproducible <code>eval/&lt;benchmark&gt;.json</code> you can regenerate locally:</p>
  <pre><code>openral benchmark run \
  --suite libero_spatial \
  --vla smolvla:rskill://OpenRAL/rskill-smolvla-libero

openral benchmark report</code></pre>

  <!-- Observability -->
  <h2>Observability &amp; data flywheel</h2>
  <p>Every skill execution is an OpenTelemetry span: weights revision pinned, camera frames captured, LLM prompts logged. Traces replay as LeRobotDataset v3 rows, closing the loop from deployment back to training data.</p>
  <pre><code>openral dashboard   # OTLP receiver at :4318, live trace viewer</code></pre>

  <!-- License -->
  <h2>License</h2>
  <p>Everything in this organization is <strong>Apache-2.0</strong>. The entire codebase ships under the same permissive license.</p>
  <p>rSkill weights are governed by their own upstream licenses (Apache-2.0 / MIT / research-permissive / RLWRLD non-commercial). The loader surfaces each weight's posture at install time. This is third-party license lineage for models OpenRAL does not own; it does not affect the Apache-2.0 license of OpenRAL's own code.</p>

  <!-- Footer -->
  <div class="footer">
    <a href="https://github.com/OpenRAL/openral">GitHub</a>
    <a href="https://openral.github.io/openral/">Docs</a>
    <a href="https://discord.gg/3paXT2bVyB">Discord</a>
    <a href="mailto:hello@openral.com">Email</a>
    <span>Apache-2.0 · © OpenRAL contributors</span>
  </div>

</div>
</body>
</html>