Installation

Prerequisites

• Operating system: Linux (Ubuntu 20.04+, Debian 11+, Fedora 36+, Arch), macOS, or Windows via WSL 2
• Internet connection: Required to download Rust and HORUS
• System dependencies: Build tools and development libraries (installed in Step 1)

What You'll Set Up

A working HORUS installation with the horus CLI tool, core libraries, and optionally Python bindings. After completing this guide, you'll be able to create, build, and run HORUS projects.

Time estimate: ~10–15 minutes

Platform Support

Step 1: Install System Dependencies

Install build tools and development libraries for your platform.

You should see all packages install without errors. If a package is not found, verify your system's package repositories are up to date.

Step 2: Install Rust

HORUS requires Rust 1.92 or later.

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

Follow the prompts — press Enter to accept the defaults. Then load the Rust environment:

source $HOME/.cargo/env

Verify the installation:

rustc --version
cargo --version

You should see version numbers like rustc 1.92.0 or higher. If rustc is not found, restart your terminal and try again.

Step 3: Install HORUS

Option A: One-line installer (recommended)

curl -fsSL https://raw.githubusercontent.com/softmata/horus/release/install.sh | bash

This downloads and runs the installer, which builds the horus CLI and installs it to ~/.cargo/bin/.

Option B: Clone and build

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

The installer takes approximately 5 minutes. You should see green checkmarks for each step as it completes.

Step 4: Verify Installation

horus --help

You should see a list of available commands including new, run, monitor, install, search, and more.

Run the system health check:

horus doctor

You should see a summary of your HORUS installation with all checks passing. If any checks fail, the output includes remediation steps.

Step 5: Install Python Bindings (Optional)

If Python 3.9+ was detected during Step 3, the bindings are already installed. Verify:

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

You should see Python bindings installed. If you see ModuleNotFoundError, install manually:

# Install maturin (Rust-Python build tool)
cargo install maturin

# Build and install from the horus_py directory
cd horus_py
maturin develop --release

You should see Successfully installed horus-robotics. Verify again with the python3 -c "import horus" command above.

Updating HORUS

If you used Option B (clone and build):

cd horus
git pull
./install.sh

To preview changes before updating:

git fetch
git log HEAD..@{u}
git pull
./install.sh

Uninstalling HORUS

Run the uninstaller from the HORUS directory:

cd horus
./uninstall.sh

This removes the horus CLI binary from ~/.cargo/bin/, cached libraries from ~/.horus/cache/, and cleans up shared memory files. Project-local .horus/ directories are left untouched.

Docker Installation

For CI/CD pipelines and containerized deployments:

# Multi-stage build
FROM rust:1.80-bookworm AS builder

# System dependencies
RUN apt-get update && apt-get install -y \
    build-essential pkg-config libssl-dev cmake \
    python3-dev python3-pip && rm -rf /var/lib/apt/lists/*

# Install HORUS
RUN curl -fsSL https://raw.githubusercontent.com/softmata/horus/release/install.sh | bash

# Build your project
WORKDIR /app
COPY . .
RUN horus build --release

# Runtime stage
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y libssl3 && rm -rf /var/lib/apt/lists/*
COPY --from=builder /root/.cargo/bin/horus /usr/local/bin/
COPY --from=builder /app/.horus/target/release/my_robot /usr/local/bin/

# CRITICAL: --ipc=host for shared memory access across containers
# docker run --ipc=host my-robot
CMD ["my_robot"]

Important: Use --ipc=host when running the container to enable shared memory access between containers and the host:

docker run --ipc=host my-robot-image

Without --ipc=host, topics cannot be shared across container boundaries.

CI/CD Setup

GitHub Actions

name: HORUS CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-action@v1

      - name: Install system deps
        run: sudo apt-get update && sudo apt-get install -y build-essential pkg-config libssl-dev cmake

      - name: Install HORUS
        run: curl -fsSL https://raw.githubusercontent.com/softmata/horus/release/install.sh | bash

      - name: Validate project
        run: horus check

      - name: Build
        run: horus build --release

      - name: Test (simulation mode, no hardware)
        run: horus test --sim --release

      - name: Lint
        run: horus lint

      - name: Format check
        run: horus fmt --check

Key CI flags:

• horus test --sim — run without hardware (uses simulated sensors)
• horus fmt --check — fail if code is unformatted (exit code 1)
• horus lint — run clippy + ruff

Offline Installation

For air-gapped robots without internet access:

# On a machine WITH internet:
# 1. Download the installer and source
curl -fsSL https://raw.githubusercontent.com/softmata/horus/release/install.sh -o install.sh
git clone https://github.com/softmata/horus.git --branch release --depth 1

# 2. Transfer to the robot via USB
scp -r install.sh horus/ robot@192.168.1.100:~/

# On the air-gapped robot:
# 3. Install from local source
cd ~/horus
./install.sh --local

Understanding horus doctor

horus doctor runs a comprehensive health check. Here's what each check means:

horus doctor --verbose

Auto-fix: horus doctor --fix installs missing toolchains and system packages automatically. It pins installed versions to horus.lock.

Troubleshooting

See the Troubleshooting Guide for more issues and detailed solutions.

Key Takeaways

• HORUS installs via a one-line command or by cloning and running ./install.sh
• The horus CLI is installed to ~/.cargo/bin/ and core libraries are cached in ~/.horus/cache/
• Python bindings are auto-installed when Python 3.9+ is detected
• horus doctor verifies your installation is healthy
• No hardware is required — HORUS works on any Linux, macOS, or WSL 2 machine

Next Steps

• Quick Start — Build your first HORUS application in Rust
• Quick Start (Python) — Build your first HORUS application in Python

See Also

• Choosing a Language — Rust vs Python comparison
• CLI Reference — Complete horus command documentation
• Common Mistakes — Avoid frequent beginner pitfalls
• Troubleshooting — Solutions for installation and runtime issues