Skip to content

Creating plugins

Automax plugins are small execution units loaded by the plugin registry.

A plugin should keep business logic outside the engine and expose one canonical DSL name, for example fs.dir.create or system.service.restart.

Contract

A plugin receives:

  • rendered input parameters from the substep with: block;
  • the current target server context;
  • an optional SSH session when the plugin is remote;
  • the runtime context and registered outputs.

A plugin returns a structured result with at least:

ok
changed
failed
skipped
outputs
message

Naming rules

Use canonical names only:

category.action

Good examples:

fs.file.template
os.package.install
system.service.enable
data.transfer.upload

Avoid shortened or ambiguous names. Public DSL names should stay canonical, explicit and stable.

Design rules

  • validate required parameters before executing anything;
  • prefer idempotent behavior when possible;
  • never hide unsafe behavior behind defaults;
  • return machine-readable outputs for register: mappings;
  • keep ambiguous aliases out of public docs and CLI output unless they are explicitly part of a documented extension contract.

Inspecting plugin metadata

Use automax plugins describe to inspect a builtin or externally loaded plugin:

automax plugins describe fs.file.template
automax plugins coverage --plugin-path ./plugins --strict
automax plugins audit --plugin-path ./plugins

The describe command prints the canonical name, description, required parameters, optional parameters and whether the plugin opens a remote SSH session. The coverage command renders a matrix for builtin and external plugins and can fail the build when metadata, preview or dry-run quality gates regress. External plugins loaded with --plugin-path are described and audited through the same registry contract.

External plugin SDK workflow

Use the SDK commands to create a checked plugin source file before loading it in jobs or release pipelines:

automax plugins init company.echo --output ./plugins
automax plugins check ./plugins
automax plugins package ./plugins --output dist/company-plugins.zip
automax plugins verify-package dist/company-plugins.zip
automax plugins index dist/company-plugins.zip --output dist/automax-plugins-index.json
automax plugins install dist/company-plugins.zip --dest .automax/plugins
automax plugins installed --dest .automax/plugins
automax plugins describe company.echo --plugin-path ./plugins
automax plugins describe company.echo --plugin-path dist/company-plugins.zip
automax plugins describe company.echo --plugin-path .automax/plugins

plugins init writes a minimal plugin class with canonical metadata, parameter schema, examples and result fields. plugins check loads the external path without builtin plugins and fails when the metadata contract is incomplete. plugins package runs the same validation before producing a ZIP archive with the plugin sources, automax-plugin.json, Automax compatibility metadata and per-file SHA-256 checksums. plugins verify-package validates that manifest and checksums. plugins index writes a deterministic JSON index for verified ZIP packages so shared plugin repositories can publish an auditable package list before any package is copied into a controlled plugin directory.

The packaged plugin can be loaded directly with the existing --plugin-path option used by run, validate, review, plan, plugins describe, plugins coverage and documentation generation commands. Automax verifies the package manifest, file sizes and SHA-256 checksums before loading Python plugin sources from the ZIP.

plugins install copies a verified ZIP into a controlled plugin directory and writes automax-plugins.lock.json with the installed package checksum. plugins update replaces an installed ZIP only after package verification, and plugins uninstall removes both the ZIP and its lock entry. Passing that directory to --plugin-path loads every top-level .py file and verified, lock-matching .zip package it contains, so operators can keep a stable plugin directory instead of listing each package path on every command.

A packaged sample collection is available in examples/external-plugins/ and exports company.demo.hello.