secubox-openwrt/package/secubox/secubox-app-streamlit-launcher/README.md

SecuBox Streamlit Launcher

On-demand Streamlit app launcher with idle shutdown and memory management.

Overview

The Streamlit Launcher optimizes resource usage on constrained devices by:

• Starting apps on-demand when first accessed (lazy loading)
• Stopping idle apps after configurable timeout (default: 30 min)
• Managing memory pressure by stopping low-priority apps when memory is low
• Priority system to keep critical apps running longer

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│   HAProxy   │────▶│  mitmproxy   │────▶│ Streamlit       │
│   (vhost)   │     │  (WAF+track) │     │ Launcher Daemon │
└─────────────┘     └──────────────┘     └────────┬────────┘
                           │                      │
                    Track access             Start/Stop
                           │                      │
                    ┌──────▼──────┐         ┌─────▼─────┐
                    │ /tmp/access │         │  slforge  │
                    │   (touch)   │         │  start/   │
                    └─────────────┘         │   stop    │
                                            └───────────┘

Installation

opkg install secubox-app-streamlit-launcher

CLI Reference

# Show status
streamlit-launcherctl status

# List all apps with details
streamlit-launcherctl list

# Manually start/stop an app
streamlit-launcherctl start <app>
streamlit-launcherctl stop <app>

# Set app priority (higher = keep running longer)
streamlit-launcherctl priority <app> <value>

# Set always-on (never auto-stop)
streamlit-launcherctl priority <app> 100 1

# Run idle check manually
streamlit-launcherctl check

# Run memory pressure check
streamlit-launcherctl check-memory

Configuration

Edit /etc/config/streamlit-launcher:

config global 'global'
    # Enable the launcher daemon
    option enabled '1'

    # Enable on-demand startup (vs always-running)
    option on_demand '1'

    # Minutes of inactivity before stopping an app
    option idle_timeout '30'

    # Seconds between idle checks
    option check_interval '60'

    # Minimum free memory (MB) before force-stopping apps
    option memory_threshold '100'

    # Max seconds to wait for app startup
    option startup_timeout '30'

# App priorities (higher = keep running longer)
config priority 'control'
    option app 'control'
    option value '100'
    option always_on '1'

config priority 'ytdownload'
    option app 'ytdownload'
    option value '30'

Priority System

Priority	Behavior
100 + always_on	Never auto-stopped
80-99	Stopped last during memory pressure
50 (default)	Normal priority
1-49	Stopped first during memory pressure

Integration with slforge

The launcher works alongside slforge (Streamlit Forge):

• slforge manages app configuration, creation, and basic start/stop
• streamlit-launcherctl adds on-demand and idle management

When on-demand is enabled:

1. User accesses https://app.example.com
2. HAProxy routes to mitmproxy
3. If app is down, mitmproxy can trigger startup via hook
4. Launcher starts app and waits for ready
5. Request is served
6. Access is tracked
7. After idle timeout, app is stopped

Access Tracking

The launcher tracks app access via touch files in /tmp/streamlit-access/:

# Track access (reset idle timer)
streamlit-launcherctl track <app>

# Or directly
touch /tmp/streamlit-access/<app>

This can be triggered by:

• mitmproxy request hook
• HAProxy health check script
• Cron job parsing access logs

Memory Management

When free memory drops below threshold:

1. Apps are sorted by priority (lowest first)
2. Low-priority apps are stopped one by one
3. Stops when memory recovers above threshold
4. Always-on apps are never stopped

Service Control

# Enable/start the daemon
/etc/init.d/streamlit-launcher enable
/etc/init.d/streamlit-launcher start

# Check daemon status
/etc/init.d/streamlit-launcher status

# View logs
logread -e streamlit-launcher

Files

Path	Description
/usr/sbin/streamlit-launcherctl	CLI tool
/etc/config/streamlit-launcher	UCI configuration
/etc/init.d/streamlit-launcher	Procd init script
/tmp/streamlit-access/	Access tracking files
/usr/share/streamlit-launcher/loading.html	Loading page template

Example: Optimize for Low Memory

# Set aggressive timeout (10 min)
uci set streamlit-launcher.global.idle_timeout='10'

# Lower memory threshold (trigger cleanup at 150MB free)
uci set streamlit-launcher.global.memory_threshold='150'

# Make dashboard always-on
streamlit-launcherctl priority dashboard 100 1

# Lower priority for heavy apps
streamlit-launcherctl priority jupyter 20
streamlit-launcherctl priority analytics 30

uci commit streamlit-launcher
/etc/init.d/streamlit-launcher restart