Skip to content
Hosted service in public preview. 3.0 installs from GitHub until it is on PyPI.

Zero-code runs

agenticml run executes a script inside a run. The script does not need to import agenticml.

Terminal window
agenticml run train.py
agenticml run train.py --lr 1e-3
agenticml run -m mypkg.train
agenticml run -m mypkg.train --epochs 3
agenticml run --project demo -- python train.py --lr 1e-3
agenticml python train.py
agenticml python train.py --lr 1e-3

Script arguments are optional. Without them, the script runs with its own defaults and argparse values are still captured as config. With them, everything after the script is passed through untouched.

Every form runs the target in-process as __main__ inside one tracked run. Pick the one that matches how you already start training.

Form Use it when
agenticml run train.py [args] You want to track a script with the current interpreter. Shortest form.
agenticml run -m pkg.train [args] Your entry point is a module, so relative imports keep working.
agenticml run -- python train.py [args] You are wrapping an existing command line (Makefile, shell script). Swap python for agenticml run --.
agenticml python train.py [args] You want the least typing. Options come from AGENTICML_* variables.
agenticml run --project demo -- python -u train.py You need Python flags or a specific interpreter. agenticml-lite must be installed there.
python -m agenticml run train.py agenticml is not on PATH, for example inside torchrun or accelerate launch.

Rules for every form:

  • agenticml options (--project, --name, …) come before the script or module. Everything after the target is passed to your script untouched.
  • The -- separator is needed only in front of python ....
  • The default run name is the script’s repo-relative path, unless --name is given.
  • Only Python files are supported: no python -c and no stdin scripts.
What Where it comes from Turn off
Config argparse and @hydra.main --no-capture-args (AGENTICML_CAPTURE_ARGS=0)
Code snapshot imported project modules and files opened for reading --no-code (AGENTICML_TRACK_CODE=0)
Model, optimizer, loss, dataloader PyTorch construction hooks --no-auto-track (AGENTICML_AUTO_TRACK=0)
auto/loss, auto/lr, auto/epoch backward() and optimizer.step() --no-auto-metrics (AGENTICML_AUTO_METRICS=0); --log-every N
TensorBoard SummaryWriter / tensorboardX --no-tensorboard (AGENTICML_SYNC_TENSORBOARD=0)
System metrics psutil, plus pynvml when installed --no-system-metrics (AGENTICML_SYSTEM_METRICS=0); --system-metrics-interval S
Lineage shadow-Git snapshot --no-lineage (AGENTICML_LINEAGE=0)
Environment environment metadata --no-env (AGENTICML_CAPTURE_ENV=0)

Loss is unscaled under GradScaler and averaged over gradient-accumulation steps. Keys passed to init(config=...) win over captured hyperparameters. Defaults differ between the SDK and CLI for two switches: auto_metrics and sync_tensorboard are off by default in agenticml.init() and on under agenticml run.

A CLI flag overrides its environment variable; a blank environment variable counts as unset. Repeatable flags (--track-file, --source-root) replace rather than extend the corresponding environment variable list. Environment variables with multiple paths (AGENTICML_TRACK_FILES, AGENTICML_SOURCE_ROOTS) use os.pathsep (: on POSIX, ; on Windows).

There is no positive override flag: once a feature is disabled via its environment variable (such as AGENTICML_SYSTEM_METRICS=0 or AGENTICML_ALL_RANKS=1), the CLI cannot re-enable it; unset the variable instead.

