Skip to content

Quickstart

This quickstart uses only files already present in the repository and does not require a remote server.

1. Create a virtual environment

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e '.[dev]'

2. Validate the example job

automax validate \
  --job examples/jobs/local-smoke.yaml \
  --inventory examples/inventory/local.yaml

Validation checks the YAML shape, inventory resolution, plugin names and plugin parameters before a run starts.

3. Preview the execution plan

automax plan \
  --job examples/jobs/local-smoke.yaml \
  --inventory examples/inventory/local.yaml

Typical output:

controller task.smoke:step.local:substep.echo plugin=command.local.run tags=-

4. Run the job

automax run \
  --job examples/jobs/local-smoke.yaml \
  --inventory examples/inventory/local.yaml \
  --state-dir .automax/runs

The run prints an operator summary and the generated run id.

Automax run completed
Run ID: 20260523-101530-local-smoke-a1b2c3d4
Status: success
State: .automax/runs/20260523-101530-local-smoke-a1b2c3d4

5. Inspect the run

automax runs list --state-dir .automax/runs
automax runs show <run-id> --state-dir .automax/runs

6. Inspect plugins

automax plugins list
automax plugins describe fs.file.template

7. Build the documentation

NO_MKDOCS_2_WARNING=1 mkdocs build --strict

For the full operator path against a remote host, continue with First SSH job.