Register and run scripts

Scripts let you run automation on suitable workers without writing a full worker. Kiwi Distro tracks the script catalogue, versions, authorisation and which workers can run which executors.

Executors#

An executor defines how to run a script: python, node, linux_shell, powershell, windows_batch, auto_it, autohotkey and playwright. List the effective definitions (built-ins plus any overrides):

kiwi distro list-executors

Workers advertise which executors they support, their platform (windows, linux, macos), whether they have an interactive desktop, and whether they have a browser runtime. Scripts that need a desktop (AutoIT, AutoHotkey) or a browser (Playwright) are only sent to workers that provide it.

1. Register the script#

kiwi distro register-script --service-id <service-id> --name monthly-report --executor python \
  --entry main.py --params "month:named:string:req,verbose:env:boolean" --timeout 5M --platforms linux

--entry is the entry file inside the bundle. --params declares parameters as name:binding[:type][:req]; use --params-file for a full JSON specification. Add --interactive or --browser when the script needs a desktop or a browser.

2. Upload a version#

kiwi distro upload-script-version --script-id <script-id> --script-version 1.0.0 --file report.zip --notes "First release"

A single file or a .zip bundle is accepted. New versions start as pending.

3. Authorise it#

kiwi distro authorize-script-version --script-id <script-id> --script-version 1.0.0

Only authorised versions can run. This requires an administrator, and disable-script-version withdraws a version.

4. Run it#

kiwi distro execute-script --script hello-svc/monthly-report --params month=9,verbose=true --follow

--follow streams the script's console output live and then shows the result. Pin a version with --script-version, and pass extra environment variables with --env-params KEY=value. run-script is the same command kept for compatibility.

Audit#

kiwi distro script-audit --script-id <script-id>

Runs, uploads and authorisations are recorded.

From Kiwi Flow#

A workflow reaches any registered script with one activity type, kiwi_distro_script, no matter which executor runs it. See Run scripts and remote work with Kiwi Distro.