Nuewframe - Platform Engineering & Edge Computing
GitHub Twitter

Meet timeout: Rust-Built, Cross-Platform, AI & CI-Ready

Every developer has been there: a test suite hangs indefinitely, a CI job runs for hours burning credits, or a script waits forever on a network call. You reach for timeout, but then discover it doesn’t work on Windows. Or it kills the parent process but leaves zombie children. Or it can’t send custom signals for graceful shutdown.

Today we’re introducing timeout — a modern, cross-platform CLI tool that solves these problems with true process group handling, configurable termination behavior, and first-class Windows support.

The Problem with Existing Timeout Tools

GNU timeout has been the Unix standard for years, but it has significant limitations:

  • No Windows support — Different tool, different syntax, different behavior
  • Limited process group handling — Child processes often survive termination
  • Platform-specific quirks — What works on Linux may fail on macOS
  • Integration friction — Exit codes and error handling vary across implementations

For teams running cross-platform CI/CD, this creates operational complexity. You need different scripts for different platforms, different fallback strategies, and constant debugging of “works on my machine” timeout issues.

What Makes Nuewframe timeout Different

Built in Rust with Tokio’s async runtime, our timeout tool provides:

True Cross-Platform Support

One binary, one syntax, consistent behavior across Linux, macOS, and Windows:

# Works identically everywhere
timeout 30s -- cargo test
timeout 5m -- npm run build
timeout 1h -- python train_model.py

On Windows, we use Job Objects for proper process tree termination. On Unix, we leverage process groups with configurable signal handling. The user experience is unified.

Process Group Termination

When your command spawns child processes, timeout terminates the entire tree:

# This script spawns multiple background processes
timeout 10s -- ./orchestrator.sh

# timeout ensures ALL children are terminated, not just the parent

No more zombie processes lingering in your CI agents or development machines.

Configurable Graceful Shutdown

Applications need time to cleanup — flush buffers, save state, close connections. Our --kill-after flag gives you control:

# Send SIGTERM, wait 5 seconds, then SIGKILL if needed
timeout -s TERM -k 5s 30s -- ./api-server

# Immediate termination (no grace period)
timeout -k 0 10s -- ./batch-job

# Extended grace period for database operations
timeout -k 30s 5m -- ./migration-script

Live Output Streaming

See your command’s output in real-time, not after it completes:

timeout 2m -- cargo test --verbose
# Output streams to your terminal as tests run
# Perfect for debugging hanging tests

CI/CD Integration

Exit codes follow GNU timeout conventions for seamless integration:

  • 0 — Command succeeded
  • 124 — Timeout reached (distinct from command failure)
  • Other — Command’s actual exit code

This makes error handling in CI pipelines straightforward:

# GitHub Actions example
- name: Run tests with timeout
  run: timeout 10m -- cargo test
  continue-on-error: false

Real-World Use Cases

Preventing Hanging CI Jobs

# Wrap flaky network tests
timeout 5m -- cargo test --test integration_tests

# Prevent infinite loops in builds
timeout 30m -- npm run build:production

Development Workflow

# Kill runaway dev servers
timeout 1h -- npm run dev

# Test timeout handling in your own code
timeout 500ms -- ./test-graceful-shutdown.sh

Automation Scripts

# Ensure deployment scripts complete
timeout 15m -- ansible-playbook deploy.yml

# Health check with timeout
timeout 30s -- curl https://api.example.com/health

Installation

Get started in seconds:

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/nuewframe/timeout/main/install.sh | bash

Windows:

irm https://raw.githubusercontent.com/nuewframe/timeout/main/install.ps1 | iex

Via Cargo:

cargo install nuewframe-timeout

Or grab prebuilt binaries from our GitHub releases.

Technical Deep Dive

For the curious, here’s what makes this possible:

Async-First Architecture

Built on Tokio’s async runtime for efficient process management and signal handling without blocking threads.

Safe Signal Handling (Unix)

We use rustix for async-signal-safe process operations, avoiding common pitfalls in signal-heavy code.

Windows Job Objects

On Windows, we create a Job Object for each command, ensuring the OS terminates the entire process tree atomically — no manual recursion needed.

Structured Logging

Internal tracing with tracing and tracing-subscriber provides detailed diagnostics for debugging timeout behavior:

# Enable verbose logging
timeout --verbose 30s -- ./my-command

Roadmap

We’re just getting started. Upcoming features include:

  • JSON output for programmatic parsing
  • Config file support for default timeouts per project
  • Retry logic with exponential backoff
  • Resource limits (CPU, memory) integration
  • Enhanced observability with structured metrics

See our ROADMAP.md for the full vision.

Why Open Source?

timeout is part of the Nuewframe initiative — a collection of open-source tools for building reliable automation. We believe foundational tooling should be:

  • Cross-platform first — Equal treatment across OSes
  • Operator-focused — Human-readable errors, predictable behavior
  • Composable — Works alone or integrated with other tools
  • Secure by default — Regular audits, documented disclosure process

Every Nuewframe project follows these principles. Check out our vision document for more.

Get Involved

Found a bug? Have a feature request? Want to contribute?

We welcome contributions from developers of all skill levels. Whether it’s documentation improvements, bug fixes, or new features — every contribution makes a difference.

Final Thoughts

Timeouts seem simple until you need them to work reliably across platforms, handle process trees correctly, and integrate with complex CI/CD pipelines. We built timeout because we were tired of platform-specific scripts and unreliable workarounds.

If you’re running automated workflows, CI/CD pipelines, or just want better control over command execution in your development workflow, give timeout a try. It’s the timeout tool we wish existed when we started.

Install it today and never worry about hanging commands again.

Want to learn more about Nuewframe’s platform engineering patterns? Follow us on GitHub and subscribe to our RSS feed for future posts on edge computing, developer tooling, and modern delivery systems.