# xlings: version-pinned toolchains and SubOS sandboxes without root

> xlings is a C++ package infrastructure that installs any version of any tool, keeps several versions side by side, and runs them inside named SubOS environments with their own tools, home and policy. It advertises OS-like isolation and a decentralised package index, and it is frank that on macOS and Windows its sandbox flag is not a security boundary, only a home directory override.

**openxlings/xlings** — Universal package infrastructure with OS-like SubOS isolation - Multi-version · Rootless · Decentralized Index · Agent-ready.

- Repository: https://github.com/openxlings/xlings
- Website: https://index.xlings.org
- Stars: 615 · Forks: 50
- Language: C++
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/openxlings-xlings

## What xlings is, in the project's own framing

The tagline is dense: Universal package infrastructure with OS-like SubOS isolation, Multi-version, Rootless, Decentralized Index, Agent-ready. And then one sentence that says the practical thing: one tool to install any version of anything, run it without root, and isolate it like an OS of its own, on Linux, macOS and Windows.

Each of those four words is a design commitment rather than a slogan.

Multi-version means any number of versions can be installed side by side, and N environments share one copy of each payload, so a team with three projects on three compiler versions stores the compiler once and points each environment at the version it needs. The core command set is short: install, use, search, list, with the version optional on install and the switch being a separate act from the install.

Rootless is the constraint that shapes the sandbox story, because you cannot install system-wide without privileges, so the mechanism is an environment rather than a prefix on the system path.

Decentralized Index means packages come from official, third-party or self-hosted indexes, and the package format, called xpkg, is the same for binaries, scripts, configs and SubOS bases alike. The repository ships an official package index at xim-pkgindex and documents how to host your own, which is the part that makes the decentralised claim concrete rather than aspirational.

Agent-ready is the newest of the four claims and the least documented in the README itself. There is an xlings subos exec command, exit codes that mean something, an XLINGS_AGENT_MODE=1 environment variable, and an NDJSON interface called xlings interface. The README tells an agent to run xlings agent usage, because a complete guide written for agents ships with xlings.

The primary language is C++, the licence is Apache-2.0, the last push was on 2026-10-20, and the project publishes dated releases such as v2026.10.20.3, with three of them on the same day. The homepage is index.xlings.org.

## Installing it, and the four commands that matter

Installation is a single piped script on each platform. On Linux and macOS:

```bash
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash
```

and on Windows in PowerShell:

```powershell
# Windows (PowerShell)
irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.ps1 | iex
```

The README also points at a build from source document for anyone who would rather compile it, and the repository tree has the expected shape for a project of this size: an apps/ directory, a src/ directory, a modules/ directory, a luban/ directory, tools/, config/, docs/, examples/, tests/, and a .xlings.json file at the root that configures the tool itself. There is an .agents/ directory and an AGENTS.md, which is consistent with the agent-ready claim being a first-class part of the design rather than an afterthought.

The working command set is four lines:

```bash
xlings install gcc@16 node@24 cmake   # install (version optional)
xlings use gcc@16                      # switch the active version
xlings search python                   # search packages
xlings list                            # what is installed
```

That is a deliberately small surface, and the ordering of the four tells you the intended flow. Search before install, install with the version if you care, list to see what you have, and use to switch the active version. The version suffix syntax, a name and a version joined by an at sign, is the one piece of syntax you have to learn.

There is a fifth command for repair, and it is the one that distinguishes this from a version manager in the usual sense. xlings self doctor --fix checks the tool's own state and repairs it in one run, alongside xlings self update. A package manager that has installed hundreds of versions across dozens of environments accumulates state, and the ability to check and repair that state in one command is what keeps the whole thing usable over time.

## Versions and projects: the same payload, different environments

The scenario the README calls several toolchains, no conflicts is the core use case, and it is one command to set up:

```bash
xlings install gcc@16 gcc@11 node@24
xlings use gcc@11        # switch back any time; both stay installed
```

Both compilers stay installed and the switch is reversible at any time, which is the point. The traditional alternatives are either a system-wide version manager that rewrites paths globally, so two projects cannot have different versions at once, or a container per project, which is heavier than most people want for a build tool.

