Skip to main content
run-bounded: a command arrow stopped by a limit

run-bounded

한국어

A command-line tool and Python library for running commands with time, output, and process-tree limits.

Rust 1.82+ · Python 3.10+

pypi rust license

5.3 ms per run; a Python subprocess.run call to the same command takes 37.9 ms. Both from the saved 30-run hyperfine file.

Install · Quick start · Why

The run-bounded CLI prints child output and a JSON result

The demo uses printf with fixed text. It shows command output, not a benchmark.

Install

pipx install run-bounded
uv tool install run-bounded
pip install run-bounded

Python 3.10+. Wheels for macOS, Linux and Windows install the run-bounded binary and the importable Python package bounded_run; no Rust toolchain is needed.

From source (Rust 1.82 or newer):

git clone https://github.com/elfenomenokim/run-bounded
cd run-bounded
cargo install --locked --path .

Quick start

run-bounded --timeout 5 --idle 2 --max-output 1K -- printf 'bounded output\n'

printf resolves through PATH. Absolute executable paths also work. Relative paths containing / or \ are rejected.

The child keeps stdout and stderr. The command writes one JSON result line to stderr:

bounded output
{"class":"ok","duration_ms":6,"exit_code":0,"stdout_truncated":false,"stderr_truncated":false}

--timeout sets wall seconds. --idle sets seconds without output. --max-output sets the default per-stream byte cap (--max-stdout and --max-stderr override each stream); K, M, and G use powers of 1024. Zero disables a time limit. Child stdin is closed by default unless --stdin inherit or --input is given. The child receives a small environment with PATH, locale, home, temporary-directory, and Windows system variables.

Run in a specific directory with separate stream caps, passed input, and --kill-on-cap:

run-bounded --cwd /tmp --input $'line 1\nline 2\n' --max-stdout 7 --max-stderr 256 --kill-on-cap -- cat
line 1
{"class":"output_limit","duration_ms":5,"exit_code":0,"stdout_truncated":true,"stderr_truncated":false}

Why

run-bounded drains stdout and stderr independently and limits each stream. On Unix, it starts a new process group and sends TERM followed by KILL when a limit expires. Windows assigns the child to a Job Object and terminates the job on timeout. The Rust CLI is one binary; the Python edition is importable without a native extension. feno-cli keeps its existing run_process_group API.

Tool Wall timeout Output cap Grandchild after timeout
run-bounded yes per stream terminated on macOS, Linux, and Windows checks
coreutils gtimeout yes no remained alive in the macOS check
Python subprocess.run(timeout=...) yes no remained alive in the macOS check

How it works

The runner starts a child, drains both streams, waits for exit or a deadline, and terminates the process tree on timeout

The source is flow.mmd; the Korean README has Korean labels.

Measurements

These are hyperfine 2.0.0 wall-time means and standard deviations for /usr/bin/true. The host was macOS 27.0 on arm64. Each command ran 3 warmups and 30 measured runs. Python command rows include starting the Python interpreter for each run.

Mean wall time: run-bounded 5.3 milliseconds, gtimeout 6.2, Python subprocess.run 37.9, Python library command 61.7
Command Mean ± standard deviation
run-bounded CLI 5.3 ± 0.8 ms
gtimeout 6.2 ± 0.7 ms
Python subprocess.run 37.9 ± 3.5 ms
Python library command 61.7 ± 15.4 ms

Re-run from the CCH repository root. The saved measurements are in macos-27-arm64-20261117.json.

cargo build --locked --release --manifest-path docs/products/feno-cli/bounded-run/Cargo.toml
hyperfine --shell=none --warmup 3 --runs 30 \
  --export-json docs/products/feno-cli/bounded-run/docs/bench/macos-27-arm64-20261117.json \
  --command-name 'run-bounded' './docs/products/feno-cli/bounded-run/target/release/run-bounded --timeout 5 --idle 2 -- /usr/bin/true' \
  --command-name 'gtimeout' '/opt/homebrew/bin/gtimeout 5 /usr/bin/true' \
  --command-name 'Python subprocess.run' '/usr/bin/python3 -c "import subprocess; subprocess.run([\"/usr/bin/true\"], check=True)"' \
  --command-name 'Python library' '/usr/bin/python3 -c "import sys; sys.path.insert(0, \"docs/products/feno-cli/bounded-run/python\"); from bounded_run import run; run([\"/usr/bin/true\"])'

Inside an already-started Python interpreter, bounded_run.run() had a 3.5 ms median over 30 calls; the saved samples include the command and host details. The grandchild comparison used a child that ignored TERM and slept for 30 seconds. run-bounded removed it; gtimeout and subprocess.run(timeout=...) left it alive.

Reference

run-bounded [--timeout SEC] [--idle SEC] [--max-output BYTES] [--max-stdout BYTES] [--max-stderr BYTES] [--kill-on-cap] [--cwd DIR] [--stdin null|inherit] [--input TEXT] -- COMMAND [ARGS...]

