Azathothas/chroot-win

wip

★ 0Forks 0RustGitHub ↗Compare

README

chroot-win

A true chroot/proot for Windows, in userspace. No kernel driver, no administrator rights, no WSL, no third-party crates. 0BSD.

Status: early. The design is settled and verified; the portable core is built and tested; neither execution backend is finished. See PROTOTYPE.md — the single, standalone document that specifies the whole project, records what is verified, and says exactly where to start.

chroot-win [OPTION]... NEWROOT [COMMAND [ARG]...]

Same shape, flags, defaults and exit codes as coreutils chroot(8), plus proot(1)'s -b/--bind, -w/--cwd, -0/--root-id, -i/--change-id, -R, -S and friends. It is called chroot-win, never chroot, so it cannot shadow an MSYS2 or Cygwin chroot already on PATH.

Goals it will not trade away

  1. CLI parity with coreutils chroot(8) — nothing new to learn.
  2. proot(1)'s extra flags on top, where they do not collide.
  3. Basic safety: rm -rf / inside the jail must not touch the host.
  4. Pure userspace, so it is portable everywhere Windows runs.
  5. The binary is chroot-win.
  6. The proof of concept runs Alpine on a stock GitHub windows-latest runner — no WSL, WinFSP, Podman, MSYS2 or QEMU, at all.

Build and test

cargo test                                    # 149 tests; runs on any host
cargo check --target x86_64-pc-windows-msvc   # typecheck the Windows code
cargo run -p cw-cli -- probe                  # verify the design on a real machine
cargo run -p cw-cli -- --help

Most of the tree is deliberately host-independent — path translation, metadata encoding, ELF parsing, gzip, CLI parsing — so it is developed and tested on Linux CI, with only the NT calls behind #[cfg(windows)].

Layout

Crate What
cw-core Errors and Linux errnos, the guest→host path translator, WSL-compatible metadata encoding, safety guards
cw-nt The NT/Win32 surface: per-process device map, extended attributes, reparse points, case sensitivity, and probe
cw-rootfs gzip/DEFLATE; rootfs fetch and extraction to come
cw-elf ELF64 parsing, the initial process stack, the syscall table
cw-cli The chroot-win binary

reference_attachments/ holds stripped prior art, read-only. It is evidence, not a dependency.

License

0BSD — public-domain-equivalent, no strings.

Contributors

Azathothasclaude

Issues