Documentation

Welcome to the documentation for Rustybox, a modern, memory-safe reincarnation of BusyBox written entirely in Rust.

Getting Started

Rustybox packages the functionality of standard system commands into a single, fully-static binary. It ships in two distinct editions: Full (GPL-2.0), which retains maximum BusyBox compatibility, and Core (MIT), which compiles only permissively licensed, safe Rust backends.

Quick Installation

You can fetch the statically linked binary for your architecture directly from the release page:

# Download the MIT edition (rustybox-core)
curl -LO https://github.com/peterlodri-sec/rustybox/releases/latest/download/rustybox-core-x86_64-unknown-linux-musl

# Make executable
chmod +x rustybox-core-x86_64-unknown-linux-musl

# Verify execution
./rustybox-core-x86_64-unknown-linux-musl --version

Multicall Mechanics

Like original BusyBox, Rustybox uses multicall mechanics to act as multiple utilities. The binary determines which tool to execute based on its own process name (argv[0]).

There are two primary ways to run commands:

1. Symlinks (Standard Unix Integration)

By creating symlinks named after individual applets (such as ls, grep, cat) that point to the rustybox binary, the utilities will execute natively when invoked.

# Create a symlink named "ls" pointing to rustybox-core
ln -s rustybox-core-x86_64-unknown-linux-musl ls

# Run the command through the symlink
./ls -la

2. Explicit Subcommands

If called by its own binary name, Rustybox dispatches commands based on its first argument:

# Dispatch the 'grep' applet explicitly
./rustybox grep -rn "TODO" src/

Usage & Examples

Rustybox is designed for minimal containers, system rescue images, and orchestration engines that require robust, sandboxed userlands.

1. Scratch Containers (Peak Minimalism)

Because the binary is compiled fully-statically using musl, it has absolutely zero external dependencies. You can drop it directly into an empty scratch container to create lightweight, secure environments.

FROM scratch

# Copy statically linked MIT edition into container
COPY rustybox-core-x86_64-unknown-linux-musl /bin/rustybox

# Automatically install all symlinks into /bin on container startup
RUN ["/bin/rustybox", "--install", "/bin"]

# Run a minimal shell
ENTRYPOINT ["/bin/ash"]

2. Agentic AI and Automation Harnesses

Rustybox integrates modern utilities like timeout, watch, flock, and xargs natively, making it a powerful harness environment for scripting and bounding processes spawned by AI agents.

# Bounding execution: kill the build command if it runs past 30 seconds
rustybox timeout 30 cargo build

# Task locking: ensure only one agent script runs at a time
rustybox flock /tmp/agent.lock -c "python run_tasks.py"

# Periodic observation: monitor CPU usage of a specific process every 2s
rustybox watch -n 2 "ps aux | grep node"

Dual-Edition Model

The defining architectural feature of Rustybox is its dual-edition compilation pipeline, which separates copyleft licensing from permissive deployments:

Modern Backends

Originally, Rustybox was generated as a pure c2rust transpile of BusyBox, producing heavily unsafe, pointer-based C code written in Rust syntax. We are incrementally replacing this legacy transpile with modern, memory-safe library code.

Size & Compilation Strategies

To preserve BusyBox's tiny footprint while running on memory-safe engines, Rustybox employs several link-time optimization (LTO) techniques:

• Size Optimization: Cargo compiles code with opt-level = 'z' and codegen-units = 1 to prioritize density.
• Static musl Target: Releases are built against musl-gcc to enable static linking, allowing binaries to run on empty filesystems.
• UPX Compression: Artifacts are packed in CI using UPX --best --lzma. The normal builds retain debug symbols inside the compressed package, while -slim builds strip symbols before compression to achieve a target size of just ~3.2MB.
• The wild Linker: We use the wild linker in the CI pipeline to significantly accelerate link-time optimization (LTO) stages for cross-crate static builds.

Contribution Guide

We welcome contributions! Our main roadmap is migrating the legacy transpiled applets over to safe, permissively licensed Rust modules.

How to Migrate an Applet

If you want to port an applet to a safe modern engine, follow these steps:

1. Expose Dependencies: Add the permissive library under [dependencies] in Cargo.toml and crates/rustybox-core/Cargo.toml.
2. Define Feature Flags: Declare a feature flag named modern-<applet> in the root Cargo.toml.
3. Wire Dispatch: Update modern.rs to route execution to the library wrapper, and add the dispatch matcher under dispatch() in crates/rustybox-core/main.rs.
4. Bypass Legacy FFI: Disable or remove the legacy transpiled C entrypoint from the vector in applets/applet_tables.rs.
5. Verify Behavior: Add smoke/integration tests in tests/modern.rs and run the test suite.

Coding Standards

• Unsafety Reduction: The primary goal is reducing the count of unsafe blocks. Unsafe operations should be isolated to thin system call boundaries.
• One-Line Imports: Maintain a single-line, single-symbol import style for standard library components (e.g. use libc::uid_t;) to allow global refactoring scripts to process imports easily.

Licensing Breakdown

Rustybox contains two separate licensing boundaries, enabling flexible usage:

The GPL Boundary (rustybox binary)

Because the transpiled code is derived directly from the C sources of BusyBox, the full binary is a derivative work under the GNU General Public License, Version 2 (GPL-2.0-only).

If you distribute modifications to the full rustybox binary, or link it into proprietary compilation pipelines, you must make its complete source code available under GPL-2.0.

The MIT Boundary (rustybox-core binary)

The rustybox-core subcrate does not import or link any transpiled C code. All compiled components (uutils coreutils, RustCrypto hashers, and custom adapters) are permissively licensed.

This binary is distributed under the MIT License, allowing you to embed it in proprietary firmware, proprietary automation workflows, or commercial container distributions without copyleft requirements.

Applet Registry

Use the interactive table below to explore all available applets, their migration status, dependencies, and license classifications.