Quick-Start

If you are new to AGILab, do one thing first: run the built-in flight_project locally from the web UI.

That first proof is:

  • source checkout

  • local install

  • web UI

  • PROJECT -> choose flight_project

  • ORCHESTRATE -> INSTALL then EXECUTE

  • ANALYSIS -> open the default view

If that works once, then branch into notebooks, cluster mode, or package mode. If it fails, use Newcomer First-Failure Recovery.

For architectural context, see AGILab Architecture and AGI Core Architecture.

Prerequisites

  • Python 3.11+ with uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh).

  • macOS or Linux shell (use WSL2 on Windows until native support lands).

  • If you plan to explore remote workers later, keep SSH access for that later step; it is not needed for the first proof path.

If the first proof fails

Do not broaden the problem immediately. Stay on the built-in local path and run the explicit newcomer proof first:

uv --preview-features extra-build-dependencies run python tools/newcomer_first_proof.py

If you also want the built-in app installer and seeded helper scripts checked in the same run:

uv --preview-features extra-build-dependencies run python tools/newcomer_first_proof.py --with-install

Then use Newcomer First-Failure Recovery for the five common first-run failures:

  • missing uv

  • installer failure

  • built-in app path not found

  • About / ORCHESTRATE startup failure

  • no fresh output under ~/log/execute/flight/

If you want the current public support picture before branching into other routes, use Compatibility Matrix. It makes the current validated slices explicit and separates them from routes that are documented but not the recommended newcomer proof.

Alternative install routes

Use these only if you already know why you want them.

Published package route (fastest install, less representative of the full product path):

mkdir ~/agi-workspace && cd ~/agi-workspace
uv venv
source .venv/bin/activate
uv pip install agilab
uv run agilab

Notebook-first route (best if you intentionally want agi-core before the UI):

git clone https://github.com/ThalesGroup/agilab.git
cd agilab
./install.sh --install-apps --test-apps
uv run --with jupyterlab jupyter lab examples/notebook_quickstart/agi_core_first_run.ipynb

Private apps or framework contributor setup

Only do this after the public built-in proof path is working.

Before working on private apps that depend on the public AGILab framework, initialise the pinned submodule:

git submodule update --init --recursive

Run without PyCharm (CLI wrappers)

If you work from a repository checkout and do not use PyCharm, run the pre-generated wrappers under tools/run_configs directly from a shell. They mirror the bundled run configurations for built-in/public apps.

List available wrappers:

find tools/run_configs -type f -name "*.sh" | sort

Examples:

bash tools/run_configs/agilab/agilab-run-dev.sh
bash tools/run_configs/apps/builtin-flight-run.sh
bash tools/run_configs/apps/builtin-flight-test-worker.sh

Optional developer workflow

If you work from a repository checkout, PyCharm and Codex CLI can speed up iteration, but they are not required to install or run AGILab.

  • PyCharm Professional can reuse the bundled run configurations.

  • Codex CLI can follow the repository guidance in AGENTS.md and .codex/skills.

  • A minimal shell-only workflow remains available through tools/run_configs.

Codex workflow

From this repository, use the shared workflow helper:

  • ./tools/codex_workflow.sh review before larger edits

  • ./tools/codex_workflow.sh exec "short change request"

  • ./tools/codex_workflow.sh apply <task-id>

The helper resolves .external/agilab/tools/codex_workflow.sh first, then falls back to a sibling ../agilab checkout only if you explicitly use the legacy layout.

Cluster installs

If you want to install on a cluster, the installer must have SSH key access or credentials with permission to deploy workers. See Cluster for the full workflow. pycharm/setup_pycharm.py mirrors web interface run configurations to ~/log/execute/<app>/AGI_*.py so that IDE and CLI stay in sync.

Note

On a virgin workspace you do not need to hand-create ~/log/execute/<app> snippets. The installer dispatcher (src/agilab/apps/install.py) calls _seed_example_scripts before kicking off AGI, copying each AGI_*.py helper from src/agilab/examples/<app>/ into ~/log/execute/<app>/ so the first install has runnable mirrors. After that initial bootstrap, the web interface ORCHESTRATE page re-generates the snippets on demand according to the form inputs you provide, keeping IDE and CLI flows in sync. Field defaults are read from each app’s per-user workspace copy ~/.agilab/apps/<app>/app_settings.toml before the form renders. That workspace file is seeded from the versioned app_settings.toml source file (for example <project>/app_settings.toml or <project>/src/app_settings.toml) on first use, so update the workspace copy when you need local baselines and update the source seed only when you intend to change the shipped defaults.

Next steps

  • AGILab Architecture – understand how the web interface, agi_core, agi_env and agi_cluster fit together.

  • Project Files Structure – explore the repository layout with an annotated tree tracked in the repo and refreshed when docs/source/directory-structure.txt is updated.

  • About AGILab – learn how core pages and optional page bundles fit together in the UI.

  • Page Bundles (apps-pages) – learn how page bundles are discovered, enabled, and launched.

Support

Support: open an issue on GitHub

License

New BSD. See License File.