runwisp-jobkit: a shell-free harness for RunWisp jobs

runwisp-jobkit is a small harness for validating and running filesystem job packages without leaning on ad-hoc shell glue. A job is a directory: a job.toml manifest plus whatever files the command needs.

This post is a practical tour: the model, the CLI, a complete manifest, and a minimal Python job.

Install

After the first PyPI release:

uv tool install --python 3.14 runwisp-jobkit

From a local checkout at the repo root:

uv tool install --force --python 3.14 .

The contract: `job.toml`

Every job directory contains a manifest. Here is a complete example with all seven fields:

schema = 1
id = "example-job"
kind = "command"
cwd = "."
argv = ["python", "run.py"]
required_env = ["EXAMPLE_MESSAGE"]
required_files = ["run.py"]

Field	Role
`schema`	Manifest version
`id`	Stable job identifier
`kind`	Execution kind (`command` today)
`cwd`	Working directory relative to the package
`argv`	Command and arguments to exec
`required_env`	Env vars that must be present before run
`required_files`	Files that must exist in the package

The harness does not install dependencies, discover jobs, store secrets, or manage RunWisp policy. Packages and their deployment environment own those concerns.

CLI: doctor, then run

runwisp-job doctor JOB_DIR
runwisp-job run JOB_DIR [ARG ...]

doctor validates the package without executing the job.
run appends each supplied argument to the manifest command unchanged, then replaces the harness process with the job process.

That split keeps “is this package well-formed?” separate from “execute it.”

Minimal Python job

A tiny package might look like:

example/
 job.toml
 run.py

schema = 1
id = "hello-python"
kind = "command"
cwd = "."
argv = ["python", "run.py"]
required_env = ["EXAMPLE_MESSAGE"]
required_files = ["run.py"]

import os
import sys

def main() -> None:
 message = os.environ["EXAMPLE_MESSAGE"]
 print(message)
 if len(sys.argv) > 1:
 print("args:", " ".join(sys.argv[1:]))

if __name__ == "__main__":
 main()

Validate and run:

export EXAMPLE_MESSAGE="hello from runwisp"
runwisp-job doctor ./example
runwisp-job run ./example -- --verbose

Language templates

The repository ships immediately runnable templates for:

Python
TypeScript (Bun)
Rust
Shell

There is also a sanitized nightly news example derived from a production-style job (some private dependencies intentionally omitted).

Why this shape

Shell-only job packaging tends to grow silent assumptions: cwd, env, missing files, half-documented argv. A filesystem package plus a validated manifest makes those assumptions explicit and checkable with doctor before anything runs.

If you want the design details and error semantics, see the authoring docs in the repository (link the real URL when the repo is public) and the project page on this site.

Point the project page and README at this post as the narrative companion.
Syndicate a version to Dev.to with a canonical URL pointing here.
Follow up with posts on packaging conventions and CI validation patterns.