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+
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 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 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.
| 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)
| 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)
| File | Actions Reset | |||
|---|---|---|---|---|
| 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.