# LiteBox 9P Protocol Support: Implementation Status and Usage Guide

> Explore LiteBox 9P protocol support, its implementation status, and usage. Learn how to leverage remote directory mounting with this Plan 9 protocol integration.

- Repository: [Microsoft/litebox](https://github.com/microsoft/litebox)
- Tags: how-to-guide
- Published: 2026-02-16

---

**LiteBox currently provides a placeholder 9P file-system implementation in [`litebox/src/fs/nine_p.rs`](https://github.com/microsoft/litebox/blob/main/litebox/src/fs/nine_p.rs) that will replace VSBox's 9P client to enable remote directory mounting via the Plan 9 protocol.**

The `microsoft/litebox` repository defines a skeletal 9P protocol support module designed to eventually handle network-backed file system operations. This implementation follows the same trait-based architecture as LiteBox's existing in-memory and tar-based file systems, providing a unified interface for sandboxed environments to access remote directories without copying data into local memory.

## Architectural Overview of LiteBox 9P Protocol Support

The 9P protocol support in LiteBox is structured around a trait-based file system abstraction that mirrors the design of other storage backends in the project.

### The nine_p Module Structure

The core implementation resides in [`litebox/src/fs/nine_p.rs`](https://github.com/microsoft/litebox/blob/main/litebox/src/fs/nine_p.rs), which declares the `FileSystem` struct:

```rust
// From litebox/src/fs/nine_p.rs
pub struct FileSystem<Platform: crate::sync::RawSyncPrimitivesProvider> {
    // Fields will hold connection state to remote 9P server
    _phantom: std::marker::PhantomData<Platform>,
}

```

This struct is generic over a `Platform` type parameter, consistent with LiteBox's cross-platform abstraction strategy. The module is publicly re-exported through [`litebox/src/fs/mod.rs`](https://github.com/microsoft/litebox/blob/main/litebox/src/fs/mod.rs), making it available as `litebox::fs::nine_p`.

### Integration with the FileSystem Trait

The `nine_p::FileSystem` implements the same `FileSystem` trait used by `in_mem::FileSystem` and `tar_ro::FileSystem`. This trait defines standard operations like `open`, `read`, `write`, and `seek`, allowing user code to interact with 9P-mounted directories using identical syntax to local storage.

## Current Implementation Status

As of the latest source code, the LiteBox 9P protocol support remains a placeholder awaiting full implementation.

### Placeholder Methods in nine_p.rs

All trait methods in [`litebox/src/fs/nine_p.rs`](https://github.com/microsoft/litebox/blob/main/litebox/src/fs/nine_p.rs) currently contain `todo!()` macros:

```rust
impl<Platform: crate::sync::RawSyncPrimitivesProvider> FileSystem for FileSystem<Platform> {
    fn open(&self, path: &str, flags: OFlags, mode: Mode) -> Result<Fd, Error> {
        todo!()
    }
    
    fn read(&self, fd: &Fd, buf: &mut [u8], offset: Option<u64>) -> Result<usize, Error> {
        todo!()
    }
    
    // Additional methods (write, seek, close, etc.) follow same pattern
}

```

This skeleton establishes the API contract while the actual 9P wire protocol logic is being migrated from VSBox.

### Debug Workaround in litebox_runner_snp

Until the 9P protocol support is functional, [`litebox_runner_snp/src/main.rs`](https://github.com/microsoft/litebox/blob/main/litebox_runner_snp/src/main.rs) contains a debug-only workaround that pre-loads host files into an in-memory file system:

```rust
/// Pre-defined file paths to load from host for testing purposes.
#[cfg(debug_assertions)]
const HOST_FILE_PATHS: &[&str] = &[
    "/out/hello",
    "/out/efault",
    "/out/thread_exit",
    "/out/tcp_server",
];

#[cfg(debug_assertions)]
fn load_host_files_into_fs<Platform: litebox::sync::RawSyncPrimitivesProvider>(
    in_mem_fs: &mut litebox::fs::in_mem::FileSystem<Platform>,
) {
    // Creates /out, loads each file from the host via VSBox's "load_file_from_host"
    // call, and writes it into the in-memory FS.
}

```

The source code contains an explicit comment indicating this code will be removed after the 9P file system migration from VSBox is complete.

## Intended Usage of 9P Protocol Support

When fully implemented, LiteBox's 9P protocol support will enable mounting remote directories through the Plan 9 file system protocol. The intended usage pattern follows the standard LiteBox file system construction pattern.

### Creating a 9P-Backed File System

Developers will instantiate the 9P file system using the platform-specific constructor:

```rust
use litebox::{LiteBox, platform::Provider};
use litebox::fs::nine_p;

fn init_filesystem<P: Provider + Sync + 'static>(litebox: &LiteBox<P>) -> impl FileSystem {
    // Create the 9P filesystem (future implementation)
    let fs = nine_p::FileSystem::<P>::new(litebox);
    
    // Connect to the host-provided 9P server (example address)
    // fs.connect("tcp://127.0.0.1:5640").expect("cannot connect to 9P server");
    
    fs
}

```

### Combining with Other File Systems

The 9P file system can be layered with other storage backends using the `default_fs` helper on `LinuxShimBuilder`, allowing a fallback hierarchy:

```rust
let tar_fs = litebox::fs::tar_ro::FileSystem::new(litebox, tar_data);
let ninep_fs = init_filesystem(&litebox);

shim_builder.set_fs(
    shim_builder.default_fs(ninep_fs, tar_fs)   // 9P becomes the primary FS
);

```

### Performing File Operations

Once mounted, operations use the standard `FileSystem` trait interface:

```rust
let fd = ninep_fs.open("/etc/hostname", OFlags::RDONLY, Mode::empty())?;
let mut buf = [0u8; 128];
let n = ninep_fs.read(&fd, &mut buf, None)?;
println!("Hostname file ({} bytes): {}", n, std::str::from_utf8(&buf[..n])?);

```

## Migration from VSBox

LiteBox's 9P protocol support is explicitly designed as a replacement for the 9P client previously provided by VSBox. The architecture allows LiteBox to either import VSBox's existing client implementation or develop a native replacement that conforms to the same `FileSystem` trait interface.

The migration path involves:
1. Implementing the wire protocol logic in [`litebox/src/fs/nine_p.rs`](https://github.com/microsoft/litebox/blob/main/litebox/src/fs/nine_p.rs)
2. Removing the debug-only host file pre-loader from [`litebox_runner_snp/src/main.rs`](https://github.com/microsoft/litebox/blob/main/litebox_runner_snp/src/main.rs)
3. Updating `LinuxShimBuilder` configurations to use `nine_p::FileSystem` instead of in-memory workarounds

## Summary

- LiteBox defines a **placeholder 9P protocol support module** at [`litebox/src/fs/nine_p.rs`](https://github.com/microsoft/litebox/blob/main/litebox/src/fs/nine_p.rs) that implements the `FileSystem` trait but currently contains only `todo!()` stubs.
- The 9P implementation follows the **same trait-based architecture** as `in_mem::FileSystem` and `tar_ro::FileSystem`, ensuring API compatibility across storage backends.
- **Debug builds** currently use a temporary host-file pre-loader in [`litebox_runner_snp/src/main.rs`](https://github.com/microsoft/litebox/blob/main/litebox_runner_snp/src/main.rs) that will be removed once 9P support is functional.
- When complete, the 9P protocol support will enable **mounting remote directories** via the Plan 9 file system protocol without copying data into the sandbox's memory.
- The design allows **layering 9P with other file systems** using `LinuxShimBuilder::default_fs()` to create fallback hierarchies.

## Frequently Asked Questions

### What is the current status of 9P protocol support in LiteBox?

LiteBox currently contains a **placeholder implementation** in [`litebox/src/fs/nine_p.rs`](https://github.com/microsoft/litebox/blob/main/litebox/src/fs/nine_p.rs). The module defines the `FileSystem` struct and implements the required trait, but all methods contain `todo!()` macros indicating they are not yet functional. The code structure follows the same pattern as the working `in_mem` and `tar_ro` file systems.

### How will LiteBox use the 9P protocol once implemented?

Once fully implemented, LiteBox will use the 9P protocol to **mount remote directories** from a host or network server directly into the sandboxed environment. This eliminates the need to pre-load files into an in-memory file system. The 9P-backed file system will implement the standard `FileSystem` trait, allowing code to open, read, write, and seek remote files using the same API as local storage.

### Why does LiteBox have a debug-only file loader in litebox_runner_snp?

The [`litebox_runner_snp/src/main.rs`](https://github.com/microsoft/litebox/blob/main/litebox_runner_snp/src/main.rs) file contains a debug-only workaround that pre-loads specific host files into an in-memory file system. This temporary code exists **only until the 9P protocol support is migrated from VSBox to LiteBox**. The loader is wrapped in `#[cfg(debug_assertions)]` attributes and includes comments indicating it will be removed once `nine_p::FileSystem` is functional.

### Can the 9P file system be combined with other storage backends?

Yes, LiteBox's architecture allows **layering the 9P file system with other backends** such as `tar_ro::FileSystem`. Using the `default_fs` method on `LinuxShimBuilder`, developers can create a fallback hierarchy where the 9P file system serves as the primary storage, with other file systems providing default or fallback content. This pattern maintains the uniform `FileSystem` trait interface across all storage types.