agilab-installer
Guidance for installing AGILAB, installing apps/pages, and debugging install/test failures.
When & Why to Use This Skill
The AGILAB Installer skill is a specialized utility designed to streamline the deployment, configuration, and troubleshooting of the AGILAB platform. It provides expert guidance on executing root and application-level installation scripts, enforcing best practices like idempotency and non-interactive setups. By offering pre-defined debugging patterns for Python environment issues and manifest mismatches, it significantly reduces the time required to maintain complex lab environments and manage inter-app data dependencies.
Use Cases
- Automating full AGILAB platform installations on macOS and Linux using non-interactive shell scripts and cluster credentials.
- Troubleshooting 'missing worker/manager' errors by validating project manifests and directory structures during app deployment.
- Implementing idempotent installation routines that prevent data loss and redundant downloads during environment updates.
- Managing complex data dependencies between applications using symlinks and shared dataset archives to optimize storage.
- Resolving Python environment configuration issues, such as missing build dependencies or incorrect project root detection.
| name | agilab-installer |
|---|---|
| description | Guidance for installing AGILAB, installing apps/pages, and debugging install/test failures. |
| license | BSD-3-Clause (see repo LICENSE) |
| 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.
- You are installing a directory without
App install fails with missing worker/manager
- Validate both manifests exist:
- manager:
.../<app>_project/pyproject.toml - worker:
.../<app>_project/src/<app>_worker/pyproject.toml
- manager:
- Validate both manifests exist:
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.