The project scenario extends the same idea to a whole team, and it does so with a workspace declaration. The example given is a JSON object naming a workspace, with an xmake version as a plain string, a gcc version keyed by linux, and an llvm version keyed by macosx. Then a single command in the project directory installs the project's own SubOS with the declared versions:

```bash
cd my-project/ && xlings install     # the project's own SubOS, the declared versions
```

So a project carries its toolchain requirements as versioned data, the same way a lockfile carries dependency versions, and the environment it produces is named and shareable. The documentation index has a whole section on projects, which tells you this is a first-class scenario rather than a feature of the environment model.

The model behind that is that a SubOS is a named environment with its own tools, home and policy, ranging from a simple PATH switch to a rootless sandbox with a private network. The policy element is what makes it an operating system analogue rather than a wrapper script: a SubOS can be given a set of rules about what it may reach, and the machine interface exists so an agent can ask what a SubOS requests and what the host grants.

For an organisation, the interesting consequence is reproducibility. A project that declares its compiler versions can be built on a laptop, in CI and on a colleague's machine with the same result, without every developer maintaining a toolchain by hand.

## SubOS, and the honest limit of the sandbox on macOS and Windows

The agent and untrusted code scenario is the one the README spends most space on, and it is also where the caveat is sharpest.

The commands look like this:

```bash
xlings subos new agent-ws --sandbox=private      # isolation is declared once, here
xlings subos exec agent-ws -- python run.py      # every entry is that sandbox; its own exit code
xlings subos use agent-ws                        # or a shell inside -- no flag needed
```

Isolation is declared once, when the environment is created, and then every entry point into that environment inherits it. xlings subos exec runs a command inside the sandbox and returns the sandbox's own exit code, and xlings subos use opens a shell inside it with no flag needed. The design point is that isolation is a property of the environment rather than something each caller has to remember to ask for.

The platform table is the important part. On Linux x86_64 and aarch64, the sandbox isolates filesystem, processes, network and identity, using bwrap. On macOS 14 and later on arm64, it isolates only the home directory. On Windows x86_64, it isolates only the user profile directory.

And the README is explicit about what that means. On macOS and Windows the sandbox is not a security boundary, and you should use an OS sandbox or a VM for code you do not trust. The command xlings subos status shows what a SubOS asks for and what the machine actually gives it, which is the right way to expose that difference rather than leaving it implied.

This is a defensible position rather than a hole in the design. A full bwrap-based isolation stack is a Linux facility, and the project states plainly that the guarantee is weaker elsewhere and tells you what to use instead. What it does mean is that the same workflow gives you different security properties depending on the operating system, and a team running untrusted code on a Mac should not assume the Linux behaviour transfers.

## Luban, the OS model built on top of xlings

Luban is the part of the project that pushes the OS analogy furthest, and it is distributed as packages of its own.

```bash
xlings install luban luban-os    # the luban command and the Luban OS window
luban new box                    # a Linux system, no root needed (Luban Core)
luban enter box                  # its shell; exit to leave
luban-os                         # or open the Luban OS window
```

The README describes it as a whole Linux userland in one command, rootless, and then boot it as a machine. The command luban new box creates a Linux system with no root needed, and luban enter box gives you its shell. The luban-os binary opens the Luban OS window, which is the desktop version of the same thing.

The model underneath has four properties according to the README: environments are made from editions, they are rolled back by generation, they are exported as images, and they are shown in the Luban OS window with their desktop. So a system is a composition of editions, each generation can be reverted, and the whole thing can be exported as a bootable image.

The editions have sizes, with a tiny edition and a desktop edition, and the same system can run in a different mode as a machine with its own kernel. The documentation index has a dedicated section for it, with a quick start and a document on the desktop, and the repository has a luban/ directory at the top level alongside a docs/luban/ directory.

The reason to run a Linux userland inside a tool that already runs on three operating systems is portability. A developer on Windows, a build server on Linux and a colleague on macOS can all be handed the same exported system and get the same environment, without any of them needing root or a container runtime. That is the same argument as the version pinning scenario, applied to whole systems rather than to single tools.

