# What is rustjail? Core Container Runtime Primitives for CubeSandbox

> Discover rustjail, a Rust library for OCI-compatible container runtime primitives. It offers namespace, cgroup, process, and seccomp control for CubeSandbox.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: deep-dive
- Published: 2026-07-05

---

**rustjail is an internal Rust library that implements OCI-compatible container runtime primitives, providing namespace isolation, cgroup management, process lifecycle control, and seccomp filtering for the CubeSandbox micro-VM architecture.**

`rustjail` serves as the low-level container engine powering TencentCloud's CubeSandbox project. Defined as a workspace member in [`agent/Cargo.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/Cargo.toml), this crate supplies the essential mechanisms to create, constrain, and manage lightweight Linux containers that isolate guest workloads according to the Open Container Initiative (OCI) specification.

## Container Isolation and Namespace Management

The foundation of rustjail's architecture rests on Linux kernel namespaces, implemented through the `LinuxContainer` abstraction.

### LinuxContainer and Namespace Creation

In [`agent/rustjail/src/container.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/rustjail/src/container.rs), the `LinuxContainer` struct implements the `BaseContainer` trait to orchestrate namespace creation. When instantiated via `LinuxContainer::new()`, it establishes new **PID**, **mount**, **network**, **IPC**, **UTS**, and **user** namespaces for each sandbox, ensuring complete process and filesystem isolation from the host.

```rust
use rustjail::container::{BaseContainer, LinuxContainer};
use rustjail::specconv::CreateOpts;

let opts = CreateOpts {
    spec: oci_spec,
    // rootfs path, mounts, etc.
};
let container = LinuxContainer::new(opts)?;
let pid = container.start()?; // Returns the PID of the container init

```

The container lifecycle also includes synchronization primitives such as `rustjail::sync` and `rustjail::sync_with_async` to coordinate multi-threaded startup sequences, ensuring namespaces are fully established before the init process executes.

## Resource Control and Cgroup Management

Rustjail enforces resource constraints through the Linux cgroup subsystem, exposed via the `rustjail::cgroups` modules.

### Cgroup Configuration and Monitoring

The `agent/rustjail/src/cgroups/` directory contains filesystem-based helpers that create and configure **cpu**, **memory**, **cpuset**, and **blk-io** control groups. These modules provide functions to set limits and monitor out-of-memory (OOM) conditions through event notifiers.

```rust
use rustjail::cgroups::fs;

// Set a 256 MiB memory limit
fs::set_memory_limit("my_container", 256 * 1024 * 1024)?;

// Retrieve guest CPU set topology
let guest_cpuset = rustjail_cgroups::fs::get_guest_cpuset()?;

```

As shown in [`agent/src/sandbox.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/sandbox.rs), the higher-level agent code leverages these primitives to apply hardware topology and resource limits to micro-VMs.

## Process Management and I/O Streams

Managing the container init process and its standard I/O requires careful handling of file descriptors and process state.

### Process Spawning and Pipe Streams

The `rustjail::process::Process` struct in [`agent/rustjail/src/process.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/rustjail/src/process.rs) handles the execution of the container's init process, including capability configuration and seccomp setup. For I/O redirection, `rustjail::pipestream::PipeStream` in [`agent/rustjail/src/pipestream.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/rustjail/src/pipestream.rs) provides async-compatible channels that connect the host's stdin/stdout/stderr to the containerized process.

```rust
use rustjail::process::Process;
use rustjail::pipestream::PipeStream;

// Start the init process inside isolated namespaces
let pid = container.start()?;

// Attach pipe streams for I/O
let streams = PipeStream::new(pid)?;

```

The library also implements `WAIT_PID_LOCKER` for signal-safe process reaping and supports exec-style re-entry for running additional commands within existing containers.

## OCI Specification and gRPC Conversion

Rustjail bridges the gap between CubeSandbox's gRPC API and standard OCI runtime specifications.

### specconv and gRPC Translation

