xlings
Universal package infrastructure with OS-like SubOS isolation.
Multi-version · Rootless · Decentralized Index · Agent-ready.
Website | Docs | Package Index | Forum
中文 | English
Used by: MCPP · upcoming Luban Linux
Why xlings?
One tool to install any version of anything, run it rootless, and isolate it OS-like — across Linux, macOS, and Windows.
"Supported" is three separate questions, so here are three columns. A platform
xlings runs on is not automatically a platform every package has an artifact
for, and neither of those says anything about how much isolation --sandbox
can actually give you.
| Platform | xlings release | Package coverage | subos --sandbox isolates |
|---|---|---|---|
| Linux x86_64 | ✅ published | full | the filesystem (bwrap / proot) |
| Linux aarch64 | ✅ published | partial — many recipes only publish an x86_64 artifact | the filesystem, once a backend is available for the arch |
| macOS 14+ arm64 | ✅ published | partial — some recipes ship x86_64 only | only $HOME |
| Windows x86_64 | ✅ published | partial | only %USERPROFILE% |
Package coverage is a property of the recipe, not of xlings: xlings install
refuses a target only when the recipe enumerates its architectures and yours
is not among them. When a recipe ships a single artifact it is installed and
you are told the recipe could not confirm your architecture.
macOS and Windows
--sandboxis not a security boundary. It redirects the home directory so tools write their dotfiles somewhere isolated. It does not contain the filesystem, the network or processes. Use an OS sandbox or a VM to run code you do not trust.
→ How xlings compares to apt / nix / docker
Core capabilities
- Universal package infrastructure — binary / script / config / subos / tutorial, all as xpkg
- Multi-version coexistence — N versions side-by-side; version-view + ref-counting (N envs ≈ 1× storage)
- 3-level SubOS isolation — shell (env switch) / FS (bwrap/proot, rootless) / image (ext4, root)
- Decentralized package index — official + 3rd-party + self-hosted; resource servers for binary mirrors
- JSON event interface —
xlings interface(NDJSON) for AI agents, CI, and 3rd-party tooling - Self-diagnosing —
xlings self doctor --fixchecks the four state layers and repairs them in one run
Quick Start
Install — Linux / macOS
curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash
Install — Windows (PowerShell)
irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.ps1 | iex
xlings install gcc@16 node@24 cmake # install (version optional)
xlings use gcc@16 # switch active version
xlings search python # search packages
xlings list # list installed
Let an AI agent install & explain it
Paste this to any AI agent (Claude, Codex, OpenCode, …):
Read the README of https://github.com/openxlings/xlings and install xlings on my machine.
- Linux/macOS: curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash
- Windows: irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.ps1 | iex
Then run `xlings agent usage` and follow it to show me how to use xlings.
xlings ships a built-in agent guide — once installed, any agent can self-learn the full workflow:
xlings agent # overview + skill list
xlings agent usage # complete usage guide written for LLM agents
Usage scenarios
🛠 Multi-version toolchains, one command everywhere
Install any version of anything and keep several side by side — switch instantly, no conflicts, no sudo. The same commands work on Linux, macOS, and Windows.
xlings install gcc@16 gcc@11 node@24 cmake
xlings use gcc@11 # switch back anytime — both stay installed
📦 Reproducible project environments, consistent across OSes
Commit a .xlings.json that declares per-platform versions. Each project gets its own isolated SubOS, so teammates and CI — on any distro or OS — land in the exact same environment, without touching the host or other projects.
{
"workspace": {
"xmake": "3.0.7",
"gcc": { "linux": "16.1.0" },
"llvm": { "macosx": "20.1.7", "windows": "19.1.0" }
}
}
cd my-project/ # entering the dir activates the project SubOS
xlings install # installs the declared versions, project-local
🤖 Agents & untrusted code in an isolated SubOS
On Linux, run agents inside a rootless filesystem-isolated SubOS. On macOS and Windows, SubOS redirects the home directory but does not contain untrusted code; use an OS sandbox or VM when that boundary is required.
xlings subos new agent-ws --from subos:dev-env@latest
xlings subos use agent-ws --sandbox # enter the isolated world
xlings subos use agent-ws --sandbox --cmd "python run.py" # or one-shot exec
🩺 Upgrade and repair, without hand-editing state
Upgrade the client, then let xlings check its own four state layers — workspace, version database, shims, payloads — and repair what it finds. One run; the report you read is the state after the repairs, and every command it prints is one you can paste.
xlings self update # upgrade xlings itself
xlings self doctor # read-only check (exit 0 = healthy)
xlings self doctor --fix --dry-run # preview the repairs
xlings self doctor --fix # repair
Documentation
Guides, design notes, and specs live in docs/.
| Area | Docs |
|---|---|
| Get started | Multi-version · Project env · SubOS & Agent · Custom index · Self-management · Build from source |
| Architecture | System overview |
| Design | SubOS-as-XPKG · xvm versioning · SubOS isolation · Index ecosystem · Interface protocol |
| Spec | xpkg manifest v1 · .xlings.json schema · Interface NDJSON v1 |
Ecosystem
| Project | Role |
|---|---|
| MCPP | Modern C++ build toolchain ecosystem — distributed through xlings |
| Luban Linux | Upcoming Linux distribution using xlings as system-level package manager (link when published) |
| xim-pkgindex | Official package index — 60+ packages and growing |
Community
- Forum: forum.d2learn.org/category/9/xlings
- QQ Groups: 167535744 / 1006282943
- Issues: github.com/openxlings/xlings/issues
Contributing
Contributors