Cronomicon

How to run Python well inside Cronomicon: how a python run actually reaches its target and what interpreter it expects there, how env, run inputs and outputs look from inside a Python script, why input() can never work and what to use instead, the exit-code semantics that decide whether your run reads Success or Failed, and how the Scripts catalog detects the variables your code consumes.

Python is a shell-family run type, so most of the machinery is shared with Bash: read the Bash Guide for the two-executor model, targeting, bastions and secrets in full depth — this guide states the shared rules briefly and goes deep only where Python differs. Companions: the User Manual, the Administrator Manual (§4, SSH executor), and the Runner Install Guide / Runner Config Guide / Runner Security Guide guides.

The one-sentence model. A Python script is a Script (run type python), a Scope names the hosts it may touch, a Job binds the two to schedules and env — and the run executes over SSH: the dialing side (the Cronomicon server or a runner) connects to each target and invokes python3 there.

1 · How a Python run reaches its target

Like Bash, a python run can execute on either executor — the in-app SSH executor (the default via the resolution chain; the pool is off until an operator sets CRONOMICON_SSH_EXECUTOR_ENABLED=true, or shell-family runs queue forever) or a runner inside the target's segment. On both, the mechanics are identical: the dialing side opens an SSH connection to each target and runs your script with python3 on the target. A run with no injected environment invokes python3 -c '<your body>'; the moment the run carries env (job env, schedule env, overrides, bound references, run-input answers), the invocation becomes python3 - and the program — an os.environ prelude plus your body — arrives on stdin, so no value ever touches argv (§4). Two consequences worth internalizing:

• The target needs python3 on the SSH session's PATH. The invocation names python3 explicitly — modern Linux distributions ship it; a legacy target that installs only python needs the name provided (a symlink, or the distro's python-is-python3 package) or the run fails per-host with command not found. Python 2 is never invoked: write for Python 3, and treat the oldest interpreter across your fleet as the floor your syntax must clear.
• Your program IS the stdin. With python3 -, the interpreter reads the whole program from stdin — which means your script cannot then read stdin itself: input() raises EOFError, and sys.stdin is exhausted. This is not a defect to work around; there is no operator at a TTY on either executor. Declare questions as run inputs and read the answers from the environment (§4).

Runner capability nuance. A runner claims the python run type when python3 (or python) is on its own PATH — the auto-detect probe — even though execution happens on the targets over SSH. For a runner host without a local interpreter that serves Python-capable targets, declare the capability explicitly (-capabilities bash,python / CRONOMICON_RUNNER_CAPABILITIES); otherwise the run queues “waiting for a python-capable runner.”

2 · Getting scripts in

