Almond Axol SDK

Command-line interface and Python SDK for the Almond Axol dual-arm robot. CLI invoked as axol <command> [flags].

The browser front-ends live under web/: a VR teleoperation interface (WebXR, hosted at axol.almond.bot), a web control panel that drives the robot from a browser via axol serve, and a diagnostics dashboard for live motor telemetry and health. See web/README.md for the front-end details.

The full documentation is hosted at docs.almond.bot. The sources live under docs/, and the pages below link to them.

New here? See Teleoperation to go from installation to a live session, or the Web Control Panel guide to drive Axol from a browser.

Requirements

• Linux
• Python 3.12+ (the hosted installer bundles 3.13)
• (Optional) NVIDIA Jetson (e.g. a ZED Box) — required for the GMSL-attached ZED cameras (data collection / policy inference).

Installation

One-command install (recommended)

One command installs uv, the axol CLI (from PyPI, with the lerobot, sim, and tracker extras), and a root systemd service that keeps axol serve running at boot:

curl https://axol.almond.bot/install -fsS | bash

Then open axol.almond.bot and connect to the machine. The install tracks releases: when a newer release exists, the control panel shows an update banner, and pressing Update reinstalls at the new release and restarts the server once idle.

On aarch64/Jetson, PyPI's pinned Torch 2.10 wheel is CPU-only. Local CUDA policy inference needs an explicitly managed JetPack-compatible Torch + Torchvision build; otherwise use remote inference or --device cpu. The hosted update paths refuse to overwrite an existing custom/CUDA build.

Development install

Install the package from a clone using uv — every dependency resolves from PyPI (kinematics comes through our published forks, almond-pyroki and almond-jaxls):

uv sync

Then activate the virtual environment so the axol CLI is on your path (or prefix every command with uv run):

source .venv/bin/activate

Install optional dependency groups as needed:

uv sync --extra lerobot --extra sim --extra tracker   # hosted feature set

The ZED Python bindings (pyzed) are not on PyPI and must be installed separately after the ZED SDK is installed:

axol zed.install

Streaming the ZED cameras to the headset (teleop --cameras, collect-data) encodes on the Jetson's NVENC via GStreamer and sends over WebRTC with aiortc. The encode path needs the system GStreamer NVENC tools plus the patched ZED source plugins, so it isn't a dependency extra. Install it once (and, on a Jetson, pin the NVENC/VIC clocks for low-latency encode):

axol gst.install
axol gst.build-zed   # build the patched ZED source plugins (needs the ZED SDK)
axol jetson.setup    # Jetson only; no-op elsewhere

Before using any motor or robot commands, initialize the CAN hardware:

axol can.setup

To drive Axol from a browser instead of the terminal, build the web UI once (it's served by axol serve):

cd web
npm install
npm run build --workspace=packages/axol-vr-client   # client package first
npm run build --workspace=app                        # → web/app/dist

See the installation guide for the full walkthrough.

Testing

The automated suite is hardware-independent: robot, CAN, ZED, and headset boundaries are exercised through protocol and API contracts, while simulation-capable code is imported with the sim extra. Several modules import the lerobot extra at import time, so install both. CI enforces aggregate coverage floors of 30% for the Python package and 75% for the tested browser libraries.

# Python unit/integration tests, coverage, lint, and package builds
uv sync --extra sim --extra lerobot --dev
uv run pytest
uvx --from ruff==0.9.7 ruff check .
uvx --from ruff==0.9.7 ruff format --check .
uv build

# React/TypeScript tests, lint, formatting, and production build
cd web
npm ci
npm test
npm run lint
npm run format:check
npm run build

Pull requests must pass the Python and Web GitHub Actions checks before merging to main.

Sitemap

Get Started

• Overview
• Installation

Operations

Each operation can be driven from the web control panel or the CLI:

• Teleoperation — drive the robot live from a VR headset (or in sim)
• Gravity Compensation — hold the arms weightless for hand-guiding
• Data Collection — record teleop episodes to a LeRobot dataset
• Replay Dataset — replay a recorded dataset episode on the robot, once or on a loop
• Run Policy — run a trained policy, local or remote inference
• DAgger Collection — run a policy while correcting it from VR, recording the corrections

Mantis

• Mantis Hardware — handheld rigs for collecting demonstrations without moving the robot
• Mantis Tracking — set up Quest, Lighthouse, or Ultimate tracking as the pose source

Remote Teleop

• Remote Teleop — drive over the internet by sideloading Tailscale on a Meta Quest

Web Interfaces

• Web Control Panel — drive the robot from a browser via axol serve
• Diagnostics Dashboard — live motor telemetry, health tiles, and diagnostics scripts, served by axol serve
• VR Interface — the in-repo WebXR teleop app (web/)
• Quest over USB — low-latency wired controller transport (poses over a USB adb tunnel; camera stays on the LAN)
• Quest Without Wearing It — keep the headset awake with nobody wearing it (proximity sensor off) for headless sessions

Advanced

• Development install — clone + uv sync, optional extras, building the web UI

CLI Reference

• Command configuration — draccus config model for teleop, gravity-comp, waypoints, collect-data, collect-dagger, replay-dataset, run-policy, inference-server
• serve — web control panel + API server
• can.setup
• can.enable
• can.driver
• lift.home
• lift.goto
• motor.info
• motor.health
• diag.rom-enable
• diag.rom-disable
• diag.teleop-jitter
• diag.offline
• diag.lift-cycle
• diag.zed-cable
• motor.set-can-id
• motor.set-zero-pos
• motor.dump-config
• motor.set-config
• motor.restore-config
• motor.flash
• teleop
• collect-data
• collect-dagger
• migrate-dataset
• replay-dataset
• run-policy
• inference-server
• provision
• rt.install
• zed.driver
• zed.install
• gst.install
• gst.build-zed
• jetson.setup
• tracker.* — Mantis tracker setup: bridge, identify, pair, install, and base-station / Ultimate checks
• tune.pid
• tune.friction
• tune.gravity
• tune.factory
• calibration.pull
• tune.motion
• tune.filter
• motion.build
• tune.repeatability
• gravity-comp
• waypoints

Python API

• Core Concepts
• almond_axol.robot — Axol, Sim, configuration, gravity compensation
• almond_axol.kinematics
• almond_axol.teleop
• almond_axol.vr
• almond_axol.zed
• almond_axol.motor
• almond_axol.lerobot