Option Environment variable Default Description
--project NAME AGENTICML_PROJECT repo or directory name Project name
--name NAME AGENTICML_NAME entry script path Run name
--tags A,B AGENTICML_TAGS unset Comma-separated tags
--notes TEXT AGENTICML_NOTES unset Run launch notes
--config KEY=VALUE none unset Config key/value pair (repeatable; JSON or raw string)
--config-file PATH AGENTICML_CONFIG_FILE unset JSON file containing a top-level config object
--group NAME AGENTICML_GROUP unset Run group
--job-type NAME AGENTICML_JOB_TYPE unset Job type
--task NAME AGENTICML_TASK inferred Task name
--parent RUN_ID AGENTICML_PARENT inferred Lineage parent run ID
--allow-cross-task AGENTICML_ALLOW_CROSS_TASK=1 off Silence warning when --task differs from parent’s task
--id RUN_ID AGENTICML_RUN_ID unset Run ID to resume (requires --resume allow or must)
--resume MODE AGENTICML_RESUME unset Resume mode: never, allow, or must
--mode MODE AGENTICML_MODE local local, offline, or disabled
--dir DIR AGENTICML_DIR ~/.agenticml Local store root
--no-auto-track AGENTICML_AUTO_TRACK=0 on Turn off PyTorch component detection
--no-auto-metrics AGENTICML_AUTO_METRICS=0 on under run Turn off auto/loss, auto/lr, auto/epoch
--log-every N AGENTICML_LOG_EVERY 1 Frequency of auto metrics in optimizer steps
--no-tensorboard AGENTICML_SYNC_TENSORBOARD=0 on under run Turn off TensorBoard mirroring
--no-capture-args AGENTICML_CAPTURE_ARGS=0 on Turn off argparse and Hydra argument capture
--no-system-metrics AGENTICML_SYSTEM_METRICS=0 on (if psutil) Turn off CPU, memory, and GPU sampling
--system-metrics-interval S AGENTICML_SYSTEM_METRICS_INTERVAL 10.0 System metrics sampling interval in seconds
--no-lineage AGENTICML_LINEAGE=0 on Turn off shadow-Git lineage snapshots
--no-code AGENTICML_TRACK_CODE=0 on Turn off source file tracking
--no-env AGENTICML_CAPTURE_ENV=0 on Turn off environment metadata capture
--track-file PATH AGENTICML_TRACK_FILES unset Extra source file to track (repeatable; path-separated in env)
--source-root DIR AGENTICML_SOURCE_ROOTS unset Extra source directory (repeatable; path-separated in env)
--max-file-bytes N AGENTICML_MAX_FILE_BYTES 10485760 (10 MiB) Per-file size cap for code and lineage snapshots
--max-total-bytes N AGENTICML_MAX_TOTAL_BYTES 104857600 (100 MiB) Total size cap for code and lineage snapshots
--flush-interval S AGENTICML_FLUSH_INTERVAL 2.0 Background metric flush interval in seconds
--all-ranks AGENTICML_ALL_RANKS=1 rank 0 only Track all distributed ranks, not just rank 0
--verbose none off Print run ID and store paths

Resume an existing run or continue under a specific ID:

Terminal window
agenticml run --id 20261101T130355-1cded4a7 --resume must -- python train.py
  • --id requires --resume allow or must, and --resume allow or must requires --id; otherwise it is a usage error (exit 2).
  • must requires that the run already exists. allow resumes an existing run, or creates a new run with that ID if none exists.
  • A resumed run keeps its stored project, name, task, and parent (a differing --parent logs a warning). Step counters continue from the last stored step, and a resume event is logged.
  • If a requested resume cannot be performed (the run is missing under must, open in another process, pruned by sync --prune, or missing meta.json), agenticml run prints an error and exits 2 without running the script.
  • If the script itself calls agenticml.init(id=..., resume=...) under agenticml run, those arguments are ignored with a warning; configure resume through the CLI instead.

Pass configuration values from the CLI or a file:

Terminal window
agenticml run --config lr=1e-3 --config amp=true --config layers='[64, 64]' -- python train.py
agenticml run --config-file base.json -- python train.py
  • --config KEY=VALUE (repeatable): VALUE is parsed as JSON if valid (lr=1e-3 becomes 0.001, amp=true becomes boolean true, layers=[64,64] becomes a list). If it does not parse as JSON, it remains a raw string (opt=adam). Quote the value to force a string: --config 'tag="1e-3"'. Values that evaluate to NaN or Infinity are rejected (exit 2). When a key is repeated, the last occurrence wins.
  • --config-file PATH (AGENTICML_CONFIG_FILE): Reads configuration from a JSON file whose top level is an object.
  • Precedence order: config file < --config pairs < script’s own init(config=...).
  • Explicit CLI and file configuration keys are protected: argument parsers (argparse, Hydra) never overwrite them.
  • When resuming a run, new configuration values merge on top of the run’s stored config.

