Vulpine Linux

An independent collaboration between taylor and charlie under the baronscott consortium.

A portable, micro-installable, persistent, and transparent system.
Designed for standalone computing, micro-services or virtual environments - usable in daily-driving, edge and embedded systems.

Overview

Currently in a DOS-like state and an early-stage environment, it does however demonstrate core capabilities and sets the stage for coming development. As that development undergoes this README.md will change and adapt alongside it.

In an increasingly connected and security-conscious world, lightweight and modular operating systems are crucial for a range of applications and end-users. Vulpine Linux embodies this philosophy; by which we aspire to develop a minimal Linux-based system, optimised for USB boot-ability and persistent storage. From there you decide how your system, your "den" unfolds. Built, shaped, and expanded on your terms - we offer stable releases in which you can take in your own direction through our package manager, or compiling your own binaries.

Our goal is simply this; build a functional, minimal, environment with optional expansion. That way the system remains understandable from end-to-file-system-end allowing you to self-service with greater ease, and for us to maintain with simplicity in mind.

While the system is intentionally minimal out-of-the-box, containing only essential components such as C, Python, networking, etc, it provides a flexible platform for expansion.

You can see the steps-between-releases below which we've aptly named "phases" we refuse to announce a stable release, or new-phase until we're certain of those feature-sets being met in a reliable and reasonable way. This ensures we aren't pushing half-baked systems into a stable title without proper mindfulness and clarity to the end-users.

Eventually transforming Vulpine Linux into a full featured, though respectfully minimal, multi-user operating system capable of supporting graphical interfaces (optional), network services, and applications with some advanced security features even if light-and-small.

Currently in the system you'll find:

• Custom compiled Linux kernel optimised for fast boot and low resource usage.
• GRUB bootloader for loading the kernel and initramfs.
• Persistent ext4 filesystem support for stable data storage.
• Minimal multi-user environment with basic userspace tools.
• Portable running on USB, installable to disk, or usable as a virtual machine on QEMU via ISO.
• Built from source for transparency, modularity, and full control.
• Basic networking support for simple connectivity, right now taking advantage of QEMU host.

This leaves you with a minimal, user-and-shell environment of which old-school DOS users and terminal depth-divers might be used to seeing day-by-day.

Getting Started

Download the repository from our origin with:

git clone https://forge.dnsrail.org/vulpinelinux/vulpinelinux.git --depth 1 && cd vulpinelinux/

If you plan to fork-and-contribute (as guided later) you'll be best off forking our codeberg mirror remembering to sync between Vulpine Linux releases to ensure you're always contributing on the latest version. This is explained later under "Contributing".

Once you've pulled from origin or your fork, you'll have the public open source for Vulpine Linux - congratulations! From here you can self-compile with ./build.sh which may require the use of sudo, we use this because we want to ensure the repository in-and-of itself is as small as possible for those on restrictive, smaller networks - less bloat, happier bandwidth.

Build Requirements

⚠️ This script assembles the system but does not build the kernel or userspace automatically. bzImage is already provided, and custom userspace binaries are placed into rootfs, this all you need to get started.

The build script assumes the following tools are installed:

• Linux environment (or WSL on Windows).
• cpio.
• gzip.
• grub-mkrescue (grub2).
• xorriso.

Additionally, the Linux kernel (bzImage) is already compiled and present in: ./linux/arch/x86_64/boot/bzImage - you will be expected to build around this.

From there you can launch it using QEMU while being in the vulpinelinux directory.

qemu-system-x86_64 \
  -m 2G \
  -smp 4 \
  -drive file=vulpine-linux.qcow2,format=qcow2,if=virtio \
  -cdrom vulpine-linux-embedded-indev.iso \
  -boot d \
  -display gtk \
  -vga virtio \
  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=net0

Right now there is only one account that exist out-of-the-box: root:root - root permissions and full-file system access by design, and can be considered the "admin" user.

Once in the system you'll be in a live-boot media, to have persistence and full-installation follow these steps:

• Launch the QEMU command provided above.
• Run ../installvulpine.sh, this will install to /dev/vda1 which should be your virtual disk image produced with the build.sh.
• Shutdown the QEMU instance.
• Relaunch with the following:

