Skip to content

Automax

Automax is a Python, YAML-driven SSH automation engine for operators who need repeatable infrastructure jobs without embedding operational data inside the application source tree.

It runs external job definitions against external inventories, stores every run in a resumable state directory, and exposes automation through small builtin or external plugins.

Job
  Task[]
    Step[]
      Substep[]

Why Automax

Automax is built around a few strict choices:

  • External operations: jobs, inventories, variables and secrets are passed by path from the CLI.
  • SSH-first execution: a step opens one fresh SSH connection per target and runs all matching substeps through that connection.
  • Resumable runs: every execution gets a run id, SQLite state, failed-node tracking, artifacts and ready-to-copy resume commands.
  • Explicit plugins: builtin plugin names are canonical and inspectable with automax plugins list and automax plugins describe.
  • Security-conscious defaults: SSH host keys are rejected by default unless a lab inventory explicitly opts into insecure behavior.

Start here

For a complete first run, use the Quickstart.

For installation and local development setup, use Installation.

For a first real SSH job against a remote host, use First SSH job.

What the public documentation covers

Area Page
Install and validate the tool Installation
Run the first local smoke job Quickstart
Write job YAML Writing jobs
Understand task/step/substep execution Execution model
Configure inventory, vars and secrets Inventory, variables and secrets
Resume failed jobs State store and resume
Inspect job scope, secrets, check-mode, diffs and manual recovery commands Job Inspection and Recovery
Inspect captured files and outputs Artifacts
Inspect every CLI command CLI reference
Review SSH and secret handling Security reference
Browse builtin plugins Builtin plugins
Validate a real SSH runtime Extended SSH smoke
Prepare releases Release process

Minimal local smoke

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

python -m automax run \
  --job examples/jobs/local-smoke.yaml \
  --inventory examples/inventory/local.yaml

Inspect the run:

automax runs list
automax runs show <run-id>

Plugin discovery

automax plugins list
automax plugins describe fs.file.template
automax docs generate-plugins --output docs/plugins/generated.md

The generated reference is published under Generated plugin reference.