COMMAND can be an absolute executable path or a bare name found on PATH. --cwd sets the working directory. --stdin defaults to null (closed); pass inherit to keep parent stdin, or --input to feed UTF-8 text and close stdin. --max-stdout and --max-stderr override --max-output per stream. --kill-on-cap terminates the process group or Job Object when either stream exceeds its cap and classifies the run as output_limit (exit code 1).

The library is bounded_run.run(command, *, timeout=60, idle=20, max_output=1048576, max_stdout=None, max_stderr=None, kill_on_cap=False, cwd=None, stdin=None, input=None, env=None). stdin defaults to closed (DEVNULL), accepts "inherit" or a readable file/fd, and input accepts bytes or str. It returns a RunResult with classification, duration, returncode, captured stdout and stderr bytes, and one truncation flag per stream. Classifications are ok, failed, timeout, idle, output_limit, or signal.

Platforms

The CLI was built and exercised on macOS 27.0 arm64, Ubuntu 24.04 arm64 on A1, and Windows build 26340 x64 (reported OS version 10.0.26340.0). The Python library was exercised on macOS and Windows. The Windows Rust build used the laptop's existing Rust 1.100 GNU toolchain. Timeout and idle return 124, output-limit kills return 1, CLI errors return 125, and normal child failures retain the child's exit code. A child terminated by a signal returns 128 plus the signal number, and its JSON exit_code is null. A consumer that stops reading its output cannot delay a timeout result: once a limit terminates the child, both editions report the timeout without waiting for the blocked output write or for a descendant that left the process group. When the runner itself receives SIGINT, SIGTERM or SIGHUP, it stops the child tree first; a Windows job also ends its children when the runner closes it.

Contributing

Run cargo build --locked from this directory. Issues and platform reports are welcome. See CONTRIBUTING.md for the tests and the review process.

License

MIT. See LICENSE.

Metadata

Release files for run-bounded 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for run-bounded 0.1.3
File Size Uploaded Provenance Actions
run_bounded-0.1.3.tar.gz 231.2 kB Without provenance Details for run_bounded-0.1.3.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for run-bounded 0.1.3
File Actions
run_bounded-0.1.3-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for run_bounded-0.1.3-py3-none-win_amd64.whl
run_bounded-0.1.3-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for run_bounded-0.1.3-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
run_bounded-0.1.3-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for run_bounded-0.1.3-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
run_bounded-0.1.3-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for run_bounded-0.1.3-py3-none-macosx_11_0_arm64.whl
run_bounded-0.1.3-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for run_bounded-0.1.3-py3-none-macosx_10_12_x86_64.whl

Total release size: 1.5 MB

Release files / run_bounded-0.1.3.tar.gz

Download URL run_bounded-0.1.3.tar.gz
Size 231.2 kB
Tags Source
SHA-256 checksum
How to use checksums
0918818cd3a5f00ecd7708aaf50d0873e835898cd84b9f8328d6334a4a78c7e4
BLAKE2b-256 checksum
How to use checksums
4785b35b54c60b3c3f048bcd27d6689c5f9f78d9e7fc7ff42e8333f8012157b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / run_bounded-0.1.3-py3-none-win_amd64.whl

Download URL run_bounded-0.1.3-py3-none-win_amd64.whl
Size 187.3 kB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
3c116a2fceaf6472b95facc9ad8ae1d274e902455339d9ce9459060d1df54ea1
BLAKE2b-256 checksum
How to use checksums
4de2a3cec1ab682e70802a383059730c89f11ab4629cc83ad63dafbdc523f2a0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / run_bounded-0.1.3-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL run_bounded-0.1.3-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 269.4 kB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
4b1dcf4164b149ed6e66bc29c9ff8af23852e9486e540b13b1726df18487b9c4
BLAKE2b-256 checksum
How to use checksums
51a77bef7046de43c5c147c9fc8311524bc6bf05e1084bdb492be2e55762abf2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / run_bounded-0.1.3-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL run_bounded-0.1.3-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 262.5 kB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
7b617bca4a2f556e53d11d114644ea4ce68877631f9b46e3c26a00ba9b189b08
BLAKE2b-256 checksum
How to use checksums
6a054ea9499aebea5b5e9babc0a62562002b02b75e2da13e675d433446e78316
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / run_bounded-0.1.3-py3-none-macosx_11_0_arm64.whl

Download URL run_bounded-0.1.3-py3-none-macosx_11_0_arm64.whl
Size 251.6 kB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
09079ac9b6d0976dbfd4b9c0e0acc98a273a4494ba73c2c197e45175fee31d85
BLAKE2b-256 checksum
How to use checksums
51f213ff34dda3872bc9cd28a76cd3008ee7578936f7d20c73353941ef084537
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / run_bounded-0.1.3-py3-none-macosx_10_12_x86_64.whl

Download URL run_bounded-0.1.3-py3-none-macosx_10_12_x86_64.whl
Size 256.0 kB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
111d8c7e599a6a7dcb40eed6713a8c4929a1d87675d2be6878d10b1b558d657e
BLAKE2b-256 checksum
How to use checksums
1858d7f20900374e0932dafb3f5e10ccd3c6d16d8db1d87709f1ed836ec4187e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Security for run-bounded 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.3 This release

6 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page