Zero-code runs
agenticml run executes a script inside a run. The script does not need to import agenticml.
agenticml run train.pyagenticml run train.py --lr 1e-3agenticml run -m mypkg.trainagenticml run -m mypkg.train --epochs 3agenticml run --project demo -- python train.py --lr 1e-3agenticml python train.pyagenticml python train.py --lr 1e-3Script 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.
Command forms
Section titled “Command forms”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 ofpython .... - The default run name is the script’s repo-relative path, unless
--nameis given. - Only Python files are supported: no
python -cand no stdin scripts.
What gets captured
Section titled “What gets captured”| 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.
Options and environment variables
Section titled “Options and environment variables”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 |
Resuming a run
Section titled “Resuming a run”Resume an existing run or continue under a specific ID:
agenticml run --id 20261101T130355-1cded4a7 --resume must -- python train.py--idrequires--resume allowormust, and--resume allowormustrequires--id; otherwise it is a usage error (exit 2).mustrequires that the run already exists.allowresumes 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
--parentlogs a warning). Step counters continue from the last stored step, and aresumeevent is logged. - If a requested resume cannot be performed (the run is missing under
must, open in another process, pruned bysync --prune, or missingmeta.json),agenticml runprints an error and exits 2 without running the script. - If the script itself calls
agenticml.init(id=..., resume=...)underagenticml run, those arguments are ignored with a warning; configure resume through the CLI instead.
Setting configuration
Section titled “Setting configuration”Pass configuration values from the CLI or a file:
agenticml run --config lr=1e-3 --config amp=true --config layers='[64, 64]' -- python train.pyagenticml run --config-file base.json -- python train.py--config KEY=VALUE(repeatable):VALUEis parsed as JSON if valid (lr=1e-3becomes0.001,amp=truebecomes booleantrue,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 toNaNorInfinityare 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 <
--configpairs < script’s owninit(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.
Lineage parent and task
Section titled “Lineage parent and task”--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.
agenticml run --parent <RUN_ID> train.pyWithout --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.
Exit status
Section titled “Exit status”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:
agenticml run --task alpha train.pyAGENTICML_TASK=alpha agenticml run train.pyOr 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.pySpawning an experiment from a parent run
Section titled “Spawning an experiment from a parent run”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.
agenticml run --task alpha --parent 20261101T172032-3a1a2f2a train.pyAfter 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.
Checking out a run’s code
Section titled “Checking out a run’s code”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.
agenticml lineage checkout 20261101T172034-fe500858cd "$(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 DIRchooses the location:agenticml lineage checkout RUN_ID --path ./run-alpha--dir DIRsets 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.