Identical to the rest of the catalog (Bash Guide §2 in depth): any raw *.py under scripts/ in the definitions repo is auto-discovered as a Script with run type python (the name keeps its extension; sub-folders shape the catalog's folder tree); or author a kind: Script YAML with exactly one of command / script / scriptPath and optional declared prompts; jobs bind by script_ref, or in-app via the Composer. Wire cronomicon validate . into CI — and ruff (or flake8) sits beside it as naturally as shellcheck does for bash.

The catalog reads your code for its variables. The Scripts view's “Variables this script uses” — the same list the Run dialog and Composer hint from — comes from a heuristic scan of environment access in the body:

• os.environ['NAME'] (either quote style) reads as required — a direct subscript raises KeyError when the key is absent, so there is no default to fall back on.
• os.environ.get('NAME', default) and os.getenv('NAME', default) read as optional when the second argument is present — the Python mirror of the shell's ${VAR:-default}.
• The leading os. is optional, so from os import environ, getenv idioms are still detected. Ordinary locals are never reported, and it is a heuristic, not a parser — a name built at runtime (os.environ[prefix + "_KEY"]) is invisible to it. Declared run inputs always beat the inferred list.

3 · Targets: what differs from Bash

Targeting follows the shared shell-family rules — a scope fans out to its member hosts, a pinned target_host wins outright on every run path, a per-run host subset is SSH-executor-only (422 scope_membership otherwise), host keys fail closed on both executors. One thing is Python-specific:

• Declare python on the scope. The “bash floor” means every scope supports bash; any other run type is a declared chip on the scope, so add python to the scopes whose hosts carry an interpreter. A pragma does the same for a Git-synced inventory: # cronomicon:v1 types=bash,python.

4 · Env, run inputs, outputs — and exit codes that tell the truth

Reading the environment

Injected environment (job env ← schedule env ← per-run overrides, plus bound references and the dispatcher's CRONOMICON_RUN_* context set) arrives as an os.environ prelude ahead of your body, delivered on stdin — never argv, never /proc-visible. By the time your first line runs it is ordinary environment:

import os

release = os.environ["TARGET_RELEASE"]              # a run-input answer — required
api_key = os.environ["CRONOMICON_SECRET_API_KEY"]      # a bound secret reference
region  = os.getenv("REGION", "us-east-1")          # optional, with a default
print(f"run {os.environ['CRONOMICON_RUN_ID']} on scope {os.environ['CRONOMICON_RUN_SCOPE']}")

Because the prelude sets os.environ in-process, child processes you spawn (subprocess.run) inherit everything automatically, exactly as they would from an exported shell variable.

Run inputs, not input()

input() raises EOFError on both executors (§1) — there is no TTY and stdin already carried your program. Declare operator questions as run inputs (spec.prompts — name, label, required, default, options); the Run dialog asks, records provenance, and the answers arrive as env vars. prompt_enforcement: block makes a missing required answer reject the run instead of warning.

Exit codes & exceptions

Exit 0 is success; anything else fails that host, and per-host results aggregate — all ok → success, all failed → failure, mixed → warning (partial). Python makes the honest default easy: an uncaught exception exits 1 with a traceback in the run log, so the anti-pattern is not silent success but the opposite — a bare except Exception: pass that swallows the failure and exits 0. Catch what you can handle, let the rest propagate, and use sys.exit(n) (or raise SystemExit(n)) when you classify failures yourself.

Passing data to downstream workflow steps (A12)

Print the marker on stdout, exactly as in Bash:

print(f"::cronomicon-output name=VERSION::{version}")

A downstream step declares an input bound to that output and receives it as an env var. If a captured value carries an injected secret, the executor drops all captured outputs and fails the run (output_secret_leak) rather than let the secret propagate — emit something derived, never the secret itself. If your script prints volumes of output, remember the marker must be its own line on stdout (not stderr, not inside JSON you dump).

5 · Secrets in Python

The full model — reference bindings, fail-closed resolution, redactor seeding, the runner-side Secret injection flag — is in Bash Guide §5 and applies unchanged: bound Secrets and Variables arrive as CRONOMICON_SECRET_<name> / CRONOMICON_VAR_<name> in os.environ, delivered over stdin, never argv. The Python-shaped edges:

• Keep secrets off child argv. subprocess.run(["mytool", "--token", token]) puts the value in the target's process table — the exact /proc/<pid>/cmdline exposure the stdin delivery exists to prevent, and Cronomicon's log redaction cannot reach a remote process table. Pass it through the child's environment (env={**os.environ, "TOKEN": token} — or simple inheritance, since os.environ already carries it) or through input= on a pipe.
• Don't re-broadcast what you fetch yourself. Redaction masks injected values in stored logs; a value your script retrieves at runtime (an API call, a decrypt step) was never registered with the redactor. Don't print it, don't log it, don't json.dumps a config object that embeds it.
• Escalation follows the Bash rules. There is no become primitive for shell-family runs; prefer a scoped NOPASSWD rule. Where a password is unavoidable, bind it as a reference and feed sudo -S via a pipe: subprocess.run(["sudo", "-S", "-p", "", "systemctl", "restart", "myapp"], input=os.environ["CRONOMICON_SECRET_BECOME_PASSWORD"] + "\n", text=True) — stdin again, never argv.

6 · Best-practice checklist

• Let exceptions propagate — a traceback that fails the run beats an except: pass that reports success. Never exit 0 unless the work truly succeeded.
• Write for the fleet's oldest python3. The target's interpreter runs your code; f-strings need 3.6, := needs 3.8 — one ancient host in the scope decides.
• Standard library first. Your script runs under the target's interpreter — a pip install dependency must exist on every host in the scope, and Cronomicon does not install packages for you. If you need real dependencies, manage them on the targets (or reach for Ansible, which exists for exactly that shape of work).
• Be idempotent — retries, schedule re-fires and operator re-runs all mean “again.”
• Run inputs instead of input(), ::cronomicon-output markers instead of temp files, env instead of argv for anything sensitive.
• Bound everything: a realistic timeout_seconds, concurrency_policy: Forbid (or Queue) for non-reentrant scripts.
• Keep scripts in Git behind script_ref; lint with ruff + cronomicon validate in CI.

7 · Troubleshooting

Anything not listed here — host keys, bastions, cred_error/conn_error, scope membership, timeouts, executor_lost — behaves exactly as for Bash: see Bash Guide §7.