--parent RUN_ID (or --parent=RUN_ID, or env AGENTICML_PARENT) sets an explicit lineage parent for the new run. The CLI value wins over the env var. An invalid run id is a usage error (exit 2). --parent applies only to new runs: a resumed run keeps its stored parent and warns if --parent differs.

Terminal window
agenticml run --parent <RUN_ID> train.py

Without --task (and without a valid AGENTICML_TASK), the new run inherits the parent’s task, so it shows up in the parent’s lane in the lineage graph. The dashboard labels such lanes “from parent run”. Task precedence: --task > AGENTICML_TASK > the parent’s task > an agenticml.toml task > the entry script’s folder.

If --task or AGENTICML_TASK differs from the parent’s task, the run still starts and logs this warning to stderr: run task 'b' differs from parent run '<RUN_ID>' task 'a'; the lineage link crosses tasks. This applies only when the parent can be read, is in the same project, and has a task. --allow-cross-task or AGENTICML_ALLOW_CROSS_TASK=1 silences that warning when the cross-task link is intended. In Python, agenticml.init(parent_run_id=..., task=..., allow_cross_task=True) does the same.

A missing or unreadable parent is still recorded, with a warning. A parent in another project is recorded, but its task is not inherited.

A script that calls agenticml.init() joins the launcher’s run. Exit code 0 finishes the run as finished; any other exit finishes it as crashed, with _exit_code and _exception in the summary. Your script’s exit code is preserved, and SIGTERM finishes the run and exits 143.

Advanced

Multiple lineages in one working directory (tasks)

Section titled “Multiple lineages in one working directory (tasks)”

A lineage is grouped by project and task. Runs with the same task form one lineage lane. Use a different task to start a separate lineage in the same directory.

Set the task per run:

Terminal window
agenticml run --task alpha train.py
AGENTICML_TASK=alpha agenticml run train.py

Or set it per directory with an agenticml.toml file:

task = "alpha"

agenticml reads the nearest agenticml.toml from the script’s folder up to the repo root.

Task precedence: --task > AGENTICML_TASK > the parent run’s task > agenticml.toml task > the entry script’s folder (relative to the repo root). A script at the repo root with no task signal goes into a “no task” lane.

A task is trimmed, must be 1 to 128 characters, and cannot contain control characters. See Lineage parent and task for the full rules. Use --allow-cross-task only to silence the cross-task warning when the cross-task link is intended.

agenticml lineage ls shows the lanes:

proj
[beta]
20261101T172034-fe500858 train.py
[no task]
20261101T172033-df1b1ee7 train.py
[alpha]
20261101T172032-3a1a2f2a train.py

By default, agenticml infers the parent: the latest earlier run in the same project and the same task. A run from the same repo root is preferred.

To choose the parent yourself, pass --parent RUN_ID (or --parent=RUN_ID, or env AGENTICML_PARENT). The CLI flag wins over the env var. Find run ids with agenticml lineage ls.

Terminal window
agenticml run --task alpha --parent 20261101T172032-3a1a2f2a train.py

After two runs in task alpha, the second run’s metadata records parent_run_id as the first run, with parent_inference set to repo_root. An explicit --parent records parent_inference as explicit.

--parent applies to new runs only. See Lineage parent and task for the rest.

agenticml lineage checkout RUN_ID creates a separate, detached git worktree at the code snapshot that run captured. It does not switch the branch of your own working copy.

Terminal window
agenticml lineage checkout 20261101T172034-fe500858
cd "$(agenticml lineage checkout 20261101T172034-fe500858)"

The command prints the path it created. The default location is <store>/worktrees/<project key>/<RUN_ID>. The store is ~/.agenticml unless --dir or AGENTICML_DIR is set.

  • --path DIR chooses the location: agenticml lineage checkout RUN_ID --path ./run-alpha
  • --dir DIR sets the store root.
  • Running checkout again for the same run returns the same path and does not fail.
  • It fails if the destination exists and is not a checkout of that run.

To compare two runs, agenticml lineage diff RUN_A [RUN_B] lists the files added, deleted or changed between them.