USO — Unified Script Orchestrator

Centralized, secure, and observable script management across Python, Shell, and JavaScript runtimes.

What is USO?

USO is a self-hosted platform for organizing, executing, and monitoring scripts across multiple runtimes from a single UI. It provides a tag-based script inventory, real-time execution logs, encrypted secrets, workflow chaining, scheduling, and a live dependency graph — all accessible through a modern SvelteKit interface backed by a FastAPI + SQLite server.

Key use cases

• Automate repetitive dev-ops or data-pipeline tasks without leaving a browser
• Chain scripts into multi-step workflows with file and env-variable passing
• Run and monitor scripts on demand or on a schedule
• Inspect execution history and metrics in the built-in dashboard

Features

Demo

See USO in action — 40-second walkthrough of all major features:

Watch the demo to see:

• Script library with smart search and filtering
• Auto-detection of script parameters and tags
• One-click execution with live log streaming
• Visual workflow builder for multi-step pipelines
• Interactive D3 dependency graph
• Real-time analytics dashboard
• Scheduled script triggers

Quick Start

Local (recommended for development)

git clone <repo-url> && cd uso
./start.sh
# Open http://localhost:8000

start.sh creates a virtualenv, installs Python deps, builds the SvelteKit frontend, and launches uvicorn — all in one step.

For frontend hot-reload during UI development:

./start.sh --dev
# Backend: http://localhost:8000
# Frontend dev server: http://localhost:5173

Docker

# Build and run (requires Docker 24+)
docker compose up --build

# Or run without compose
docker build -t uso .
docker run -p 8000:8000 -e USO_MASTER_KEY=<key> uso

App is available at http://localhost:8000.

Configuration

Generate a master key:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Demo Scripts

USO ships with 9 curated scripts covering file I/O, env chaining, network calls, metrics, and multi-language execution.

Demo Workflows

Three built-in workflows demonstrate the core chaining patterns.

1. Metrics-Pipeline-Demo

File output chaining — exports metrics to CSV, then summarises the file.

metrics_export  ──▶  process_metrics_csv

2. File-Output-Chain

File generation + env handoff — generates structured output files, then reads the generated path via env vars.

file_generator_demo  ──▶  env_chain_demo

3. API-Probe-Chain

Network verification + inventory — verifies the app is healthy, then queries and displays the script inventory.

health_check  ──▶  api_client_demo

Architecture

src/uso/
  api/app.py          # FastAPI application factory + lifespan
  api/routes/         # REST + WebSocket route handlers
  db/                 # SQLite CRUD layer (scripts, runs, tags, workflows, edges…)
  services/           # Business logic layer
  executor.py         # Subprocess execution with resource limits
  scheduler.py        # APScheduler integration
  secret_manager.py   # Fernet encrypt/decrypt
  seed.py             # Database seeding (scripts, tags, workflows)
  mcp_server.py       # FastMCP server for AI-agent use

frontend/src/
  routes/             # SvelteKit page routes (scripts, graph, metrics, schedules…)
  components/         # Shared UI components (OmniSearch, ScriptFlyout, Sidebar…)
  stores/             # Svelte 5 runes-based state stores

scripts/predefined/   # Demo script source files
data/                 # SQLite DB and script output artifacts (gitignored)

Request path: SvelteKit page → /api/* or /ws/* route → service layer → SQLite (WAL mode)

Development

make install    # Create venv + install Python deps
make test       # Run pytest (107 tests)
make lint       # Run ruff check + format check
./start.sh --dev  # Backend (port 8000) + frontend dev server (port 5173)

Tech stack

• Backend: Python 3.12, FastAPI, uvicorn, APScheduler 3.11, SQLite WAL
• Frontend: SvelteKit 5 (runes), Tailwind CSS v4, Lucide icons, D3
• Security: Fernet encryption, non-root Docker user, CORS-scoped origins

Testing

.venv/bin/python -m pytest tests/ -q --tb=short

Test modules cover: API routes, DB layer, executor, detector, file manager, scheduler, MCP server, secret manager, graph API, and service layer.

License

MIT