Installing HORUS

This guide covers installing Rust, building HORUS, and verifying the installation. The process takes approximately 10-15 minutes.

Platform Support

HORUS has native cross-platform support:

The namespace defaults to the literal default — so on Linux the real directory is /dev/shm/horus_default/. Set HORUS_NAMESPACE to isolate robots from each other.

Prerequisites

Required:

• Operating System: Linux, macOS, or Windows
  • Linux: Ubuntu 20.04+ recommended (fastest shared memory)
  • macOS: Native support using /tmp/horus_<namespace>/
  • Windows: Native support using %TEMP%\horus_<namespace>\
• Rust 1.90+: We'll install this in Step 1
• Build Tools & System Libraries: Build tools, pkg-config, and all required development libraries
  Copy

  # Ubuntu/Debian/Raspberry Pi OS - COMPLETE dependencies (copy-paste this!)
  sudo apt update
  sudo apt install -y build-essential pkg-config \
    libssl-dev libudev-dev libasound2-dev \
    libx11-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev \
    libwayland-dev wayland-protocols libxkbcommon-dev \
    libvulkan-dev libfontconfig-dev libfreetype-dev \
    libv4l-dev
  
  # Fedora/RHEL/CentOS
  sudo dnf groupinstall "Development Tools"
  sudo dnf install -y pkg-config openssl-devel systemd-devel alsa-lib-devel \
    libX11-devel libXrandr-devel libXi-devel libXcursor-devel libXinerama-devel \
    wayland-devel wayland-protocols-devel libxkbcommon-devel \
    vulkan-devel fontconfig-devel freetype-devel \
    libv4l-devel
  
  # Arch Linux
  sudo pacman -S base-devel pkg-config openssl systemd alsa-lib \
    libx11 libxrandr libxi libxcursor libxinerama \
    wayland wayland-protocols libxkbcommon \
    vulkan-icd-loader fontconfig freetype2 \
    v4l-utils
  

• 10-15 minutes: For first-time installation
• Internet connection: To download dependencies

What these packages do:

• Core: libssl-dev (networking), libudev-dev (device detection), libasound2-dev (audio)
• Graphics/GUI: X11, Wayland libraries (required for monitor)
• Optional: libv4l-dev (camera support), fontconfig (improved text rendering)

Not required:

• Rust (installed in Step 1)
• Git (installed in Step 2)
• Systems programming experience

Quick Install (Recommended)

Copy and paste these commands into your terminal:

# 1. Install Rust (takes ~2 minutes)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 2. Clone HORUS
git clone https://github.com/softmata/horus.git
cd horus

# 3. Run automated installer (takes ~5 minutes)
./install.sh

# 4. Verify it works
horus --help

If the help command displays available commands, installation is complete. Skip to Next Steps.

What the installer does:

• Clones the HORUS source into ~/.horus/cache/horus@<version>/ (kept because horus run/horus build compile projects against horus as path dependencies)
• Downloads a checksum-verified pre-built horus binary when one matches your platform, and otherwise builds only the horus_manager package, which produces the horus binary
• Installs the horus CLI tool to ~/.cargo/bin/ (or ~/.local/bin/)
• Verifies the install by running horus --version and adds the install directory to your PATH

Step-by-Step Installation

Step 1: Install Rust

HORUS is built with Rust. No prior Rust experience is required; HORUS also supports Python for application development.

On Linux (or WSL/Docker):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the prompts (just press Enter for defaults).

Restart your terminal or run:

source $HOME/.cargo/env

Verify Rust is installed:

rustc --version
cargo --version

You should see version numbers like rustc 1.90.0 or higher.

