winstack 0.1.0

Windows-native process orchestrator — no Docker, no WSL required

WinStack

Windows-native process orchestrator — no Docker, no WSL required.

Start, stop, and monitor your local development services from a single YAML file. Think docker-compose up, but for native Windows processes.

winstack bootstrap   # clone → install → start → health-check
winstack ui          # live split-pane dashboard
winstack down        # stop everything cleanly

---

Features

• Single YAML config — define all your services, dependencies, and health checks in one place
• Dependency ordering — services start and stop in the correct order based on depends_on
• Health checks — HTTP and TCP checks with configurable retries before marking a service ready
• Restart watchdog — on_failure and always restart policies with max retry limits
• Live TUI dashboard — split-pane terminal UI with real-time logs, CPU/memory, uptime
• Prerequisite checks — verify tools, ports, env vars, and folders before starting
• Git integration — clone or pull repos as part of bootstrap
• Group support — start subsets of services with --group

---

Installation

pip install winstack

Or install from source:

git clone https://github.com/sunnymurali/winstack.git
cd winstack
pip install -e .

Requirements: Python 3.9+, Windows 10/11

---

Quick Start

1. Create a config:

winstack init

Or copy example.winstack.yaml and edit it.

2. First-time setup (clone + install + start):

winstack bootstrap

3. Start services (after first run):

winstack up

4. Open the live dashboard:

winstack ui

---

Commands

Command	Description
winstack init	Interactive wizard — creates winstack.yaml
winstack check	Run prerequisite checks only
winstack clone	Clone or pull repos for services with repo: set
winstack bootstrap	Full first-run: clone → install → start
winstack up	Start services (skips clone & install)
winstack down	Stop all running services
winstack restart <name>	Stop and restart a single service
winstack status	Table view of all service states
winstack logs <name>	Tail a service log in real time
winstack ui	Interactive split-pane TUI dashboard

Common flags

Flag	Commands	Effect
--config / -c <path>	all	Use a different yaml file
--group / -g <name>	up, down, bootstrap, clone	Act on a named subset
--skip-install	bootstrap	Skip install step
--skip-checks	bootstrap	Skip prerequisite checks
--lines / -n <N>	logs	Lines to show before following (default 50)

---

Configuration Reference

version: "1"

# Global env vars — merged into every service
env:
  PYTHONPATH: "."

# Checks run before any service starts
prerequisites:
  - type: command        # verify a CLI tool exists
    name: python
    version_flag: "--version"
    expected_contains: "Python 3"
    fix: "Install Python 3.9+"

  - type: port_free      # verify a port is available
    port: 8001
    fix: "Stop whatever is on 8001"

  - type: env_var        # verify an env var is set
    name: OPENAI_API_KEY
    fix: "Set OPENAI_API_KEY before running"

  - type: folder         # verify a directory exists
    path: C:/data/myapp
    fix: "mkdir C:/data/myapp"

# Named subsets — start with: winstack up --group <name>
groups:
  minimal: [api]
  full:    [api, worker, frontend]

services:
  api:
    dir: ./api                        # relative to winstack.yaml
    repo: https://github.com/…        # clone/pull with winstack clone
    install: pip install -r requirements.txt
    start: python start_server.py
    env_file: .env                    # loaded from service dir
    env:
      LOG_LEVEL: INFO                 # per-service env (overrides global)
    enabled: true                     # set false to skip without deleting

    health:
      type: http                      # http | tcp | none
      url: http://localhost:8001/docs
      host: localhost                 # tcp only
      port: 8001                      # tcp only
      interval: 3                     # seconds between retries
      retries: 20                     # total attempts
      timeout: 5                      # per-check timeout

    restart:
      policy: on_failure              # no | on_failure | always
      max_retries: 3                  # 0 = unlimited

    depends_on:
      other_service:
        condition: process_healthy    # process_started | process_healthy

---

Live Dashboard (winstack ui)

┌ WinStack ──────────────────────────────── 10:42:31 ─┐
│  Service        Status       PID    CPU         Mem  │
│ ──────────────────────────────────────────────────── │
│ > sql_agent     ● RUNNING    1234   ███░░  2.3%  45MB│
│   vector_svc    ○ STOPPED    —      —             —  │
├────────────────────────────────────────────────────── │
│  LOGS  ──  sql_agent                                 │
│  10:42:28 Starting server...                         │
│  10:42:29 Loaded config                              │
│  10:42:30 ERROR: connection refused    ← bold red    │
└─────────────────────────────────────────────────────┘
│  q Quit  r Restart  s Start/Stop  c Clear Logs       │

Keyboard shortcuts:

Key	Action
↑ / ↓	Navigate service list
r	Restart selected service
s	Toggle start/stop
c	Clear log panel
g / G	Jump to top / bottom of logs
q	Quit

---

Restart Watchdog

When restart.policy is on_failure or always, a background thread monitors the process every 2 seconds and restarts it automatically (up to max_retries times). A manual winstack down cancels the watchdog so it doesn't fight the stop.

---

How bootstrap works

winstack bootstrap
  └─ prerequisite checks
  └─ for each service (dependency order):
       clone_or_pull   (if repo: is set)
       run install
       start process   → watchdog thread spawned
       wait for health check

---

License

MIT