Agilab Installer

---
name: agilab-installer
description: Guidance for installing AGILAB, installing apps/pages, and debugging install/test failures.
license: BSD-3-Clause (see repo LICENSE)
metadata:
  updated: 2026-01-09
---

# AGILAB Installer Skill

Use this skill when working on:
- `install.sh` / `install.ps1` (root installer)
- `src/agilab/install_apps.sh` / `src/agilab/install_apps.ps1` (apps/pages installer)
- `src/agilab/apps/install.py` (app install entry)
- Data seeding / dataset archives / post-install hooks

## Golden Rules

- Use `uv --preview-features extra-build-dependencies …` for Python entrypoints.
- Do not add silent fallbacks (detect missing capabilities and raise actionable errors).
- Keep installs **idempotent**: rerunning should not wipe user data or re-download unnecessarily.

## Common Commands

- Full install (macOS/Linux):
  - `./install.sh --non-interactive --cluster-ssh-credentials user:pass --apps-repository /path/to/apps-repo --install-apps --test-apps`
- Apps/pages install only:
  - `cd src/agilab && ./install_apps.sh --test-apps`

## Debugging Patterns

- **“Does not appear to be a Python project”**
  - You are installing a directory without `pyproject.toml`/`setup.py`.
  - Ensure the installer runs `uv pip install -e .` from the repo root.

- **App install fails with missing worker/manager**
  - Validate both manifests exist:
    - manager: `.../<app>_project/pyproject.toml`
    - worker:  `.../<app>_project/src/<app>_worker/pyproject.toml`

- **Dataset extraction wipes seeded files**
  - Avoid mtime heuristics on extracted files; use a stamp file tied to the archive.
  - Prefer linking to shared datasets rather than copying to each app.

## Data Dependencies Between Apps

Some apps depend on outputs of others (e.g. LinkSim needs satellite trajectories).
Preferred approach:
- Install/seed the producing app first.
- Reuse outputs via symlink/junction into the dependent dataset folder to avoid duplication.