Step 2: Install Git (If You Don't Have It)

Check if you have Git:

git --version

If not, install it:

# Ubuntu/Debian
sudo apt install git

# Fedora
sudo dnf install git

# Arch Linux
sudo pacman -S git

Step 3: Clone HORUS

Download the HORUS source code:

git clone https://github.com/softmata/horus.git
cd horus

This creates a horus directory with all the code.

Step 4: Run the Installer

Use the automated installer to install everything:

./install.sh

This script:

1. Clones and caches the HORUS source at ~/.horus/cache/horus@<version>/
2. Downloads a pre-built horus binary from GitHub Releases (checksum-verified), or compiles horus_manager from that cached source if no binary matches your platform (~3-5 min)
3. Installs the horus binary to ~/.cargo/bin/ (or ~/.local/bin/)
4. Adds the install directory to your PATH and runs horus env --init
5. Verifies with horus --version

The output displays progress with colored indicators. Green checkmarks indicate successful steps.

Step 5: Verify Installation

Test that the horus command works:

horus --help

You should see a list of available commands like new, run, monitor, etc.

Python Support

Python bindings are not installed by ./install.sh — build them manually with maturin:

# From the horus repository root:

# 1. Install maturin (Python build tool)
# Option A: Via Cargo (recommended for Ubuntu 24.04+)
cargo install maturin

# Option B: Via pip (if not blocked by PEP 668)
# pip install maturin

# 2. Navigate to Python bindings
cd horus_py

# 3. Build and install (takes ~3 minutes)
maturin develop --release

To verify Python bindings work:

python3 -c "import horus; print('Python bindings installed successfully')"

Note: The PyPI package name is horus-robotics, but you import it as import horus in Python code.

See Python Bindings for complete API documentation and examples.

Platform-Specific Notes

Linux (Ubuntu/Debian)

Linux installation is straightforward. If build errors occur, install all required packages:

sudo apt update
sudo apt install -y build-essential pkg-config \
  libssl-dev libudev-dev libasound2-dev \
  libx11-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev \
  libwayland-dev wayland-protocols libxkbcommon-dev \
  libvulkan-dev libfontconfig-dev libfreetype-dev \
  libv4l-dev

Linux (Fedora/RHEL)

sudo dnf groupinstall "Development Tools"
sudo dnf install -y pkg-config openssl-devel systemd-devel alsa-lib-devel \
  libX11-devel libXrandr-devel libXi-devel libXcursor-devel libXinerama-devel \
  wayland-devel wayland-protocols-devel libxkbcommon-devel \
  vulkan-devel fontconfig-devel freetype-devel \
  libv4l-devel

Raspberry Pi

HORUS runs on Raspberry Pi. Install Ubuntu Server or Raspberry Pi OS, then:

# Install all dependencies
sudo apt update
sudo apt install -y build-essential pkg-config \
  libssl-dev libudev-dev libasound2-dev \
  libx11-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev \
  libwayland-dev wayland-protocols libxkbcommon-dev \
  libvulkan-dev libfontconfig-dev libfreetype-dev \
  libv4l-dev

# Raspberry Pi specific packages (GPIO, I2C, SPI support)
sudo apt install -y libraspberrypi-dev i2c-tools python3-smbus

# Enable I2C and SPI (required for sensors)
sudo raspi-config
# Navigate to: Interface Options → I2C → Enable
# Navigate to: Interface Options → SPI → Enable

Performance tips:

• Use 64-bit OS for better performance
• Compile with --release flag (much faster than debug)
• Allocate more RAM to GPU if using camera nodes (in /boot/config.txt)

NVIDIA Jetson Nano

HORUS supports Jetson Nano with GPU acceleration for vision tasks:

# Install all dependencies
sudo apt update
sudo apt install -y build-essential pkg-config \
  libssl-dev libudev-dev libasound2-dev \
  libx11-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev \
  libwayland-dev wayland-protocols libxkbcommon-dev \
  libvulkan-dev libfontconfig-dev libfreetype-dev \
  libv4l-dev

# Jetson specific packages (GPU acceleration)
sudo apt install -y nvidia-jetpack

# Verify CUDA is installed
nvcc --version

GPU acceleration:

• Install JetPack for CUDA support; HORUS itself ships no CUDA feature
• --enable <cap> forwards <cap> as a cargo feature to your crate, so horus run --enable cuda works only once your project declares a cuda feature under [rust.features] in its horus.toml (in a workspace, in the member's horus.toml — a virtual root cannot carry [features]) and your own node code gates the CUDA path on it

macOS (Native)

HORUS has native macOS support using /tmp/horus_<namespace>/ for shared memory:

# 1. Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 2. Install Xcode Command Line Tools (if not already installed)
xcode-select --install

# 3. Clone and build HORUS
git clone https://github.com/softmata/horus.git
cd horus
./install.sh

# 4. Verify installation
horus --help

macOS shared memory:

• Uses /tmp/horus_<namespace>/, i.e. /tmp/horus_default/ by default (tmpfs-backed, fast)
• Automatically created on first run
• Same API as Linux - no code changes needed

Alternative options (if native doesn't work for your use case):

• Docker - Run HORUS in a Linux container
• VMware/Parallels - Full Linux VM
• Cloud Linux - Remote development on AWS/DigitalOcean

Windows (Native)

HORUS has native Windows support using %TEMP%\horus_<namespace>\ for shared memory:

# 1. Install Rust (using rustup-init.exe from rustup.rs)
# Download and run: https://win.rustup.rs/x86_64

# 2. Clone HORUS (in PowerShell or Git Bash)
git clone https://github.com/softmata/horus.git
cd horus

# 3. Run the install script (Git Bash or WSL recommended)
./install.sh

# 4. Verify installation
horus --help

Note: On Windows, we recommend using Git Bash or WSL to run the install script. Alternatively, you can build manually with cargo build --release and copy the binary to your PATH.

Windows shared memory:

• Uses %TEMP%\horus_<namespace>\ (typically C:\Users\<user>\AppData\Local\Temp\horus_default\)
• Automatically created on first run
• Cross-process communication works natively

Alternative: WSL 2 (if you prefer Linux environment)

1. Open PowerShell as Administrator
2. Run: wsl --install
3. Restart your computer
4. Follow Linux installation steps inside WSL

Hardware Driver Support (Optional)

HORUS integrates hardware drivers distributed as registry packages; none are bundled with the core install. These are completely optional - the default installation does NOT require any hardware packages or drivers.

Key points:

• Default ./install.sh works without any hardware packages
• Nodes that declare no [hardware] need no driver packages at all; horus run --sim swaps declared hardware for stubs
• Hardware drivers are installed from the registry only when you ask for them
• You can install HORUS on your laptop and deploy to hardware later

When you need hardware packages:

• Only when you install a hardware driver from the registry (horus install <driver>) and configure it under [hardware] in horus.toml
• Only for production deployment on actual robots
• Never needed for development, testing, or simulation

Hardware Drivers Available as Registry Packages

None of these ship with the core install. Find and install them with the horus CLI (horus search <hardware>, then horus install <package>), and wire them up under [hardware] in horus.toml. The "System Packages" column lists the host libraries that must already be present for the driver to work.

Installing the System Packages Drivers Need

These are the host libraries and tools from the table above. The drivers themselves come from the registry (horus install <package>).

For Raspberry Pi GPIO/I2C/SPI/PWM:

sudo apt install -y libraspberrypi-dev i2c-tools python3-smbus

# Enable hardware interfaces
sudo raspi-config
# Navigate to: Interface Options → I2C → Enable
# Navigate to: Interface Options → SPI → Enable
# Navigate to: Interface Options → Serial Port → Enable

For CAN bus debugging tools:

sudo apt install -y can-utils

# Setup virtual CAN for testing
sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0

# Test CAN tools
cansend vcan0 123#DEADBEEF
candump vcan0

For Intel RealSense depth cameras:

# Add Intel RealSense repository
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key F6E65AC044F831AC80A06380C8B3A55A6F3EFCDE
sudo add-apt-repository "deb https://librealsense.intel.com/Debian/apt-repo $(lsb_release -cs) main" -u

# Install RealSense SDK
sudo apt install -y librealsense2-dev librealsense2-utils

# Test camera
realsense-viewer

Workflow: Development to Hardware Deployment

Development (on your laptop):

# 1. Install HORUS normally (no hardware packages needed)
./install.sh

# 2. Create and run your project
horus new my_robot
cd my_robot
horus run   # Builds and runs your nodes. A new project declares no
            # [hardware], so nothing here touches a device.

A bare horus run is not simulation mode — it instantiates whatever real drivers [hardware] declares. Once you add hardware entries and want to develop against stubs on your laptop, use --sim:

horus install horus-sim3d   # one-time: the simulator plugin `--sim` launches
horus run --sim             # swaps every [hardware] entry marked `sim = true`
                            # for a stub node

Note: --sim auto-launches the simulator plugin (sim3d by default, or [robot].simulator). If that plugin is not installed, horus run --sim refuses to start rather than fall through to the real hardware.

Deployment (on the robot):

# 1. Install system packages on the robot
sudo apt install libraspberrypi-dev i2c-tools can-utils

# 2. Run against the real hardware
horus run --release

Hardware is declared in horus.toml, not on the command line:

[hardware]
imu = { use = "bno055", bus = "/dev/i2c-1" }

Capabilities such as GPU acceleration or the editor are command-line flags. Each capability name is forwarded to cargo as a feature of your own crate, so declare it under [rust.features] in horus.toml first — otherwise the build stops with none of the selected packages contains these features: cuda:

# horus.toml
[rust.features]
cuda = []
editor = []

horus run --enable cuda --release

Or enable them once in horus.toml (top level, above any [section] header) instead of passing the flag every time:

# horus.toml
enable = ["cuda", "editor"]

Capability names recognised by --enable (each is forwarded as a cargo feature of your crate unless noted; you must declare it under [rust.features] yourself):

• cuda (alias gpu) → feature cuda
• editor → feature editor
• headless → feature headless
• visual → feature visual
• python (alias py) → feature python
• opencv → feature opencv-backend
• io-uring → feature io-uring-net
• ultra-low-latency → feature ultra-low-latency
• full → feature full
• net (alias network) — not forwarded to your crate; enables the net feature on the horus dependency instead
• sim (alias simulation) — turns on no build features by itself

Note: An unrecognised name is passed through verbatim as a cargo feature. If your crate does not declare it, the build fails with none of the selected packages contains these features: <name>.

Hardware buses are not --enable capabilities. Configure them under [hardware] in horus.toml, as shown above.

Cargo feature flags (for advanced users building with cargo directly):

• macros - Procedural macros (node!, topics!) — enabled by default
• net - Transparent LAN topic replication across machines (opt-in; also reachable as horus run --net)
• telemetry - Telemetry export for live monitoring — enabled by default
• blackbox - Flight recorder for post-mortem analysis — enabled by default

Note: Most users should use horus run --enable <capability> or set enable = ["cuda", "editor"] in horus.toml rather than passing cargo --features by hand. The four flags above are features of the horus crate itself, not of your project.

How simulation works:

Entries marked sim = true under [hardware] in horus.toml are swapped for stub nodes when you run horus run --sim; the log then shows hardware.<name>: simulation mode — using stub.

That is the whole mechanism. HORUS does not detect a missing device and silently fall back to simulation — if your driver opens /dev/spidev0.0 and it is not there, that is your driver's error to handle. Write the fallback yourself if you want one, or use --sim to develop on a laptop.

Hardware in Python

Once a driver is installed and declared under [hardware] in horus.toml, you can interact with hardware from Python nodes using HORUS Topics and standard message types:

import horus
from horus import Imu, CmdVel

def controller_tick(node):
    imu_data = node.recv("imu/data")
    if imu_data:
        node.send("cmd_vel", CmdVel(0.5, 0.0))
        # A dict works too, as long as its keys are the message's field names:
        # node.send("cmd_vel", {"linear": 0.5, "angular": 0.0})

node = horus.Node(
    name="Controller",
    subs={"imu/data": {"type": Imu}},
    pubs={"cmd_vel": {"type": CmdVel}},
    tick=controller_tick,
    rate=50
)
horus.run(node)

Declaring a topic with {"type": CmdVel} makes it a typed topic. node.send() accepts either an instance of the message class or a dict, converting a dict with CmdVel(**data).

That conversion is why the field names matter: CmdVel's fields are linear and angular, so {"linear_x": ..., "angular_z": ...} fails to convert. The failure is silent at the conversion step — the code falls through and hands the raw dict to the typed path, which rejects it:

TypeError: 'dict' object is not an instance of 'CmdVel'

The message names the type, not the bad key, so check your field names against the message when you see it.

Additional hardware drivers (CAN bus, SPI, I2C, Dynamixel servos, stepper motors, etc.) are available as registry packages. Use horus search to find drivers for your hardware.

Understanding Shared Memory

HORUS uses platform-specific shared memory for ultra-fast communication between components:

The namespace is default unless you set HORUS_NAMESPACE, so the directory you will normally see is /dev/shm/horus_default/ (Linux), /tmp/horus_default/ (macOS) or %TEMP%\horus_default\ (Windows).

Check available space:

# Linux
df -h /dev/shm

# macOS
df -h /tmp

# Windows (PowerShell)
Get-PSDrive -Name $env:TEMP.Substring(0,1)

You should have at least 256MB. Most systems have 1-2GB.

If you need more space (Linux only):

# Temporarily increase to 2GB
sudo mount -o remount,size=2G /dev/shm

# Make permanent: edit /etc/fstab (requires sudo)
# Add line: tmpfs /dev/shm tmpfs defaults,size=2G 0 0

Updating HORUS

To update to the latest version:

# Navigate to HORUS directory
cd horus

# Pull latest changes and reinstall
git pull
./install.sh

To preview changes before updating:

git fetch
git log HEAD..@{u}  # See what's new
git pull
./install.sh

Uninstalling

To completely remove HORUS:

# Navigate to HORUS directory
cd horus

# Run the uninstaller
./uninstall.sh

The uninstaller will:

1. Remove the horus CLI binary from ~/.cargo/bin/ and ~/.local/bin/
2. Remove ~/.horus/cache/ — the cached HORUS source and its pre-compiled deps
3. Remove the rest of ~/.horus/ (blackbox recordings, shell env files), prompting first only if it holds config.toml or credentials — answer "no" there and your config survives while cache/ still goes
4. Remove ~/.config/horus/ (auth.json, workspace registry) on Linux, or ~/Library/Caches/horus + ~/Library/Application Support/horus on macOS, or %APPDATA%\horus + %LOCALAPPDATA%\horus on Windows
5. Clean up shared memory files (platform-specific paths)
6. Leave project-local .horus/ directories untouched

Manual uninstall (if needed):

Linux/macOS:

# Remove CLI tool
rm -f ~/.cargo/bin/horus ~/.local/bin/horus

# Remove caches, config and credentials — these are separate directories
rm -rf ~/.horus/                 # cached source + pre-compiled deps, blackbox recordings, env.sh / env.fish
rm -rf ~/.cache/horus/           # XDG package cache (horus pkg) — uninstall.sh does not remove this
rm -rf ~/.config/horus/          # auth.json — your registry credentials
rm -rf ~/.local/share/horus/     # recordings, keys
# macOS: ~/Library/Caches/horus, ~/Library/Application Support/horus

# Remove source code
rm -rf ~/horus/  # or wherever you cloned it

# Clean up shared memory (optional - HORUS auto-cleans sessions)
# Linux:
rm -rf /dev/shm/horus_*
# macOS:
rm -rf /tmp/horus_*

Windows (PowerShell):

HORUS ships a native PowerShell uninstaller — prefer it over deleting by hand:

.\uninstall.ps1

To do it manually instead:

# Remove CLI tool
Remove-Item -Force "$env:USERPROFILE\.cargo\bin\horus.exe"

# Remove caches, config and credentials
Remove-Item -Recurse -Force "$env:USERPROFILE\.horus"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\horus"
Remove-Item -Recurse -Force "$env:APPDATA\horus"     # auth.json

# Remove source code
Remove-Item -Recurse -Force "$env:USERPROFILE\horus"  # or wherever you cloned it

# Clean up shared memory (optional - HORUS auto-cleans sessions)
Remove-Item -Recurse -Force "$env:TEMP\horus_*"

Troubleshooting

Having installation issues? Try manual recovery:

# Navigate to HORUS source directory
cd /path/to/horus

# Clean and reinstall
cargo clean
rm -rf ~/.horus/cache    # installer's source cache (horus@<version>) and pre-compiled deps
rm -rf ~/.cache/horus    # XDG cache root — searched first by `horus run`
./install.sh

Common issues:

• Missing packages: Install all required system dependencies (see above)
• Raspberry Pi: Ensure GPIO/I2C packages are installed
• Jetson Nano: Ensure CUDA/JetPack packages are installed

See the Troubleshooting & Maintenance Guide for:

• Common installation errors and detailed fixes
• System dependency issues
• Platform-specific problems
• 15+ solved issues with step-by-step solutions

Next Steps

With HORUS installed, proceed to one of the following:

1. Quick Start Tutorial - Build your first HORUS application
2. CLI Reference - Complete command documentation
3. Examples - Sample HORUS applications

Recommended: Start with the Quick Start Tutorial.