Skip to content

Plugin system

Automax plugins are named operations loaded through the plugin registry.

Only canonical names are public DSL names. For example:

fs.file.template
system.service.restart
database.sqlite.query

Aliases are intentionally not exposed by automax plugins list.

Inspect plugins

automax plugins list
automax plugins describe fs.file.template
automax plugins describe fs.file.template --json
automax plugins coverage --format=markdown --output plugin-coverage.md
automax plugins coverage --strict
automax plugins audit

Metadata

Every builtin plugin has structured metadata:

  • name;
  • category;
  • description;
  • required parameters;
  • optional parameters;
  • parameter types and defaults;
  • result fields;
  • examples;
  • remote-session and dry-run flags.

automax plugins coverage turns that metadata into an operator matrix. The report lists category, remote-session, check-mode, dry-run, manual preview, diff preview and external tool coverage for every registered plugin. Use --strict in CI or release checks to fail when metadata or preview quality gates regress.

The generated plugin reference is built from this metadata:

automax docs generate-plugins --output docs/plugins/generated.md

External plugins

The core execution engine is independent from the builtin plugin set. Future external plugins can be registered without changing job orchestration, state storage or SSH connection handling.

External plugin sources can be created with automax plugins init, validated with automax plugins check, packaged with automax plugins package, verified with automax plugins verify-package, indexed with automax plugins index for repository publishing and installed into a controlled local plugin directory with automax plugins install. The same --plugin-path option accepts source files, source directories, verified package ZIPs and directories containing installed package ZIPs. Package ZIPs are verified for manifest consistency, file size and SHA-256 checksum before plugin classes are loaded.

External plugin package indexes include package checksums and can be checked with scripts/check-plugin-index-policy.sh. Signature enforcement remains operator policy.