qemu-system-x86_64 \
  -m 2G \
  -smp 4 \
  -drive file=vulpine-linux.qcow2,format=qcow2,if=virtio \
  -boot d \
  -display gtk \
  -vga virtio \
  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=net0

This will then be your full-system installation with true persistence.

Contributing

Anti-AI Clause

The project adopts a strict stance against artificial intelligence integration, aligning with the principles outlined by NotByAI and Linus Torvalds’ pragmatic approach that declares the human responsibility element:

"You, the human submitter, bear full responsibility and accountability for reviewing the AI-generated code, ensuring license compliance, and for any bugs or security flaws that arise."

Contributions must be human-led, reviewed, and understood by the submitter.

Code that cannot be clearly explained, maintained, or trusted will not be accepted. Low-quality or unverified contributions will be rejected (sign your commits - there is no excuse in 2026 not to sign) the user ideally should match your signature but the main part is signing and verifying.

We want Vulpine Linux as a system, and a distribution point for open-source code, to be human-first. This will ring true for contributions made across the scope of Vulpine Linux and the systems, software and infrastructure we go on to develop or use first-hand, such as our Package Manager and infrastructure is be dependent on DNSRail and mirrors like Codeberg, wherever possible we will support human-first.

How to Contribute

We want to start by saying thank you for considering a contribution that aligns with Vulpine Linux's philosophy. This is a low-level, from-scratch system - so contributions should reflect an understanding of how the system is built and why it is built in this way.

As such, we kindly ask that you focus on one-branch per feature or fix, and do that single branch feature-or-fix well. This way we can ensure proper-steady and audit-able contributions rather than monolithic merge requests that risk going against the philosophy we aspire for.

1. Fork and Clone

Fork the repository and clone it locally:

git clone https://codeberg.org/YOUR-USERNAME/vulpinelinux.git && cd vulpinelinux/

⚠️ Commits made to the main repository will be rejected, you have been warned - this is reserved for core, high-priority pushes only from the core Vulpine Linux team, these branches on main are then deleted post-merge. All commits must be done through forking and via Codeberg unless you're one of the core Vulpine Linux team.

2. Make Your Changes

Before making changes, create a new branch.

If its a feature (such as adding, updating or changing an existing software) git checkout -b feature/your-feature-name

An example would be git checkout -b feature/csh-config

If your goal is to work on an issue you should use: git checkout -b fix/issue-reference-name

An example would be git checkout -b fix/expand-alias-overflow

Your changes must be made in a dedicated branch (e.g. feature/your-feature-name)

Work within the existing structure:

