The Problem

Self-hosting a personal server means managing discovery, installation, networking, backups, and health monitoring for dozens of services—each with its own packaging format, dependencies, and update path. StartOS replaces that ad-hoc stack with a purpose-built Linux distribution that treats self-hosted services as first-class citizens: signed packages, isolated containers, and a reactive state database.

What This Does

StartOS is a full operating system for personal servers. The Rust backend (core/src/disk/main.rs, core/src/lib.rs) handles disk management and system services; the Node.js container runtime (container-runtime/src/Adapters/Systems/SystemForEmbassy/index.ts) manages LXC containers; the Angular frontend (web/projects/setup-wizard/) provides the UI; and the TypeScript SDK (sdk/) defines the packaging format and service APIs.

The repo is a portfolio of four self-contained projects—core, sdk, web, and container-runtime—not a single codebase. Each has its own build and test setup. The SDK is the largest surface: 510 files, 485 code files, with the osBindings module as the central hub (47 modules import PackageId, 45 import types).

How It Is Wired

Execution starts in container-runtime/src/Adapters/Systems/SystemForEmbassy/index.ts. The start function (line 452) reaches 178 functions and makes the first outbound network call via this.fetch. init (line 413) reaches 173 functions and traces to restoreBackup -> readFile for filesystem access. dependenciesCheck (line 1078) reaches 174 functions and also hits fs.readFile. The execute path in web/projects/setup-wizard/src/app/services/live-api.service.ts makes HTTP calls via rpcRequest -> httpRequest.

The SDK's osBindings module is the blast-radius center: PackageId (47 importers), types (45 importers, in a cycle), and osBindings/index (328 imports, instability 0.96). The import cycle between types.ts, Effects.ts, and util/index.ts means a change in any one requires coordinated edits across all three. The exver.ts file (84 functions, 989 lines, 290 branch points) is the version-comparison engine and the most complex single file.

How To Use It

git clone https://github.com/moses-y/start-os
cd start-os
# Follow CONTRIBUTING.md for environment setup
make build   # top-level Makefile drives the build

The Makefile and build/image-recipe/Dockerfile define the build pipeline. The README points to CONTRIBUTING.md for environment setup and docs.start9.com for installation. For a prebuilt path, the README describes buying a Start9 server or installing on compatible hardware. The repo has no documented CLI for local dev beyond the Makefile targets.

Real-World Use

A typical deployment: install StartOS on a Raspberry Pi or x86 box, then browse the marketplace to install Bitcoin Core, a Lightning node, and Nextcloud. Each service ships as an S9PK—a signed, merkle-archived package that supports partial downloads and cryptographic verification. The container runtime isolates each service in LXC, the SDK's Daemons.ts manages process lifecycle, and Patch-DB keeps the UI state synchronized with the backend.

Code Health & Issues

Static analysis found 300 issues (167 high, 129 medium, 4 low) across 5 kinds. The highest-concentration problems:

  • High - Import cycle members (32 occurrences) — sdk/base/lib/types.ts, Effects.ts, util/index.ts are mutually reachable. Fix: extract shared types or invert dependencies.
  • High - Hub modules (10) — osBindings/PackageId.ts (47 dependents) and types.ts (45 dependents) create high blast radius. Fix: keep stable, move volatile logic out.
  • High - Oversized files (7) — sdk/base/lib/actions/input/builder/value.ts at 1220 lines. Fix: split by responsibility.
  • High - Deep nesting (10) — core/src/backup/backup_bulk.rs and core/src/bins/startd.rs reach indentation depth 9. Fix: early returns and guard clauses.
  • Medium - High branching density — sdk/base/lib/exver/index.ts at 290 branch points over 989 lines.

SDLC observations: CI exists (GitHub Actions), tests are present (36 files), and no secrets were committed. The audit found one high-severity issue: third-party GitHub Actions are pinned to tags (docker/setup-qemu-action@v4), not commit SHAs—a tag can be moved, exposing CI tokens. Medium issues: no permissions: declaration in workflows, no Dependabot, mutable Docker base image (debian:${SUITE}), no dependency vulnerability scan, and persist-credentials not disabled on checkout.

The Bottom Line

StartOS is a serious, production-grade self-hosting platform with a well-structured SDK and a real container runtime. The codebase is large and the SDK has genuine maintainability debt—cycles, hubs, and oversized files will slow changes. It's best suited for developers building on StartOS or contributing to the platform itself, not for quick experimentation.