Home

StarkOS

Welcome to the StarkOS wiki! Stark is an JavaScript operating system and orchestration platform for deploying and managing software packages ("packs") across Node.js and browser runtimes.

What is StarkOS?

StarkOS enables you to:

• 🚀 Isomorphic Execution: Same pack runs identically on Node.js servers and browser tabs — UI is just another workload
• 📦 Pack Management: Immutable, versioned, bundled JavaScript artifacts with private/public visibility and system/user namespaces — Packs vs Pods
• 🖥️ Multi-Runtime: Deploy to Node.js (worker_threads) or browser (Web Workers) with runtime-agnostic core — Architecture
• 🔄 Reactive State: Vue 3 @vue/reactivity primitives throughout — desired-state reconciliation converges declared state with actual state automatically
• 🎯 Kubernetes-Like Scheduling: Filter → Score → Select pipeline with node selectors, taints/tolerations, resource fitting, priority & preemption — Scheduling & Policies
• 🔐 Security & RBAC: Supabase Auth with 4-role model (admin/user/node/viewer), ownership boundaries, trust zones, transport security (HTTPS/WSS), and RLS — Security & Capabilities
• 📡 Real-Time Event System: Structured events across 7 categories with persistent storage, WebSocket streaming, correlation IDs, and audit trails — Event Schema
• 🛡️ Services & Auto-Healing: Declarative service controller with replica-based and DaemonSet modes, crash-loop detection, auto-rollback, and follow-latest upgrades
• 🌐 Networking & Service Mesh: Inter-service communication via internal URLs, WebRTC data plane, network policies (deny-by-default), ingress/exposure, and HTTP interceptors — Networking & Services
• 🏗️ Namespace Isolation: Scoped resource boundaries with cross-namespace communication via fully-qualified internal URLs
• 🔧 Node Management: Labels, taints, resource declarations, cordon/uncordon, heartbeat-based liveness monitoring, and automatic pod rescheduling
• 💥 Built-in Chaos Testing: 10 pre-built fault-injection scenarios including node loss, network partitions, latency injection, and API flakiness — Chaos Testing
• 📊 Observability: Structured JSON logging, health endpoints, resource monitoring, and JSON output for scripting — Metrics & Observability
• 🖥️ Comprehensive CLI: Unified stark <resource> <action> syntax covering all orchestrator features with multiple output formats — CLI Reference

Key Concepts

Concept	Description
Pack	A bundled software package that can be deployed (private or public visibility)
Node	A runtime environment (Node.js or browser) that executes packs
Pod	A running instance of a pack on a specific node
Namespace	Isolated resource boundary with quotas
Service	A persistent resource that automatically manages pods

Technology Stack

• Language: TypeScript 5.x (strict mode)
• Reactivity: Vue 3 (@vue/reactivity)
• Database: Supabase (PostgreSQL)
• Testing: Vitest
• Build: Vite

Getting Started

1. Installation - Set up your development environment
2. Quick Start - Deploy your first pack in minutes
3. Mental Model - Understand how Stark thinks

Project Structure

stark-os/
├── packages/
│   ├── core/            # Isomorphic reactive core
│   ├── shared/          # Shared types, validation, utilities
│   ├── server/          # REST API & WebSocket server
│   ├── cli/             # Command-line interface
│   ├── node-runtime/    # Node.js runtime adapter
│   └── browser-runtime/ # Browser runtime adapter
├── supabase/
│   └── migrations/      # Database schema migrations
└── tests/
    ├── integration/     # Integration tests
    └── e2e/            # End-to-end tests

Need Help?

• Check the Glossary for terminology
• Browse the CLI Reference for command documentation
• Read the API Reference for REST and WebSocket APIs