• rootfs/ - userspace (init, shell, configs).
• busybox/ - system utilities (omitted at this time, this is a reference).
• linux/ - kernel source (omitted at this time but where you'll find bzImage).
• iso/ - boot structure (GRUB, kernel, initramfs).
• build.sh - runs the full build including compiling GRUB.

Examples of valid contributions:

• Improvements to init or boot process.
• New statically compiled tools (must run in initramfs). and that contribute towards the next stable-release expectations.
• Kernel or otherwise config optimisations.
• Networking or system stability fixes.
• Contributions towards the next stable-release expectations.
• Documentation improvements, these must be British-English.

3. Follow Project Constraints

• All binaries must work in a minimal initramfs environment.
• Prefer static builds where possible. otherwise supply the dynamic libraries and during Pull Request list ones provided.
• Avoid unnecessary dependencies (especially glibc-heavy ones).
• Keep the system lightweight and understandable - our article here explains more
• Meet "Pull Request Expectations".

4. Test Your Changes

Rebuild and test:

./build.sh

Run in QEMU:

qemu-system-x86_64 \
  -m 2G \
  -smp 4 \
  -drive file=vulpine-linux.qcow2,format=qcow2,if=virtio \
  -cdrom vulpine-linux-embedded-indev.iso \
  -boot d \
  -display gtk \
  -vga virtio \
  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=net0

Follow the flowchart as a general guide:

flowchart LR
    A[Build-and-boot] --> B{Is your implementation working properly?}
    B -->|Yes| C[Great, take a screenshot and write documentation]
    B -->|No| D[Debug and try again]
    C --> E[Push to fork, pull request, supply docs, submit]
    D --> B

Ensure:

• System boots cleanly
• No kernel panics
• Your feature works as intended
• You haven't inadvertently broken something else
• It can be built reliably time-again using ./build.sh

Avoid hard coding anything that risks being re-written by ./build.sh notably GRUB.

⚠️ Dynamically linked binaries will not work unless all required libraries are included, you are responsible for having tested your commit works via the previous steps

5. Pull Request Expectations

• You've made the feature in git checkout -b feature/your-feature-name or similarly if its an issue fix as git checkout -b fix/issue-reference-name on your own fork, not on the main repository

• You must detail in at least one paragraph (short if you prefer) what your submission is resolving; describe what you changed and why, and how your code functions cleanly. You can keep it simple, but it must be understandable.

If we do not believe you wrote it, or understand it for yourself - it will be rejected.

• Include any relevant logs or screenshots if applicable for documentation purposes.

• Where possible include a reference link or documentation, so that others can learn from you and the project.

"Using auto-ai to make submissions, pushing clearly AI-generated code, repeated low-quality or unreviewed submissions may result in restricted contribution access. We are a human-first endeavour, we understand AI can be found in the IDE through to documentation in real-life and we cannot stop this but the more we minimise it here, in our project, the happier we all are." ~Charlie

You can then push your branch to your fork and open a Pull Request against the main repository ensuring your PR description follows the expectations outlined above, remembering to sign your commit we will reject any that are not signed.

Bare in mind when providing a -m for messaging to keep it short-and-simple for example git commit -m "patch for fixing {issue}", no one wants clunky and excessive messages.

6. Review Process

All contributions are:

• Reviewed manually.
• Tested for stability and compatibility.
• Evaluated for alignment with project philosophy.

Submissions that cannot be clearly explained or maintained will be rejected. This is true for unsigned commits or those submitted on/to the main repository - it must go through your fork, and Pull Requested. We cannot overstate this enough. Vulpine Linux is built step-by-step with intent so contributions should reflect that same mindset and set the bar for other developers to come after. We appreciate strongly well written and proper commits - it matters massively for reference and professionalism both on your part and ours.

FAQ

What is Vulpine Linux based on?

Vulpine Linux is built directly on the Linux kernel and a minimal userspace constructed primarily around BusyBox. It is not based on any existing distribution (such as Debian, Arch, or Alpine), but instead follows a from-scratch approach where each component is selected, compiled, and integrated manually. This helps us achieve our philosophy by building intentionally.

The system uses:

• A custom-compiled Linux kernel.
• A BusyBox-based minimal userspace.
• A handcrafted initramfs.
• GRUB for bootloading.

This approach ensures full transparency and control, at the cost of requiring manual configuration and compilation.

Does it have a package manager?

No - not currently.

Vulpine Linux is still in an early stage where software is added manually by compiling and integrating it directly into the root filesystem. This keeps the system minimal and avoids unnecessary complexity during this initial and vital stage.

A package manager is planned for future development and will be git-cloned from another repository into the system during ./build.sh, likely built through the DNSRail ecosystem. The goal is to maintain the project’s philosophy of transparency and control, while making software management more practical too.

What is Charlies Vulpine Shell? CVSH

Charlie's Vulpine Shell (CVSH) is a custom shell developed specifically for Vulpine Linux but can be used on other distributions such as Debian, and Arch. It is designed to be lightweight, simple, and tightly integrated with the system’s minimal environment. Though the standalone exists for public user on other systems.

Unlike full-featured shells like Bash or Zsh, CVSH focuses on:

• Minimal dependencies.
• Static compilation compatibility.
• Direct control over execution flow.
• Simplicity over feature bloat.

It serves as both a functional shell and a learning tool, forming part of the system’s identity and long-term direction.

Why does Vulpine Linux feel "DOS-like"?

This is intentional. The current environment is minimal by design, providing only the core components needed to boot, log in, and interact with the system. You can mount disks and drives for persistence.

The DOS-like feel reflects:

• A simple multi-user terminal environment.
• Minimal abstraction.
• Direct interaction with system tools.

This serves as a foundation to build upon rather than a finished user experience. We know we're a long way from finished but, it does provide something and even in the final system a full graphical-user-interface will remain entirely optional.

Why are most binaries statically compiled?

Because Vulpine Linux runs from an initramfs at this time with no full userspace or dynamic linker environment, statically compiled binaries ensure that programs can run without relying on external shared libraries. The more we "own" the full-stack the greater sense of security and control we adopt into the system.

This improves portability and reliability, especially in early-stage or embedded environments too. If you make a commit that uses dynamic you're responsible for supplying the binaries, consider using ldd to see which are necessary.

Why doesn’t some software work out-of-the-box?

Many standard Linux applications assume:

• A full glibc environment.
• Dynamic libraries.
• A complete filesystem hierarchy.

Vulpine Linux intentionally avoids some of these for now. As a result, software must often be adapted or compiled specifically for this environment.

Why use BusyBox?

BusyBox provides a wide range of essential Unix utilities in a single compact binary. This makes it ideal for minimal systems like Vulpine Linux, where space, simplicity, and control are priorities.

Can I use this as a daily operating system?

Not yet, not in the traditional sense.

Vulpine Linux is currently leaving the proof-of-concept stage and becoming a truly built-for-daily-use system even if minimalist. While functional, it lacks many features expected from a full desktop or server OS right now.

The long-term goal is to evolve into a more complete system, but for now it is best suited for experimentation, learning, and development.

Why does networking behave differently in QEMU?

By default, QEMU uses user-mode networking (NAT), which:

• Assigns the VM an internal IP (e.g. 10.0.2.15).
• Prevents direct inbound connections.
• QEMU NAT means the VM will not appear as a device on your local network.

To access services like SSH, port forwarding must be used with QEMU. This is a limitation of the virtualisation setup, not Vulpine Linux itself but we welcome contributions that help us adopt a wider set of virtual machines and can help develop the networking so it works appropriately with wired, and wireless, so it can get a "true" IP from DHCP.

What makes Vulpine Linux different from other minimal distros?

Vulpine Linux isn't just minimal - it is intentional.

Rather than stripping down an existing system, it is being built piece-by-piece with:

• Full control over every component.
• No hidden dependencies at its core.
• A focus on understanding, over convenience.
• Bridging away from all-in-memory unlike some other minimalist systems.

As much as its a system, it is a process too and a testament against other operating systems. Instead of just forking an existing distro and slapping on a fancy new screen. We took the Linux kernel and built on top from nothing. We aren't forking Debian, we aren't forking Arch. We're building bone and sinew from as scratch as we could get and with minimalism-by-design.

We want Vulpine Linux to feel like its truly yours in the end - we supply the minimalist system, you build your own den onto it with the tools we provide... Even if it'll take a while for us to get there.

What are the current limitations?

• No package manager
• Limited hardware support (primarily tested in QEMU).
• Minimal userspace (BusyBox-based).
• No dynamic linking environment.

Any "stable" release will mean we (the core team) have reliably reached expectations for stable build designation; we are designing intentionally and the Vulpine Linux team refuse to rush or meet deadlines - we want to be certain when we say something is stable that we've ran through it more than a dozen times. Intent, respect to the system, the craft, and time taken - is vital.

Support

For support, you can reach out on discord, or InTheMansion irc channels #lobby, or #vulpinelinux.

License

Vulpine Linux © 2026 by BaronScottConsortium is licensed under:

Creative Commons Attribution-ShareAlike 4.0 International This applies to Vulpine Linux developed systems and operating system and is not intended to supersede licensing applied to tools our operating system is dependent upon. All original licenses apply where ours cannot apply.

This license requires that reusers (you) give credit to the creator (us). It allows reusers (you) to distribute, remix, adapt, and build upon the material in any medium or format, even for commercial purposes. If others remix, adapt, or build upon the material, they (you) must license the modified material under identical terms.

• Credit must be given to us, the creators.
• Adaptations must be shared under the same terms.

How do we give credit?

This can be given clearly on your website, or beside the Downloads or a repository-fork. So long as it apparent in some reasonable - but fair - fashion that you've distributed, remixed, adapted, and/or built upon Vulpine Linux.