# Install Stack Flagos

> Install the 5-package multi-chip software stack (vLLM, FlagTree, FlagGems, FlagCX, vllm-plugin-FL) inside a GPU container. Handles network mirror detection, dependency ordering, wheel selection, and per-package validation. Use after gpu-container-setup has produced a running container with PyTorch + GPU access.

- Skill: `flagos-ai/install-stack-flagos` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add flagos-ai/install-stack-flagos`
- Raw SKILL.md: https://api.skillmd.com/api/skills/flagos-ai/install-stack-flagos/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: flagos-ai (https://skillmd.com/u/flagos-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/flagos-ai/install-stack-flagos

---


<!--
 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:

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

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

```bash
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:

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

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

### Step 2: Check Disk Space

From `collect_env_info.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

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

Quick validate:
```bash
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/select_flagtree_wheel.py` to find the correct wheel:

```bash
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:

```bash
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

```bash
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:
```bash
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:
```bash
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

```bash
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:

```bash
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:

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

### Step 6: Produce Final Report

Combine all results into structured output:

```json
{
  "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

| Failure | Behavior |
|---------|----------|
| Container not running | Report error, exit |
| Network unreachable (both direct and mirror) | Report, exit |
| pip install fails | Report package, full error, continue (unless gate) |
| Build from source fails | Report compiler error, continue |
| No matching FlagTree wheel | Report vendor/python/glibc mismatch, continue |
| Import fails after install | Report traceback, continue |
| Disk space < 10GB | Warn user, ask whether to proceed |
| Timeout (any command) | All commands use timeout; report which step |

## Timeout Rules

| Operation | Timeout |
|-----------|---------|
| pip install (per package) | 300s |
| git clone | 120s |
| make (FlagCX) | 300s |
| Network probe | 5s |
| Validation (import) | 30s |