The `rustjail::specconv` module in [`agent/rustjail/src/specconv.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/rustjail/src/specconv.rs) converts gRPC-encoded OCI specifications (received via CubeAPI) into the `oci` crate structures used internally. This includes translating process definitions, mounts, and resource limits from the wire format to runtime configurations.

```rust
// Convert gRPC spec to OCI spec
let oci_process = rustjail::process_grpc_to_oci(&grpc_spec.process);

```

This conversion ensures that container definitions arriving through the RPC interface in [`agent/src/rpc.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/rpc.rs) are validated and normalized before container creation.

## Security: Seccomp and Mount Validation

Security features in rustjail are exposed through optional Cargo features defined in [`agent/rustjail/Cargo.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/rustjail/Cargo.toml).

### Seccomp BPF Filtering

When the `seccomp` feature is enabled, `rustjail::seccomp` generates and loads Berkeley Packet Filter (BPF) programs to restrict available system calls. This generates allow-lists or deny-lists that the kernel enforces before executing syscalls in the container context.

```toml

# In Cargo.toml

[features]
seccomp = ["rustjail/seccomp"]

```

```rust
#[cfg(feature = "seccomp")]
use rustjail::seccomp::Seccomp;

// Create a filter allowing only read/write syscalls
let filter = Seccomp::new(vec!["read", "write"])?;
filter.apply()?; // Loads into the kernel for the current thread

```

### Mount Handling

The `rustjail::mount` module performs bind-mounts, overlay filesystem mounts, and validates mount options before application, preventing dangerous configurations like unrestricted host filesystem access.

## Summary

- **rustjail** is a Rust workspace member in [`agent/Cargo.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/Cargo.toml) that implements OCI-compatible container runtime primitives for CubeSandbox.
- **`LinuxContainer`** in [`agent/rustjail/src/container.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/rustjail/src/container.rs) creates PID, mount, network, and user namespaces for isolation.
- **`rustjail::cgroups`** modules enforce resource limits on CPU, memory, and I/O while monitoring OOM events.
- **`PipeStream`** and **`Process`** manage container init lifecycle and async I/O redirection between host and guest.
- **`specconv`** translates gRPC OCI specifications from CubeAPI into internal runtime structures.
- **Optional `seccomp`** support generates BPF filters to restrict system calls, enhancing security.

## Frequently Asked Questions

### What is rustjail and how does it relate to CubeSandbox?

rustjail is an internal Rust library within the TencentCloud/CubeSandbox repository that implements the core container runtime. It provides the low-level primitives—namespace creation, cgroup management, and process control—that the CubeSandbox agent uses to isolate micro-VM workloads. It is bundled as a workspace crate in [`agent/Cargo.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/Cargo.toml) and consumed by the main agent code in [`agent/src/sandbox.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/src/sandbox.rs).

### Which Linux namespaces does rustjail create for each container?

According to the source code in [`agent/rustjail/src/container.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/rustjail/src/container.rs), rustjail creates new **PID**, **mount**, **network**, **IPC**, **UTS**, and **user** namespaces for each `LinuxContainer` instance. This comprehensive isolation ensures that processes, network interfaces, and filesystem views remain separate from the host and other containers.

### How does rustjail handle OCI specification conversion?

The `rustjail::specconv` module in [`agent/rustjail/src/specconv.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/rustjail/src/specconv.rs) provides conversion functions like `process_grpc_to_oci` that translate gRPC-encoded OCI specifications (defined in the `protocols::oci` module) into the standard `oci` crate structures used by the runtime. This bridge allows CubeSandbox's API to accept container definitions while maintaining OCI runtime compatibility.

### Is seccomp support mandatory when using rustjail?

No, seccomp support is optional and controlled via Cargo features in [`agent/rustjail/Cargo.toml`](https://github.com/TencentCloud/CubeSandbox/blob/main/agent/rustjail/Cargo.toml). The `seccomp` feature must be explicitly enabled to include the `rustjail::seccomp` module and its BPF filtering capabilities. When disabled, rustjail operates without system call filtering, relying on other security mechanisms like capabilities and namespaces for isolation.