Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pythops/oryx/llms.txt

Use this file to discover all available pages before exploring further.

Building Oryx from source gives you full control over the binary and is the only way to make local modifications. Oryx is a Rust workspace with an embedded eBPF component (oryx-ebpf) that compiles to BPF bytecode. This requires the Rust nightly toolchain and a specialised BPF linker — standard stable Rust is not sufficient.

​
Prerequisites

Oryx requires Rust nightly, not stable. The workspace’s rust-toolchain.toml pins the channel to nightly. Attempting to build with stable Rust will fail.
Before you start, ensure the following are available on your system:
  • Linux kernel 6.10 or higher. Some features depend on kernel capabilities introduced in 6.10. If you are on Debian, version 13 (Trixie) or newer is required; on Ubuntu, version 24.04 (Noble) or newer.
  • Rust nightly toolchain with the rust-src component (installed in step 1 below).
  • bpf-linker — the LLVM-based linker used to produce BPF ELF objects. See the bpf-linker installation instructions.
  • git to clone the repository.

​
Build steps

1

Install the Rust nightly toolchain

Install nightly Rust and the rust-src component, which is required to cross-compile the eBPF crate:
rustup toolchain install nightly --component rust-src
2

Install bpf-linker

bpf-linker links the eBPF object files produced by the Rust compiler. Follow the official installation guide for your distribution:https://github.com/aya-rs/bpf-linker?tab=readme-ov-file#installation
3

Clone the repository

git clone https://github.com/pythops/oryx
cd oryx
4

Build the release binary

The xtask helper orchestrates the two-stage build: it first compiles oryx-ebpf for the BPF target and then compiles oryx-tui for the host, embedding the eBPF object at link time.
cargo xtask build --release
The resulting binary is written to target/release/oryx.
5

Install the binary

Copy the binary to a directory in your $PATH:
sudo cp target/release/oryx /usr/local/bin/oryx
Run Oryx with root privileges:
sudo oryx

​
Workspace structure

The repository is a Cargo workspace. Understanding the layout helps when navigating or modifying the code: 
oryx/
├── oryx-tui/       # Userspace TUI application (Ratatui, Aya, crossterm)
├── oryx-ebpf/      # eBPF kernel programs (no_std, compiled for BPF target)
├── oryx-common/    # Shared types used by both oryx-tui and oryx-ebpf
├── xtask/          # Build orchestration (cargo xtask build / run)
├── Cargo.toml      # Workspace manifest
└── rust-toolchain.toml  # Pins the nightly channel
oryx-ebpf is not a member of the top-level workspace (it has its own [workspace] section with an empty members list) because it compiles for a different target. The xtask crate handles invoking cargo build for it separately before building the rest of the workspace.

​
Development helpers

The Justfile at the repository root provides convenience targets: 
just build          # cargo xtask build (debug)
just run            # cargo xtask run (debug)
just run-debug      # cargo xtask run with RUST_LOG=info and RUST_BACKTRACE=1 (output to log-file)
just fmt            # run cargo fmt across oryx-ebpf, oryx-tui, and oryx-common
just clean <iface>  # remove TC filters attached to a network interface
just show <iface>   # list TC filters on a network interface
just release        # cargo xtask run --release
just update         # cargo update for workspace and oryx-ebpf

Build docs developers (and LLMs) love

Get started for freeTalk to us