{"id":49620967,"url":"https://github.com/openxlings/xlings","last_synced_at":"2026-05-26T23:01:48.397Z","repository":{"id":253824982,"uuid":"844525090","full_name":"openxlings/xlings","owner":"openxlings","description":"Universal package infrastructure with OS-like SubOS isolation - Multi-version · Rootless · Decentralized Index · Agent-ready.","archived":false,"fork":false,"pushed_at":"2026-05-26T05:38:43.000Z","size":3109,"stargazers_count":579,"open_issues_count":22,"forks_count":45,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-26T06:10:53.904Z","etag":null,"topics":["ai","auto-configuration","auto-detect","d2x","demos","installer","llm-application","package-manager","project-management","tools","version-manager","xlings"],"latest_commit_sha":null,"homepage":"https://openxlings.github.io","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openxlings.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-08-19T12:46:09.000Z","updated_at":"2026-05-26T05:22:47.000Z","dependencies_parsed_at":"2024-11-29T17:24:52.207Z","dependency_job_id":"16426339-623a-4008-a2fb-d9db3cc5d370","html_url":"https://github.com/openxlings/xlings","commit_stats":null,"previous_names":["sunrisepeak/xlings","openxlings/xlings"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/openxlings/xlings","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openxlings%2Fxlings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openxlings%2Fxlings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openxlings%2Fxlings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openxlings%2Fxlings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openxlings","download_url":"https://codeload.github.com/openxlings/xlings/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openxlings%2Fxlings/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33542350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"ssl_error","status_checked_at":"2026-05-26T15:22:15.568Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","auto-configuration","auto-detect","d2x","demos","installer","llm-application","package-manager","project-management","tools","version-manager","xlings"],"created_at":"2026-05-05T02:03:38.203Z","updated_at":"2026-05-26T23:01:48.392Z","avatar_url":"https://github.com/openxlings.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"\u003cdiv align=center\u003e\n  \u003cimg width=\"120\" src=\"https://xlings.d2learn.org/imgs/xlings-logo.png\"\u003e\n\n  \u003ch1\u003exlings\u003c/h1\u003e\n\n  \u003cem\u003eUniversal package infrastructure with OS-like SubOS isolation.\u003cbr/\u003e\n  Multi-version · Rootless · Decentralized Index · Agent-ready.\u003c/em\u003e\n\n  \u003cb\u003e [Website] | [Docs] | [Package Index] | [Forum] \u003c/b\u003e\n\n  [中文](README.zh.md) | English\n\u003c/div\u003e\n\n[Website]: https://openxlings.github.io/\n[Docs]: docs/\n[Package Index]: https://openxlings.github.io/xim-pkgindex\n[Forum]: https://forum.d2learn.org/category/9/xlings\n\n\u003cp align=center\u003e\n  \u003cem\u003eUsed by: \u003ca href=\"https://github.com/mcpp-community/mcpp\"\u003eMCPP\u003c/a\u003e · upcoming \u003cb\u003eLuban\u003c/b\u003e Linux\u003c/em\u003e\n\u003c/p\u003e\n\n\u003c!-- TODO: 30s demo GIF here --\u003e\n\n---\n\n## Why xlings?\n\n| Pain | Without xlings | With xlings |\n|------|----------------|-------------|\n| Need gcc@16 alongside system gcc@11 | Manual builds, conflict-prone | `xlings install gcc@16` — both coexist |\n| Team needs identical project env | \"Works on my machine\" | `.xlings.json` + `xlings install` — enter project dir and you're seamlessly in an isolated, reproducible SubOS |\n| Agent needs its own isolated world to run in | Docker daemon + images + cleanup | Agent runs **inside** a SubOS — full permissions, rootless, lightweight, host untouched |\n\n### vs. other tools\n\n| | apt / brew | nix | docker | **xlings** |\n|---|:---:|:---:|:---:|:---:|\n| Multi-version coexistence | ❌ | ✅ | ✅ | ✅ |\n| Rootless | ❌ | ⚠️ | ⚠️ | ✅ (except image mode) |\n| No daemon | ✅ | ✅ | ❌ | ✅ |\n| Cross-platform | ❌ | ⚠️ | ✅ | ✅ Linux / macOS / Windows |\n| Isolation granularity | ❌ | FS | FS+ | 🔒 shell / FS / image (3 levels) |\n| Storage reuse | — | ✅ store | ❌ image bloat | ✅ version-view + refcount |\n| Startup overhead | ⚡ instant | ⚡ instant | 🐢 seconds | ⚡ instant / ~10ms (sandbox) |\n| Decentralized index | ❌ | ❌ | ❌ | ✅ official + 3rd + self-hosted |\n| Agent / JSON interface | ❌ | ❌ | ⚠️ API | ✅ `xlings interface` (NDJSON) |\n| OS-level pkg mgr | apt is | NixOS | ❌ | ✅ (Luban Linux, upcoming) |\n\n---\n\n## Quick Start\n\n### Install\n\n**Linux / macOS**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash\n```\n\n**Windows (PowerShell)**\n\n```powershell\nirm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.ps1 | iex\n```\n\n### Via your AI agent\n\nCopy this prompt to your AI agent (Claude, Codex, OpenCode, etc.):\n\n```\nInstall xlings package manager on my machine.\n- Linux/macOS: curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash\n- Windows: irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.ps1 | iex\nProject: https://github.com/openxlings/xlings\n```\n\n### Hello, multi-version\n\n```bash\nxlings install gcc@16 node@24 cmake\nxlings use gcc@16        # switch active version\ngcc --version            # gcc 16.x\n```\n\n---\n\n## Core Concepts\n\n```mermaid\ngraph TD\n    subgraph \"Package Index (decentralized)\"\n        A1[Official - openxlings/xim-pkgindex]\n        A2[3rd-party - community repos]\n        A3[Self-hosted - your Git repo]\n    end\n\n    subgraph \"xpkgs/ — global shared, version-view + ref-counted\"\n        B1[gcc/16.1]\n        B2[gcc/15.1]\n        B3[python/3.12]\n        B4[subos-x-py-ds/1.0]\n    end\n\n    subgraph \"SubOS instances — per-env isolated\"\n        C1[\"SubOS A (shell-level)\\nshim → gcc@16\\n🔓 no root\"]\n        C2[\"SubOS B (FS-level sandbox)\\nbwrap / proot\\n🔓 no root\"]\n        C3[\"SubOS C (image-level)\\next4 sparse mount\\n🔒 root needed\"]\n    end\n\n    A1 \u0026 A2 \u0026 A3 --\u003e B1 \u0026 B2 \u0026 B3 \u0026 B4\n    B1 --\u003e C1\n    B2 --\u003e C2\n    B3 --\u003e C3\n\n    style C1 fill:#e8f5e9\n    style C2 fill:#e3f2fd\n    style C3 fill:#fff3e0\n```\n\n### Five pillars\n\n1. **📦 Universal package infrastructure** — binary / script / config / subos / tutorial — all as xpkg\n2. **🔀 Multi-version coexistence** — N versions side-by-side; version-view + reference-counting (N envs ≈ 1× storage)\n3. **🏗️ 3-level SubOS isolation** — shell (env switch) / FS (bwrap/proot, rootless) / image (ext4, root)\n4. **🌐 Decentralized package index** — official + 3rd-party + self-hosted; resource servers for binary mirrors\n5. **🤖 JSON event interface** — `xlings interface` (NDJSON protocol) for AI agents, CI, and 3rd-party tooling\n\n---\n\n## Three Scenarios\n\n### 🛠 Toolchain — multi-version without sudo\n\n```bash\nxlings install gcc@16 gcc@11 cmake node@24\nxlings use gcc@16        # instant switch\nxlings use gcc@11        # back to 11, no conflict\n```\n\n### 📦 Project — seamless project-level SubOS\n\nWhen you enter a project directory containing `.xlings.json`, xlings **seamlessly activates a project-scoped SubOS** — you and your team work inside an isolated environment without even noticing. All dependencies stay within the project's own SubOS.\n\n```json\n{\n  \"workspace\": {\n    \"xmake\": \"3.0.7\",\n    \"gcc\": { \"linux\": \"16.1.0\" },\n    \"llvm\": { \"macosx\": \"20.1.7\" }\n  }\n}\n```\n\n```bash\ncd my-project/           # automatically enters project SubOS\nxlings install           # installs deps into project-local isolation\nxmake build              # everything just works, isolated from host\n```\n\nClone → `cd` → build. Same env across teammates and CI. No manual activation needed.\n\n### 🤖 Agent — agent runs inside its own lightweight world\n\nxlings lets you run agents (codex, claude, opencode, etc.) **inside SubOS** — the agent gets full permissions within its isolated world, while the host remains completely safe.\n\n**Why this matters:**\n\n- 🔓 Agent has broader permissions inside SubOS — install packages, modify files, run arbitrary code — no risk to host data\n- 🔁 Same agent tool, multiple instances on one host — each in its own SubOS with its own config (normally codex/claude can only run once per account)\n- ⚡ Lightweight — not a heavy VM or container, just a namespace-isolated environment\n\n**Run an agent inside SubOS:**\n\n```bash\n# Create a SubOS for the agent (from a base env, or configure your own)\nxlings subos new claude-workspace --from subos:dev-env@latest\n\n# Enter SubOS — the agent runs IN here, with full control\nxlings subos use claude-workspace --sandbox\n# → you're now inside the agent's world\n# → start claude / codex / opencode here\n# → they can install, modify, experiment freely — host is untouched\n\n# Multiple isolated instances of the same agent on one machine\nxlings subos new claude-workspace-1 --from subos:dev-env@latest\nxlings subos new claude-workspace-2 --from subos:dev-env@latest\nxlings subos new codex-workspace --from subos:dev-env@latest\n```\n\n**One-shot tasks via `--cmd` also work:**\n\n```bash\nxlings subos use claude-workspace --sandbox --cmd \"python analyze.py\"\n```\n\nNo root. No daemon. No image bloat. **Each agent gets its own world.**\n\n---\n\n## SubOS Deep Dive\n\n### Three isolation levels\n\n| Level | Mechanism | Root? | Isolation scope | Use case |\n|-------|-----------|:---:|---|---|\n| 🟢 **Shell** | env/PATH switch | No | Tool versions only | Daily dev, version pinning |\n| 🔵 **FS** | bwrap / proot sandbox | No | Filesystem (HOME, /tmp private) | Agent, experiments, untrusted code |\n| 🟠 **Image** | ext4 sparse mount | Yes | Full block-device isolation | Heavy workloads, persistent sandboxes |\n\n### Key features\n\n- **Fork from base** — `xlings subos new \u003cname\u003e --from \u003clocal|subos:pkg@ver\u003e` (0s for shared storage)\n- **Non-interactive exec** — `xlings subos use \u003cname\u003e --cmd \"\u003ccommand\u003e\"` (exit code propagates)\n- **Sandbox mode** — `--sandbox` flag; bwrap preferred (setuid, xim-managed), proot fallback\n- **Storage modes** — `--storage shared|tmpfs|image` chosen at fork time\n- **Project-local SubOS** — add `\"subos\": \"\u003cname\u003e\"` to `.xlings.json`; entering the project directory seamlessly activates the project's SubOS\n- **Keeper (opt-in)** — `--keep` holds mount namespace alive for high-frequency exec; `xlings subos stop` to release\n\n---\n\n## Package Index Ecosystem\n\n```mermaid\ngraph TD\n    subgraph Sources\n        S1[🏛️ Official - openxlings/xim-pkgindex]\n        S2[🌍 3rd-party - community repos]\n        S3[🏠 Self-hosted - team Git / local path]\n    end\n\n    subgraph \"Resource Servers (binary mirrors)\"\n        R1[GLOBAL]\n        R2[CN]\n        R3[Self-hosted OSS]\n    end\n\n    S1 \u0026 S2 \u0026 S3 --\u003e|\"xpkg manifest\"| X[xlings install]\n    X --\u003e|\"download binary\"| R1 \u0026 R2 \u0026 R3\n\n    style X fill:#e8f5e9\n```\n\nAdd a custom index in one line:\n\n```json\n{\n  \"index_repos\": [\n    { \"name\": \"xim\", \"url\": \"https://github.com/openxlings/xim-pkgindex.git\" },\n    { \"name\": \"my-team\", \"url\": \"git@gitlab.internal:devtools/pkgs.git\" }\n  ]\n}\n```\n\n---\n\n## Ecosystem\n\n| Project | Role | Link |\n|---------|------|------|\n| **MCPP** | Modern C++ build toolchain ecosystem — distributed through xlings | [github.com/mcpp-community/mcpp](https://github.com/mcpp-community/mcpp) |\n| **Luban Linux** | Upcoming Linux distribution using xlings as system-level package manager | *(link when published)* |\n| **xim-pkgindex** | Official package index — 60+ packages and growing | [openxlings/xim-pkgindex](https://github.com/openxlings/xim-pkgindex) |\n\n---\n\n## Agent Integration\n\n### The agent lives inside SubOS\n\nUnlike traditional \"agent calls tool\" patterns, xlings puts the **agent itself inside a SubOS**. The agent gets a full isolated environment — it can install packages, write files, run services — all without touching the host.\n\n| Use case | How |\n|----------|-----|\n| Give agent full permissions safely | Run agent inside `--sandbox` SubOS |\n| Multiple instances of same agent (codex/claude) on one host | One SubOS per instance |\n| Agent needs specific env (Python + CUDA + custom libs) | Fork from `subos:ml-env@latest` |\n| Ephemeral task execution | `--storage tmpfs` + `--cmd` |\n\n### Programmatic interface\n\n`xlings interface` provides NDJSON protocol over stdio — for programmatic control by AI agents, CI systems, and third-party tools:\n\n```bash\nxlings interface\n# → {\"protocol\":\"1.0\",\"capabilities\":[...]}\n# ← {\"action\":\"install\",\"target\":\"subos:py-ds@latest\"}\n# → {\"kind\":\"progress\",\"phase\":\"downloading\",\"percent\":45,...}\n# → {\"kind\":\"data\",\"dataKind\":\"installed\",\"payload\":{...}}\n```\n\n### Dev \u0026 test environments\n\nBeyond agents, SubOS is also great for development and testing:\n\n```bash\n# Different environments for different scenarios\nxlings subos new rust-nightly --storage shared\nxlings subos new legacy-gcc11 --storage shared\n\n# Or use project-local mode: just cd into the project directory\ncd my-project/           # seamlessly enters project SubOS\n```\n\n---\n\n## Building from source\n\n```bash\n# 1. Install xlings (see Quick Start above)\n# 2. From the repo root — install build deps:\nxlings install           # reads .xlings.json → xmake, cmake, ninja, toolchain\n\n# 3. Switch to the dev toolchain:\nxlings use gcc@16.1.0    # ensures glibc-linked xrepo cache is used\n\n# 4. Build:\nxmake f -y \u0026\u0026 xmake build xlings\nxmake build xlings_tests \u0026\u0026 xmake run xlings_tests\n```\n\nThe same `.xlings.json` drives CI and the release pipeline.\n\n---\n\n## Community\n\n- **Forum**: [forum.d2learn.org/category/9/xlings](https://forum.d2learn.org/category/9/xlings)\n- **QQ Groups**: 167535744 / 1006282943\n- **Issues**: [github.com/openxlings/xlings/issues](https://github.com/openxlings/xlings/issues)\n\n### Contributing\n\n- [Issue handling \u0026 bug fixing](https://xlings.d2learn.org/en/documents/community/contribute/issues.html)\n- [Adding new packages](https://xlings.d2learn.org/en/documents/community/contribute/add-xpkg.html)\n- [Documentation](https://xlings.d2learn.org/en/documents/community/contribute/documentation.html)\n\n---\n\n**Contributors**\n\n\u003ca href=\"https://github.com/openxlings/xlings/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=openxlings/xlings\" /\u003e\n\u003c/a\u003e\n\n[![Star History Chart](https://api.star-history.com/svg?repos=openxlings/xlings,openxlings/xim-pkgindex\u0026type=Date)](https://star-history.com/#openxlings/xlings\u0026openxlings/xim-pkgindex\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenxlings%2Fxlings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenxlings%2Fxlings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenxlings%2Fxlings/lists"}