The related project Luban is listed in the used-by line at the top of the README, alongside MCPP, described in the ecosystem section as a modern C++ toolchain distributed through xlings, and the repository carries an mcpp.toml file at the root.

## What to check before relying on it

Three things are worth knowing before you put this in front of a team.

The first is the sandbox guarantee, and it is platform dependent in a way that matters. The Linux build gives you filesystem, process, network and identity isolation through bwrap, while macOS and Windows give you a home directory override and the README tells you plainly not to treat that as a boundary. If your use case involves running code you do not control, that difference decides whether the tool is usable for the job.

The second is the package supply chain. Packages are binaries, scripts, configs and SubOS bases in one format, fetched from an official index, a third-party index or one you host yourself. The decentralised index model is genuinely useful for air-gapped or organisation-controlled setups, and the documentation covers indexes and mirrors as well as hosting an index. It also means the trust question moves from a single source to each index you add, so which indexes you configure is a decision with security weight.

The third is the agent story, which is the most novel part and the least documented in the README itself. The xlings agent usage command exists and a full guide ships with the tool, and the machine interface is a named contract with its own specification document, but the README does not describe it in detail. If you are building an agent workflow on top of this, the agents and machine interface documents are where the actual work is.

The documentation structure itself is a signal. The index in the README is organised as Start, Use, SubOS, Extend, Contracts and Luban, with a separate section for xlings itself covering build from source, architecture and release. Twenty or so separate documents with generated command reference and specifications is a documentation posture that suggests the project expects to be extended, and the contributing links point at adding packages, hosting an index, authoring a SubOS template and improving the docs, which is a good sign for a project whose main claim is extensibility.

## Conclusion

Adopt xlings if your team runs several projects that need different compiler or runtime versions, if you want a single tool that installs any version of anything without root, or if you want agent workflows that run inside a declared environment with a meaningful exit code. Do not adopt it as a security boundary on macOS or Windows, where the sandbox only overrides the home directory, and do not assume the agent interface is stable, since the machine interface and the agent guide are the newest and least documented part of the project. Before you commit, read the SubOS and sandbox and policy documents, decide which package indexes you will trust, and start with the project workspace declaration, because the declared-version workflow is the part of the design that pays for itself immediately.

## FAQ

### What is xlings?

It is a universal package infrastructure for Linux, macOS and Windows that installs any version of any tool, keeps several versions side by side, and runs them inside named SubOS environments with their own tools, home and policy. It needs no root, and its tagline lists multi-version, rootless, decentralised index and agent-ready as the design commitments.

### How do I install xlings?

On Linux and macOS run the piped quick_install.sh script, and on Windows run the quick_install.ps1 script through irm and iex in PowerShell. There is also a build from source document, and the repository contains an apps/ directory, a src/ directory, modules/, tools/ and a .xlings.json configuration file.

### Does the xlings sandbox isolate untrusted code on macOS and Windows?

Not fully. The platform table states that on Linux x86_64 and aarch64 the sandbox isolates filesystem, processes, network and identity through bwrap, while on macOS 14+ arm64 and on Windows x86_64 it isolates only the home or user profile directory. The README says plainly that on macOS and Windows it is not a security boundary and that you should use an OS sandbox or a VM for code you do not trust.

### What are SubOS environments in xlings?

They are named environments with their own tools, home and policy, ranging from a PATH switch to a rootless sandbox with a private network. Isolation is declared once when the environment is created, and every entry point inherits it, with xlings subos exec running a command inside the sandbox and xlings subos use opening a shell there.

### What is Luban in relation to xlings?

Luban is the OS model built on xlings, distributed as packages of its own. It builds a whole Linux userland in one command without root, with environments made from editions, rollback by generation, and export as bootable images, and there is a desktop version, the Luban OS window.

## Sources

- [License: Apache-2.0](https://github.com/openxlings/xlings/blob/main/LICENSE)
- [openxlings/xlings on GitHub](https://github.com/openxlings/xlings)
- [Project website](https://index.xlings.org)
- [README](https://github.com/openxlings/xlings/blob/main/README.md)
- [Releases](https://github.com/openxlings/xlings/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openxlings-xlings