<!-- Copyright 2026 FlagOS Contributors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->

Install Multi-Chip Software Stack

Install 5 packages inside a running GPU container, in dependency order, with per-package validation and structured error reporting.

Skill Components

install-stack/
├── SKILL.md                           # This file — execution flow
├── scripts/
│   ├── detect_network.py              # Probe GitHub/PyPI, return mirror config (JSON)
│   ├── collect_env_info.py            # Python/glibc/arch/vendor/disk info (JSON)
│   ├── select_flagtree_wheel.py       # Match vendor+python+glibc → wheel specifier (JSON)
│   └── validate_packages.py           # Import-test all 5 packages, report status (JSON)
└── references/
    ├── vendor-mappings.md             # FlagCX make flags, adaptor names, dependency chain
    └── network-mirrors.md             # GitHub/PyPI mirror config rules

Prerequisites

• A running Docker container with PyTorch + GPU access (from /gpu-container-setup)
• Know the container name and GPU vendor

If invoked standalone, ask the user for container name and GPU vendor. If invoked from /flagrelease orchestrator, these are passed as context.

Execution Flow

Step 0: Resolve Container & Vendor

Verify the container is running:

docker inspect --format='{{.State.Status}}' <CONTAINER> | grep -q running

Copy and run scripts/collectenvinfo.py inside the container to get vendor, Python version, glibc version, architecture, and free disk space:

docker cp <SKILL_DIR>/scripts/collect_env_info.py <CONTAINER>:/tmp/
docker exec <CONTAINER> python3 /tmp/collect_env_info.py

If vendor is unknown and user didn't provide --vendor, ask the user.

Step 1: Detect Network Environment

Copy and run scripts/detect_network.py inside the container:

docker cp <SKILL_DIR>/scripts/detect_network.py <CONTAINER>:/tmp/
docker exec <CONTAINER> python3 /tmp/detect_network.py

Parse the JSON output to get GITHUBPREFIX and PIPINDEX for all subsequent commands. See references/network-mirrors.md for fallback rules.

Step 2: Check Disk Space

From collectenvinfo.py output, verify at least 10GB free. If not, warn user and ask whether to proceed.

Step 3: Install Packages (in dependency order)

See references/vendor-mappings.md for dependency chain and install order: vLLM → FlagTree → FlagGems → FlagCX → vllm-plugin-FL

3.1: vLLM 0.13.0

docker exec <CONTAINER> pip install ${PIP_INDEX} vllm==0.13.0

Quick validate:

docker exec <CONTAINER> python3 -c "import vllm; assert vllm.__version__ == '0.13.0'"

GATE: If vLLM install fails → record error and EXIT the skill.

3.2: FlagTree (pre-compiled wheel)

Run scripts/selectflagtreewheel.py to find the correct wheel:

python3 <SKILL_DIR>/scripts/select_flagtree_wheel.py \
    --vendor <VENDOR> --python <PY_VER> --glibc <GLIBC_VER>

If status is FOUND, uninstall stock triton and install the wheel:

docker exec <CONTAINER> bash -c '
python3 -m pip uninstall -y triton
python3 -m pip uninstall -y triton
python3 -m pip install <SPECIFIER> <PIP_ARGS>
'

If status is NOT_FOUND, record the mismatch and continue (do not exit).

3.3: FlagGems

docker exec <CONTAINER> bash -c "
cd /tmp && git clone ${GITHUB_PREFIX}/FlagOpen/FlagGems
cd FlagGems && pip install ${PIP_INDEX} -e .
"

Failure → record and continue.

3.4: FlagCX (two-phase build)

Read references/vendor-mappings.md to look up the correct Make flag and FLAGCX_ADAPTOR for the detected vendor.

Phase 1: Build C++ library:

docker exec <CONTAINER> bash -c "
cd /tmp && git clone ${GITHUB_PREFIX}/flagos-ai/FlagCX
cd FlagCX && git submodule update --init --recursive
make <MAKE_FLAG> -j\$(nproc)
"

Phase 2: Install PyTorch plugin:

docker exec <CONTAINER> bash -c "
cd /tmp/FlagCX/plugin/torch
FLAGCX_ADAPTOR=<ADAPTOR> pip install -e . --no-build-isolation
"

Failure → record and continue.

3.5: vllm-plugin-FL

docker exec <CONTAINER> bash -c "
cd /tmp && git clone ${GITHUB_PREFIX}/flagos-ai/vllm-plugin-FL
cd vllm-plugin-FL
pip install ${PIP_INDEX} -r requirements.txt
pip install --no-build-isolation -e .
"

On Iluvatar, if requirements.txt fails, retry with requirements_iluvatar.txt.

GATE: If vllm-plugin-FL fails → record error and EXIT the skill.

Step 4: Validate All Packages

Copy and run scripts/validate_packages.py inside the container:

docker cp <SKILL_DIR>/scripts/validate_packages.py <CONTAINER>:/tmp/
docker exec <CONTAINER> python3 /tmp/validate_packages.py

This produces a comprehensive JSON report of all 5 packages with import status, versions, and gate check.

Step 5: Set Runtime Environment

If FlagCX installed successfully, persist FLAGCX_PATH:

docker exec <CONTAINER> bash -c "echo 'export FLAGCX_PATH=/tmp/FlagCX' >> ~/.bashrc"

Step 6: Produce Final Report

Combine all results into structured output:

{
  "status": "PASS | PARTIAL | FAIL",
  "stage": "install-stack",
  "container": "<name>",
  "vendor": "<vendor>",
  "network": {"github_mirror": true, "pypi_mirror": true},
  "python_version": "3.11",
  "glibc_version": "2.34",
  "packages": {
    "vllm": {"status": "PASS", "version": "0.13.0"},
    "flagtree": {"status": "PASS", "version": "0.4.1+ascend3.2"},
    "flaggems": {"status": "PASS", "version": "..."},
    "flagcx": {"status": "PASS", "version": "0.10.0"},
    "vllm_plugin_fl": {"status": "PASS", "version": "..."}
  },
  "flagcx_path": "/tmp/FlagCX",
  "gate_passed": true,
  "errors": []
}

Status logic:

• PASS — all 5 packages installed and validated
• PARTIAL — vLLM + plugin installed, some of FlagTree/FlagGems/FlagCX failed
• FAIL — vLLM or plugin failed (gate failed)

Error Handling

Timeout Rules