Newcomer Guide

If you are new to AGILab, optimize for one outcome only: one successful local run of the built-in flight_project from the web UI, including the core PROJECT -> ORCHESTRATE -> PIPELINE -> ANALYSIS route.

This page gives the mental model only. Quick-Start owns the exact commands. Newcomer First-Failure Recovery owns the first-failure path.

Fast adoption ladder

Use this order when you need the quickest route to confidence:

Stage

What to do

Why it matters

Browser preview

Open AGILAB Demo.

Confirms the public UI shape before you install anything.

Local first proof

Follow Quick-Start with the built-in flight_project.

Exercises the real source-checkout install, run, and analysis path.

Evidence record

Keep ~/log/execute/flight/run_manifest.json from agilab first-proof --json.

Gives support, contributors, and future runs the same baseline.

Expansion

Move to notebooks, package mode, private apps, or cluster work.

Prevents day-1 failures from mixing product, app, and infrastructure variables.

Choose one route

Goal

Route

Use when

See the UI now

AGILAB Demo

You want a browser-only look at the AGILAB web UI before installing anything.

Prove it locally

Quick-Start

You want the real source-checkout path with flight_project. Target: pass the first proof in 10 minutes.

Use the API/notebook

agi-core Demo

You want the smaller AgiEnv / AGI.run(...) surface before the full UI.

The first proof is deliberately narrow: use a source checkout, run the built-in flight_project locally from the web UI, inspect the pipeline recipe, and confirm a visible result under ~/log/execute/flight/. The landing page first-proof wizard now enforces that same single actionable route, reads run_manifest.json, and shows a recovery checklist with exact evidence commands before you branch out.

That is enough for day 1. Do not widen the problem to notebooks, package mode, private apps, or cluster setup until this path works once and the manifest gives you a passing baseline.

This also means PyCharm is not part of the day-1 contract. AGILAB keeps PyCharm run configurations for developers who want IDE debugging, but the newcomer route is shell + browser first. The same install, execute, and analysis path can be driven from commands, the web UI, or checked-in wrappers.

Adoption evidence

On April 24, 2026, the source-checkout first-proof smoke passed locally in 5.86s against the 600s target. On April 25, 2026, the same source-checkout proof passed on a fresh external machine in 26.87s. On April 27, 2026, the packaged first-proof CLI passed locally in 7.04s:

uv --preview-features extra-build-dependencies run agilab first-proof --json

The JSON proof writes ~/log/execute/flight/run_manifest.json. That manifest is the portable first-proof run record: command, Python/platform context, active app, timing, artifact references, and validation status.

That supports an Ease of adoption score of 4.0 / 5: the public demo works, the first routes are explicit, PyCharm is optional, installer tests are opt-in, and the source-checkout proof now has local, fresh external macOS, repeatable Flight cluster doctor, AI Lightning, Hugging Face, bare-metal cluster, and VM-based cluster validation. It is not scored higher yet because Azure, AWS, and GCP deployment validation remains open.

After day 1: cluster proof

Cluster validation is a second milestone, not part of the newcomer proof. Use it only after the local flight_project path has passed once.

For the repeatable two-node check, go to Cluster. That page owns:

  • LAN discovery and SSH prerequisites

  • shared cluster-share setup and sentinel checks

  • the Flight cluster doctor command

  • source-checkout and package-mode cluster validation commands

What to ignore on day 1

Skip these until the local flight_project proof works once:

  • cluster and SSH setup

  • published-package mode

  • notebook-first route

  • private or optional app repositories

  • IDE convenience flows

  • full installer test suites unless you explicitly want validation instead of the fastest first proof

The five words you need

  • PROJECT: where you choose the app you want to run.

  • ORCHESTRATE: where you install and execute it.

  • PIPELINE: where you inspect, generate, or replay run steps.

  • ANALYSIS: where you look at the result.

  • Worker: the isolated runtime that actually executes the app.

Common newcomer traps

  • Mixing package mode and source mode without being explicit: pick one first, then switch deliberately.

  • Trying cluster mode before a local run succeeds: local success gives you a clean baseline for later SSH debugging.

  • Expecting private or optional apps to appear automatically: public built-in apps live under src/agilab/apps/builtin; extra apps usually require APPS_REPOSITORY / AGILAB_APPS_REPOSITORY.

  • Running ``uvx agilab`` from the source tree: from a repository checkout, use the source commands documented in Quick-Start so you do not accidentally run the published wheel.

  • Assuming PyCharm is required: PyCharm mirrors are useful for debugging, but the supported first proof is independent of PyCharm.

Where to go next