OpenParable
Skip to content
← Back to skills

Xlings Usage

Apps & Automation
xlings-usage

Xlings Usage is an Agent Skill for apps & automation published in the openxlings/xlings repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

xlings 包管理器完整使用指南 — 安装、多版本管理、SubOS 隔离环境、项目模式、Agent 集成、包索引生态。Use when tasks involve xlings install/use/search/remove flows, subos lifecycle (new/use/fork/stop/remove), project-mode .xlings.json setup, agent sandbox workflows, or custom index/resource-server configuration.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/openxlings/xlings/blob/HEAD/.agents/skills/xlings-usage/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/xlings-usage, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

xlings Usage

Overview

xlings 是通用包管理基础设施,支持:

  • 多版本共存 + 即时切换
  • 三级 SubOS 隔离(shell / FS / image)
  • 去中心化包索引(官方 + 第三方 + 自建)
  • Agent 集成(JSON interface + sandbox)

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

Verify: xlings --version

Package Management

xlings install gcc@16          # install specific version
xlings install node cmake      # install multiple
xlings remove gcc              # remove
xlings search python           # search packages
xlings update                  # update package index
xlings list                    # list installed packages

Multi-Version

xlings install gcc@16 gcc@11   # both installed
xlings use gcc@16              # switch active
xlings use gcc@11              # switch back
gcc --version                  # reflects active version

Mechanism: version-view + reference-counting. N environments share one copy of xpkg payloads.

SubOS — Environment Isolation

Three levels

LevelCommandRoot?Use case
Shellxlings subos use <name>NoVersion isolation only
FS (sandbox)xlings subos use <name> --sandboxNoFull filesystem isolation
Imagexlings subos use <name> --sandbox (storage=image)YesBlock-device isolation

Lifecycle

# Create
xlings subos new dev-env
xlings subos new dev-env --storage tmpfs          # ephemeral data
xlings subos new dev-env --from subos:[email protected] # fork from xpkg base

# Enter
xlings subos use dev-env                          # interactive shell
xlings subos use dev-env --sandbox                # sandbox mode
xlings subos use dev-env --cmd "echo hello"       # single command
xlings subos use dev-env --sandbox --cmd "..."    # sandbox + command

# List / info
xlings subos list
xlings subos info dev-env

# Keeper (high-frequency exec)
xlings subos use dev-env --sandbox --keep         # keep mount namespace alive
xlings subos stop dev-env                         # release keeper

# Remove
xlings subos remove dev-env

Project-local SubOS

When a project has .xlings.json with workspace declarations, entering the project directory automatically activates a project-scoped SubOS:

cd my-project/     # seamlessly enters project SubOS
xlings install     # installs deps into project isolation

Agent Workflows

Agent runs inside SubOS

# Create isolated env for agent
xlings subos new agent-ws --from subos:dev-env@latest

# Enter — agent runs INSIDE this world
xlings subos use agent-ws --sandbox
# → start codex / claude / opencode here

# Multiple instances on one host
xlings subos new agent-ws-1 --from subos:dev-env@latest
xlings subos new agent-ws-2 --from subos:dev-env@latest

Programmatic interface

xlings interface
# NDJSON protocol v1.0 over stdio
# → {"protocol":"1.0","capabilities":[...]}

One-shot command execution

xlings subos use agent-ws --sandbox --cmd "python analyze.py"

Package Index Ecosystem

Add custom index

In ~/.xlings/.xlings.json or project .xlings.json:

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

Resource servers (binary mirrors)

{
  "XLINGS_RES": {
    "GLOBAL": "https://github.com/xlings-res",
    "CN": "https://gitcode.com/xlings-res"
  }
}

type="subos" Packages

Install a subos base package and fork from it:

xlings install subos:[email protected]             # install base (lands in xpkgs/)
xlings subos new exp --from subos:[email protected] # fork (0s, shared storage)

Key Flags Reference

FlagContextEffect
--cmd "<cmd>"subos useNon-interactive single command exec
--sandboxsubos useEnable FS-level isolation (bwrap/proot)
--storage <mode>subos newshared / tmpfs / image
--from <spec>subos newFork from local subos or pkg-spec
--keepsubos useKeep mount namespace alive (no timeout)
--no-keepsubos useForce disable keeper
--ttl <sec>subos useCustom keeper idle timeout
-yinstallSkip confirmation prompts
-ginstallInstall to global scope (not project)

Toolchain Switching (dev)

xlings use [email protected]   # switch active gcc for dev builds