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+

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

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

cargo install puts the run-bounded binary in ~/.cargo/bin. For the Python library, build the wheel from the same checkout: python3 -m pip wheel --no-deps -w dist . and install the file in dist/. The package is not on PyPI yet.

Rust 1.82 or newer is needed; the wheel installs the same binary and the importable Python package bounded_run.

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 a per-stream byte cap; K, M, and G use powers of 1024. Zero disables a time limit. The child receives a small environment with PATH, locale, home, temporary-directory, and Windows system variables.

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] -- COMMAND [ARGS...]

COMMAND can be an absolute executable path or a bare name found on PATH. The library is bounded_run.run(command, timeout=60, idle=20, max_output=1048576). 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, 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, 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.2

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.2
File Size Uploaded Provenance Actions
run_bounded-0.1.2.tar.gz 225.8 kB Without provenance Details for run_bounded-0.1.2.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for run-bounded 0.1.2
File Actions
run_bounded-0.1.2-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for run_bounded-0.1.2-py3-none-win_amd64.whl
run_bounded-0.1.2-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.2-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
run_bounded-0.1.2-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for run_bounded-0.1.2-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
run_bounded-0.1.2-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for run_bounded-0.1.2-py3-none-macosx_11_0_arm64.whl
run_bounded-0.1.2-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for run_bounded-0.1.2-py3-none-macosx_10_12_x86_64.whl

Total release size: 1.4 MB

Release files / run_bounded-0.1.2.tar.gz

Download URL run_bounded-0.1.2.tar.gz
Size 225.8 kB
Tags Source
SHA-256 checksum
How to use checksums
3f7f29c92d4cb9dae9ab3d95829d5735be7fd8fa5c6c5a3c70473effb701cd45
BLAKE2b-256 checksum
How to use checksums
5e4029a3e047106a097c58cbabb5d7b66c1520fd1226f7214e3474fb3ef7434f
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.2-py3-none-win_amd64.whl

Download URL run_bounded-0.1.2-py3-none-win_amd64.whl
Size 179.5 kB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
79679f6ecc481f8ced5b670ec853ea0c966b4b1af9e158de8a3b47ad476fa8c0
BLAKE2b-256 checksum
How to use checksums
cbed70b25ad0bcbdeface1ea44bfceb097ad99f9982246e861791ca7a2b9bb33
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.2-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL run_bounded-0.1.2-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 264.3 kB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
567c78d28a881c81f7252c7b3e9e7506b6f3a423daa86fda7a2dea735ab8e913
BLAKE2b-256 checksum
How to use checksums
6f4cef668a5c7cf3813824c2bb9ce30336952fd90a0f7855e8ae9f674900a001
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.2-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL run_bounded-0.1.2-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 257.0 kB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
07cb4e48fba18e8606b61867749d9de71a8bc27be9f30f7f7384360435b68302
BLAKE2b-256 checksum
How to use checksums
b8cecd1c5880fdb7c1406b16a89ba4abad998c9f3124235b7cd3f066d44adee0
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.2-py3-none-macosx_11_0_arm64.whl

Download URL run_bounded-0.1.2-py3-none-macosx_11_0_arm64.whl
Size 247.5 kB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
89953b595e653f69e9726605e13dd213ae8caf7ad6fbeafbb1202d6ddecd477e
BLAKE2b-256 checksum
How to use checksums
c470616cd19c6d5e8305ba7414a4c44d9e8b5d4b4db6a01e2e86ebf54508ed41
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.2-py3-none-macosx_10_12_x86_64.whl

Download URL run_bounded-0.1.2-py3-none-macosx_10_12_x86_64.whl
Size 252.8 kB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
bb36ffacb027bc46e53437502244f1af35e2c95f833b4147f521ffd782a937c6
BLAKE2b-256 checksum
How to use checksums
6a07f2380affaafd4d9e1608743a64b98a7dccd4af2687c050aa2bafa828d0cd
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.2

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.2 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