Project URL: https://github.com/openxlings/xlings

Note: Currently, the Linux experience is better; adapting gradually on Windows/macOS.

Users: MCPP · Upcoming Luban Linux

Why choose xlings?

vs other tools

Quick Start

Installation

Linux / macOS

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

Windows (PowerShell)

irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.ps1 | iex

Let your AI Agent help you install

Copy the following content to your AI agent (Claude / Codex / OpenCode, etc.):

帮我安装 xlings 包管理器。
- 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
项目地址: https://github.com/openxlings/xlings

Try Multi-Version

xlings install gcc@16 node@24 cmake
xlings use gcc@16        # 切换当前版本
gcc --version            # gcc 16.x

Core Concepts

Features

1. 📦 Universal Package Management Infrastructure — binary / script / config / subos / tutorial are all xpkg
2. 🔀 Multi-version Coexistence — N versions of the same tool coexist; version view + reference counting (N environments ≈ 1 copy storage)
3. 🏗️ Three-level SubOS Isolation — shell (env switching) / FS (bwrap/proot, no root required) / image (ext4, root required)
4. 🌐 Decentralized Package Index — official + third-party + self-hosted repositories; resource server for binary mirror distribution
5. 🤖 JSON Event Interface — xlings interface(NDJSON protocol) for AI agents, CI, and third-party tools

Scene

🛠 Toolchain — Multi-version without sudo

xlings install gcc@16 gcc@11 cmake node@24
xlings use gcc@16        # 即时切换
xlings use gcc@11        # 切回 11, 互不干扰

📦 Project — Seamlessly Enter Project-level SubOS

When you enter a project directory that contains .xlings.json, xlings automatically and transparently activates the project-level SubOS — You and your team work in an isolated environment without any manual operation. All dependencies are in the project's own SubOS.

{
  "workspace": {
    "xmake": "3.0.7",
    "gcc": { "linux": "16.1.0" },
    "llvm": { "macosx": "20.1.7" }
  }
}

cd my-project/           # 自动进入项目 SubOS
xlings install           # 依赖装进项目级隔离环境
xmake build              # 一切正常运作, 与宿主机隔离

clone → cd → build. The team and CI environments are completely consistent, no manual activation needed.

🤖 Agent — Agent runs in its own lightweight world

xlings lets you put the agent (codex / claude / opencode, etc.)Runs inside SubOS — The agent has full permissions within the isolated environment, and the host machine is completely secure.

Why this matters:

• 🔓 The agent has greater permissions inside SubOS — installing packages, modifying files, running arbitrary code — without harming the host.
• 🔁 The same agent tool, multiple instances on one machine — each SubOS has its own independent configuration (normally, a single Codex/Claude account can only run one instance).
• ⚡ Lightweight — not a heavyweight VM or container, only namespace isolation.

Running agents in SubOS:

# 创建 SubOS(从 base 环境 fork,或自己从零配置)
xlings subos new claude-workspace --from subos:dev-env@latest

# 进入 SubOS — Agent 在这里面运行,拥有完全控制权
xlings subos use claude-workspace --sandbox
# → 现在你在 agent 的世界里
# → 在这里启动 claude / codex / opencode
# → 它们可以自由安装、修改、实验 — 宿主机不受影响

# 同一台机器上运行多个隔离的 agent 实例
xlings subos new claude-workspace-1 --from subos:dev-env@latest
xlings subos new claude-workspace-2 --from subos:dev-env@latest
xlings subos new codex-workspace --from subos:dev-env@latest

One-off tasks can also use --cmd:

xlings subos use claude-workspace --sandbox --cmd "python analyze.py"

No root required, no daemon, no image bloat.Every Agent has its own world.

SubOS Detailed Explanation

Three-Level Isolation

Key Capability

• Fork from base — xlings subos new <name> --from <local|subos:pkg@ver>(0s under shared storage)
• Non-interactive Execution —xlings subos use <name> --cmd "<command>" (exit code passthrough)
• sandbox mode — --sandbox flag; bwrap preferred (setuid, xim self-managed), proot fallback
• storage mode — --storage shared|tmpfs|image, select when forking
• project-level SubOS — .xlings.json declared, automatically and transparently activated when entering the project directory
• Keeper (optional) — --keep keep mount namespace active, high-frequency exec optimization; xlings subos stop release

package index ecosystem

graph TD
    subgraph 来源
        S1["🏛️ 官方 - openxlings/xim-pkgindex"]
        S2["🌍 第三方 - 社区仓库"]
        S3["🏠 自建 - 团队 Git / 本地路径"]
    end

    subgraph "资源服务器 (二进制镜像)"
        R1[GLOBAL]
        R2[CN]
        R3[自建 OSS]
    end

    S1 & S2 & S3 -->|"xpkg 包描述"| X[xlings install]
    X -->|"下载二进制"| R1 & R2 & R3

    style X fill:#e8f5e9

One line to add custom index:

{
  "index_repos": [
    { "name": "xim", "url": "https://github.com/openxlings/xim-pkgindex.git" },
    { "name": "my-team", "url": "[email protected]:devtools/pkgs.git" }
  ]
}

ecosystem

Agent Integration

Agent runs inside SubOS

Unlike the traditional "agent calls tools" pattern, xlings lets the agent itself run inside SubOS. The agent has a fully isolated environment — it can install packages, write files, run services — all without affecting the host machine.

programmatic interface

xlings interface provides NDJSON protocol (stdio communication) — programmatic control for AI Agents, CI systems and third-party tools:

xlings interface
# → {"protocol":"1.0","capabilities":[...]}
# ← {"action":"install","target":"subos:py-ds@latest"}
# → {"kind":"progress","phase":"downloading","percent":45,...}
# → {"kind":"data","dataKind":"installed","payload":{...}}

Development & test environment

Besides Agent, SubOS is also suitable for development and testing:

# 不同场景不同环境
xlings subos new rust-nightly --storage shared
xlings subos new legacy-gcc11 --storage shared

# 或使用项目级模式:进入项目目录即自动进入隔离环境
cd my-project/           # 无感进入项目 SubOS

Building from source

# 1. 安装 xlings(见上方"快速开始")
# 2. 在仓库根目录安装构建依赖:
xlings install           # 读取 .xlings.json → xmake, cmake, ninja, 工具链

# 3. 切换到开发工具链:
xlings use [email protected]    # 确保 xrepo 缓存用 glibc 链接

# 4. 构建:
xmake f -y && xmake build xlings
xmake build xlings_tests && xmake run xlings_tests

.xlings.json also drives CI and release pipelines.

Community

• Project Address: https://github.com/openxlings/xlings
• Forum: forum.d2learn.org/category/9/xlings
• QQ Group: 167535744 / 1006282943
• Issues: github.com/openxlings/xlings/issues