Gula

A lightweight Linux process supervisor for robotics and edge AI development.

Gula runs a multi-process robotics or edge AI stack from one YAML file. It starts processes in directed acyclic graph order, waits for readiness probes, watches process-group resource usage, keeps bounded logs and CSV metrics, and applies configured recovery behavior when workloads fail policy checks.

What It Provides

• YAML process configuration with strict validation and JSON Schema support.
• DAG-based startup using setup-job completion and service readiness edges.
• Scriptable command readiness probes for health checks.
• Process-group shutdown, cleanup, signal forwarding, and CPU/memory metrics.
• Restart policy with capped exponential backoff.
• Memory threshold actions: warning, restart, stop, and kill.
• Per-process CPU affinity, niceness, and I/O priority.
• Command hooks for memory, CPU, runtime, policy, heartbeat, and exit events.
• Log files, size/time rotation, bounded in-memory log buffers, and CSV metrics.
• Local operator commands: status, start, stop, and restart.
• Terminal dashboard with process state, recent metrics, buffered logs, and process controls.
• Optional iceoryx2 node-liveness monitoring with --features iceoryx.

Status

Gula 0.1.0 is an early proof-of-concept release. The supported interface is the gula binary plus YAML configuration.

• Gula is not a replacement for systemd or ROS 2 launch. It sits between a system service manager and framework-specific launch files: systemd can still own the machine service, ROS 2 launch can still describe ROS-specific behavior, and Gula can supervise the cooperating processes in one application stack.
• The local control plane is a Unix-domain-socket JSON operator contract.
• Gula does not claim hard real-time behavior.

Gula is aimed at the development and field-debugging gap that often gets filled with hacky shell scripts, monit configs, tmux sessions, and unclear recovery behavior. It is especially useful when several robotics or edge AI processes need orchestration, readiness checks, observability, and repeatable recovery behavior in the field.

Quick Start

Requires Linux and Rust 1.90 or newer.

git clone https://github.com/unstablecursor/gula.git
cd gula
cargo build --release

./target/release/gula validate \
  --config config/gula.yaml \
  --sys-config config/gula_config.yaml

./target/release/gula run \
  --config config/gula.yaml \
  --sys-config config/gula_config.yaml

To generate a fresh starter config:

./target/release/gula init
./target/release/gula validate \
  --config config/gula.yaml \
  --sys-config config/gula_config.yaml
./target/release/gula run \
  --config config/gula.yaml \
  --sys-config config/gula_config.yaml

Try the TUI Demo

To see the terminal dashboard against a small local stack, follow the TUI demo walkthrough. It uses examples/tui_dashboard.yaml and opens gula tui against a demo supervisor in a second terminal.

CLI

gula run                                    # run config/gula.yaml
gula validate --config config/gula.yaml     # validate without starting
gula doctor                                 # inspect host support
gula init                                   # write starter config files
gula status                                 # inspect running supervisor
gula tui                                    # open terminal dashboard
gula stop worker                            # stop a process
gula restart worker                         # restart and wait for completion
gula start worker                           # start an operator-stopped process

Operator commands discover the local supervisor through $GULA_RUNTIME_DIR, $XDG_RUNTIME_DIR/gula, /run/gula, or /tmp/gula-$UID. Advanced clients can also set $GULA_CONTROL_SOCKET.

Examples

Starter config:

• config/gula.yaml - smallest generated-style process config.
• config/gula_config.yaml - default system config.

Feature examples:

• templates/minimal.yaml - minimal built-in template used by gula init --template minimal.
• templates/edge-robotics.yaml - built-in edge/robotics starter used by gula init --template edge.
• examples/basic_supervisor.yaml - DAG startup, memory warning, restart backoff.
• examples/command_hooks.yaml - hook triggers and hook artifacts.
• examples/tui_dashboard.yaml - local TUI demo.
• examples/web_app/ - API/worker/log topology.
• examples/edge_ai_applications/ - edge AI pipeline patterns.
• examples/ros2_suite/ - ROS-style shell mocks and a real ros2 launch template.
• examples/iceoryx2/ - feature-gated liveness monitoring examples.

Use examples/FEATURE_COVERAGE.md to find a sample for a specific config field.

Documentation

The Markdown user guide lives in docs/user_docs/src/. Key pages:

• Tutorial
• Installation
• Configuration
• CLI reference
• Control plane
• Terminal dashboard
• Security model
• Benchmarks
• FAQ

Benchmarks

Benchmark sources, workloads, and report-generation code live under benchmarks/. Generated reports are ignored by git because the numbers are host-specific.

cargo test --test benchmark_overhead test_overhead_regression -- --nocapture --test-threads=1
cargo test --test benchmark_reaction_time test_reaction_time_regression -- --nocapture --test-threads=1
cargo test --test benchmark_reaction_time test_worst_reaction_time_regression -- --nocapture --test-threads=1
cargo test --features iceoryx --test benchmark_reaction_time test_heartbeat_reaction_time_regression -- --nocapture --test-threads=1

For publication-style runs with more retained samples and Markdown/SVG/CSV reports, see Benchmarks.

Planned Work

Likely next areas include cgroups v2 support, crash-context capture, ROS 2-aware liveness checks, and more benchmark coverage on realistic robotics and edge workloads.

Development

cargo fmt --check
cargo test
cargo test --features iceoryx --test iceoryx_tests
cargo test --test benchmark_overhead -- --nocapture --test-threads=1
cargo test --test benchmark_reaction_time -- --nocapture --test-threads=1

The benchmark tests are regression checks for local development. Treat their numbers as host-specific measurements, not universal guarantees.

License

Apache License 2.0 - see LICENSE.