Documentation

Learn UAS inside out

Everything you need to understand, use, and extend the Universal App Store.

What is UAS?

UAS (Universal App Store) is a Windows-first, account-synced, stateful environment installer. It treats your entire development toolchain as a versioned, declarative profile that can be installed, synced, diffed, and rolled back.

Think of it as "dotfiles for Windows" meets "Homebrew + Chocolatey + Ninite" — with cloud sync, environment variables, and rollback capabilities.

Architecture

UAS is a layered system with strict dependency direction. UI layers depend on the engine, never the reverse. The engine is the single most important component.

System Architecture
┌─────────────┐   ┌─────────────┐
│   CLI Tool   │   │ Desktop App │
└──────┬──────┘   └──────┬──────┘
       │                  │
       └────────┬─────────┘
                │
        ┌───────▼────────┐
        │  Install Engine │  ← Core library
        └───────┬────────┘
                │
    ┌───────────┼───────────┐
    │           │           │
┌───▼──┐  ┌────▼───┐  ┌────▼────┐
│Catalog│  │ State  │  │ Backend │
│(YAML) │  │  (DB)  │  │  (API)  │
└───────┘  └────────┘  └─────────┘

Key Rules

  • • Engine MUST NOT depend on CLI or Desktop
  • • CLI MUST NOT depend on Desktop (or vice versa)
  • • Catalog MUST NOT depend on anything (pure data)
  • • Backend MUST NOT call the engine directly

Install Engine

The engine is the core library — it parses recipes, executes installers, tracks state, and supports rollback. It has zero UI logic and is consumed by both the CLI and Desktop.

engine-usage.ts
import { UasEngine } from "@uas/engine";

const engine = await UasEngine.create({
  dbPath: "./uas-state.db"
});

// Install with dry-run preview
await engine.install(recipe, { dryRun: true });

// Check installation state
const apps = engine.listInstalled();

// Rollback if needed
await engine.rollback(installId);

await engine.shutdown();

CLI Tool

The command-line interface wraps the engine with terminal-friendly output. Install globally via npm to use the uas command from anywhere.

CLI Commands
# Browse and install
uas list                    # List available software
uas search "node"           # Search the catalog
uas install node            # Install software
uas install node --dry-run  # Preview first

# Save and restore
uas save --name work-laptop # Save environment
uas restore work-laptop     # Restore on new machine

# Environment variables
uas env save                # Snapshot PATH + env vars
uas env restore default     # Restore env vars

# Cloud sync
uas login                   # Authenticate
uas sync                    # Push state to cloud
uas sync --pull             # Pull from cloud

# Profiles
uas profile diff dev-setup  # See what would change
uas profile apply dev-setup # Apply a profile

Backend API

Express REST API with JWT authentication. Provides user management, profile storage, machine tracking, and install history.

API Endpoints
POST   /api/auth/register       Create account
POST   /api/auth/login          Get JWT token
GET    /api/auth/me             Current user info

POST   /api/profiles            Create profile
GET    /api/profiles            List profiles
PUT    /api/profiles/:id        Update profile

POST   /api/machines            Register machine
GET    /api/machines            List machines

GET    /api/history             Install history
GET    /api/health              Health check

Catalog System

Install recipes are YAML files validated against a JSON Schema. Each recipe describes how to install one application — download URL, installer type, side effects, verification.

recipe.yaml
id: node
name: Node.js
version: "22.12.0"
description: JavaScript runtime
license: MIT

installer:
  type: msi
  url: https://nodejs.org/dist/v22.12.0/...
  sha256: abc123...
  silent_args: "/qn"

requirements:
  os: windows
  arch: x64
  admin: false

verification:
  command: "node --version"
  expected_output: "v22.12.0"

Profiles

Declarative environment profiles define a complete toolchain. Share them with teammates, version them in Git, or sync them to the cloud.

frontend-dev.yaml
name: frontend-dev
description: Frontend development environment
version: "1.0.0"
author: team-lead

apps:
  - id: node
    version: "22.12.0"
  - id: git
  - id: vscode
  - id: python
    version: "3.13.0"

settings:
  install_dir: "%LOCALAPPDATA%\Programs"
  parallel: false
  continue_on_error: true

FAQ

Is UAS a replacement for Chocolatey or Winget?

No. UAS orchestrates installations — it doesn't compile or host packages. It can work alongside Chocolatey, Winget, and Scoop. UAS manages environments; they manage packages.

Does UAS support Linux or macOS?

Not yet. UAS is Windows-first by design. Cross-platform support is a future goal, but we believe in doing one thing exceptionally well first.

Does UAS need admin privileges?

By default, no. UAS runs at user level. Admin elevation is requested per-operation only when needed (e.g., MSI to Program Files). You're always prompted first.

Is it safe?

UAS validates all recipes against a JSON Schema, verifies download checksums (SHA-256), runs with least privilege, and supports full dry-run previews. See our security model for details.

Can I contribute recipes?

Absolutely! The catalog is community-maintained. See catalog/CONTRIBUTING.md in the repo for guidelines on writing and submitting install recipes.

Ready to try it?

Get UAS up and running in under a minute.

DownloadRead the Docs