passthrough feature

- Bump SDK version to 0.4.0-beta.54
- Add `server.device-info` RPC endpoint and `s9pk select` CLI command
- Extract `HardwareRequirements::is_compatible()` method, reuse in registry filtering
- Add `AbortedError` class with `muteUnhandled` flag, replace generic abort errors
- Handle unhandled promise rejections in container-runtime with mute support
- Improve `InputSpec.filter()` with `keepByDefault` param and boolean filter values
- Accept readonly tuples in `CommandType` and `splitCommand`
- Remove `sync_host` calls from host API handlers (binding/address changes)
- Filter mDNS hostnames by secure gateway availability
- Derive mDNS enabled state from LAN IPs in web UI
- Add "Open UI" action to address table, disable mDNS toggle
- Hide debug details in service error component
- Update rpc-toolkit docs for no-params handlers

.claude/settings.json

@@ -0,0 +1 @@
+{}

.github/actions/setup-build/action.yml

@@ -0,0 +1,81 @@
+name: Setup Build Environment
+description: Common build environment setup steps
+
+inputs:
+  nodejs-version:
+    description: Node.js version
+    required: true
+  setup-python:
+    description: Set up Python
+    required: false
+    default: "false"
+  setup-docker:
+    description: Set up Docker QEMU and Buildx
+    required: false
+    default: "true"
+  setup-sccache:
+    description: Configure sccache for GitHub Actions
+    required: false
+    default: "true"
+  free-space:
+    description: Remove unnecessary packages to free disk space
+    required: false
+    default: "true"
+
+runs:
+  using: composite
+  steps:
+    - name: Free disk space
+      if: inputs.free-space == 'true'
+      shell: bash
+      run: |
+        sudo apt-get remove --purge -y azure-cli || true
+        sudo apt-get remove --purge -y firefox || true
+        sudo apt-get remove --purge -y ghc-* || true
+        sudo apt-get remove --purge -y google-cloud-sdk || true
+        sudo apt-get remove --purge -y google-chrome-stable || true
+        sudo apt-get remove --purge -y powershell || true
+        sudo apt-get remove --purge -y php* || true
+        sudo apt-get remove --purge -y ruby* || true
+        sudo apt-get remove --purge -y mono-* || true
+        sudo apt-get autoremove -y
+        sudo apt-get clean
+        sudo rm -rf /usr/lib/jvm
+        sudo rm -rf /usr/local/.ghcup
+        sudo rm -rf /usr/local/lib/android
+        sudo rm -rf /usr/share/dotnet
+        sudo rm -rf /usr/share/swift
+        sudo rm -rf "$AGENT_TOOLSDIRECTORY"
+
+    # BuildJet runners lack /opt/hostedtoolcache, which setup-python and setup-qemu expect
+    - name: Ensure hostedtoolcache exists
+      shell: bash
+      run: sudo mkdir -p /opt/hostedtoolcache && sudo chown $USER:$USER /opt/hostedtoolcache
+
+    - name: Set up Python
+      if: inputs.setup-python == 'true'
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.nodejs-version }}
+        cache: npm
+        cache-dependency-path: "**/package-lock.json"
+
+    - name: Set up Docker QEMU
+      if: inputs.setup-docker == 'true'
+      uses: docker/setup-qemu-action@v3
+
+    - name: Set up Docker Buildx
+      if: inputs.setup-docker == 'true'
+      uses: docker/setup-buildx-action@v3
+
+    - name: Configure sccache
+      if: inputs.setup-sccache == 'true'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          core.exportVariable('ACTIONS_RESULTS_URL', process.env.ACTIONS_RESULTS_URL || '');
+          core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

.github/workflows/start-cli.yaml

@@ -0,0 +1,88 @@
+name: start-cli
+
+on:
+  workflow_call:
+  workflow_dispatch:
+    inputs:
+      environment:
+        type: choice
+        description: Environment
+        options:
+          - NONE
+          - dev
+          - unstable
+          - dev-unstable
+      runner:
+        type: choice
+        description: Runner
+        options:
+          - standard
+          - fast
+      arch:
+        type: choice
+        description: Architecture
+        options:
+          - ALL
+          - x86_64
+          - x86_64-apple
+          - aarch64
+          - aarch64-apple
+          - riscv64
+  push:
+    branches:
+      - master
+      - next/*
+  pull_request:
+    branches:
+      - master
+      - next/*
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODEJS_VERSION: "24.11.0"
+  ENVIRONMENT: '${{ fromJson(format(''["{0}", ""]'', github.event.inputs.environment || ''dev''))[github.event.inputs.environment == ''NONE''] }}'
+
+jobs:
+  compile:
+    name: Build Debian Package
+    if: github.event.pull_request.draft != true
+    strategy:
+      fail-fast: true
+      matrix:
+        triple: >-
+          ${{
+            fromJson('{
+              "x86_64": ["x86_64-unknown-linux-musl"],
+              "x86_64-apple": ["x86_64-apple-darwin"],
+              "aarch64": ["aarch64-unknown-linux-musl"],
+              "x86_64-apple": ["aarch64-apple-darwin"],
+              "riscv64": ["riscv64gc-unknown-linux-musl"],
+              "ALL": ["x86_64-unknown-linux-musl", "x86_64-apple-darwin", "aarch64-unknown-linux-musl", "aarch64-apple-darwin", "riscv64gc-unknown-linux-musl"]
+            }')[github.event.inputs.platform || 'ALL']
+          }}
+    runs-on: ${{ fromJson('["ubuntu-latest", "buildjet-32vcpu-ubuntu-2204"]')[github.event.inputs.runner == 'fast'] }}
+    steps:
+      - name: Mount tmpfs
+        if: ${{ github.event.inputs.runner == 'fast' }}
+        run: sudo mount -t tmpfs tmpfs .
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: ./.github/actions/setup-build
+        with:
+          nodejs-version: ${{ env.NODEJS_VERSION }}
+
+      - name: Make
+        run: TARGET=${{ matrix.triple }} make cli
+        env:
+          PLATFORM: ${{ matrix.arch }}
+          SCCACHE_GHA_ENABLED: on
+          SCCACHE_GHA_VERSION: 0
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: start-cli_${{ matrix.triple }}
+          path: core/target/${{ matrix.triple }}/release/start-cli

.github/workflows/start-registry.yaml

@@ -0,0 +1,173 @@
+name: start-registry
+
+on:
+  workflow_call:
+  workflow_dispatch:
+    inputs:
+      environment:
+        type: choice
+        description: Environment
+        options:
+          - NONE
+          - dev
+          - unstable
+          - dev-unstable
+      runner:
+        type: choice
+        description: Runner
+        options:
+          - standard
+          - fast
+      arch:
+        type: choice
+        description: Architecture
+        options:
+          - ALL
+          - x86_64
+          - aarch64
+          - riscv64
+  push:
+    branches:
+      - master
+      - next/*
+  pull_request:
+    branches:
+      - master
+      - next/*
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODEJS_VERSION: "24.11.0"
+  ENVIRONMENT: '${{ fromJson(format(''["{0}", ""]'', github.event.inputs.environment || ''dev''))[github.event.inputs.environment == ''NONE''] }}'
+
+jobs:
+  compile:
+    name: Build Debian Package
+    if: github.event.pull_request.draft != true
+    strategy:
+      fail-fast: true
+      matrix:
+        arch: >-
+          ${{
+            fromJson('{
+              "x86_64": ["x86_64"],
+              "aarch64": ["aarch64"],
+              "riscv64": ["riscv64"],
+              "ALL": ["x86_64", "aarch64", "riscv64"]
+            }')[github.event.inputs.platform || 'ALL']
+          }}
+    runs-on: ${{ fromJson('["ubuntu-latest", "buildjet-32vcpu-ubuntu-2204"]')[github.event.inputs.runner == 'fast'] }}
+    steps:
+      - name: Mount tmpfs
+        if: ${{ github.event.inputs.runner == 'fast' }}
+        run: sudo mount -t tmpfs tmpfs .
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: ./.github/actions/setup-build
+        with:
+          nodejs-version: ${{ env.NODEJS_VERSION }}
+
+      - name: Make
+        run: make registry-deb
+        env:
+          PLATFORM: ${{ matrix.arch }}
+          SCCACHE_GHA_ENABLED: on
+          SCCACHE_GHA_VERSION: 0
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: start-registry_${{ matrix.arch }}.deb
+          path: results/start-registry-*_${{ matrix.arch }}.deb
+
+  create-image:
+    name: Create Docker Image
+    needs: [compile]
+    permissions:
+      contents: read
+      packages: write
+    runs-on: ${{ fromJson('["ubuntu-latest", "buildjet-32vcpu-ubuntu-2204"]')[github.event.inputs.runner == 'fast'] }}
+    steps:
+      - name: Cleaning up unnecessary files
+        run: |
+          sudo apt-get remove --purge -y google-chrome-stable firefox mono-devel
+          sudo apt-get autoremove -y
+          sudo apt-get clean
+
+      - run: |
+          sudo mount -t tmpfs tmpfs .
+        if: ${{ github.event.inputs.runner == 'fast' }}
+
+      - name: Set up docker QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: "Login to GitHub Container Registry"
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{github.actor}}
+          password: ${{secrets.GITHUB_TOKEN}}
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/Start9Labs/startos-registry
+          tags: |
+            type=raw,value=${{ github.ref_name }}
+
+      - name: Download debian package
+        uses: actions/download-artifact@v4
+        with:
+          pattern: start-registry_*.deb
+
+      - name: Map matrix.arch to docker platform
+        run: |
+          platforms=""
+          for deb in *.deb; do
+            filename=$(basename "$deb" .deb)
+            arch="${filename#*_}"
+            case "$arch" in
+              x86_64)
+                platform="linux/amd64"
+                ;;
+              aarch64)
+                platform="linux/arm64"
+                ;;
+              riscv64)
+                platform="linux/riscv64"
+                ;;
+              *)
+                echo "Unknown architecture: $arch" >&2
+                exit 1
+                ;;
+            esac
+            if [ -z "$platforms" ]; then
+              platforms="$platform"
+            else
+              platforms="$platforms,$platform"
+            fi
+          done
+          echo "DOCKER_PLATFORM=$platforms" >> "$GITHUB_ENV"
+
+      - run: |
+          cat | docker buildx build --platform "$DOCKER_PLATFORM" --push -t ${{ steps.meta.outputs.tags }} -f - . << 'EOF'
+          FROM debian:trixie
+
+          ADD *.deb .
+
+          RUN apt-get install -y ./*_$(uname -m).deb && rm *.deb
+
+          VOLUME /var/lib/startos
+
+          ENV RUST_LOG=startos=debug
+
+          ENTRYPOINT ["start-registryd"]
+
+          EOF

.github/workflows/start-tunnel.yaml

@@ -0,0 +1,84 @@
+name: start-tunnel
+
+on:
+  workflow_call:
+  workflow_dispatch:
+    inputs:
+      environment:
+        type: choice
+        description: Environment
+        options:
+          - NONE
+          - dev
+          - unstable
+          - dev-unstable
+      runner:
+        type: choice
+        description: Runner
+        options:
+          - standard
+          - fast
+      arch:
+        type: choice
+        description: Architecture
+        options:
+          - ALL
+          - x86_64
+          - aarch64
+          - riscv64
+  push:
+    branches:
+      - master
+      - next/*
+  pull_request:
+    branches:
+      - master
+      - next/*
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODEJS_VERSION: "24.11.0"
+  ENVIRONMENT: '${{ fromJson(format(''["{0}", ""]'', github.event.inputs.environment || ''dev''))[github.event.inputs.environment == ''NONE''] }}'
+
+jobs:
+  compile:
+    name: Build Debian Package
+    if: github.event.pull_request.draft != true
+    strategy:
+      fail-fast: true
+      matrix:
+        arch: >-
+          ${{
+            fromJson('{
+              "x86_64": ["x86_64"],
+              "aarch64": ["aarch64"],
+              "riscv64": ["riscv64"],
+              "ALL": ["x86_64", "aarch64", "riscv64"]
+            }')[github.event.inputs.platform || 'ALL']
+          }}
+    runs-on: ${{ fromJson('["ubuntu-latest", "buildjet-32vcpu-ubuntu-2204"]')[github.event.inputs.runner == 'fast'] }}
+    steps:
+      - name: Mount tmpfs
+        if: ${{ github.event.inputs.runner == 'fast' }}
+        run: sudo mount -t tmpfs tmpfs .
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: ./.github/actions/setup-build
+        with:
+          nodejs-version: ${{ env.NODEJS_VERSION }}
+
+      - name: Make
+        run: make tunnel-deb
+        env:
+          PLATFORM: ${{ matrix.arch }}
+          SCCACHE_GHA_ENABLED: on
+          SCCACHE_GHA_VERSION: 0
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: start-tunnel_${{ matrix.arch }}.deb
+          path: results/start-tunnel-*_${{ matrix.arch }}.deb

.github/workflows/startos-iso.yaml

@@ -12,9 +12,6 @@ on:
           - dev
           - unstable
           - dev-unstable
-          - docker
-          - dev-docker
-          - dev-unstable-docker
       runner:
         type: choice
         description: Runner
@@ -28,9 +25,13 @@ on:
           - ALL
           - x86_64
           - x86_64-nonfree
+          - x86_64-nvidia
           - aarch64
           - aarch64-nonfree
-          - raspberrypi
+          - aarch64-nvidia
+          # - raspberrypi
+          - riscv64
+          - riscv64-nonfree
       deploy:
         type: choice
         description: Deploy
@@ -47,13 +48,18 @@ on:
       - master
       - next/*
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 env:
-  NODEJS_VERSION: "18.15.0"
+  NODEJS_VERSION: "24.11.0"
   ENVIRONMENT: '${{ fromJson(format(''["{0}", ""]'', github.event.inputs.environment || ''dev''))[github.event.inputs.environment == ''NONE''] }}'
 
 jobs:
   compile:
     name: Compile Base Binaries
+    if: github.event.pull_request.draft != true
     strategy:
       fail-fast: true
       matrix:
@@ -62,36 +68,53 @@ jobs:
             fromJson('{
               "x86_64": ["x86_64"],
               "x86_64-nonfree": ["x86_64"],
+              "x86_64-nvidia": ["x86_64"],
               "aarch64": ["aarch64"],
               "aarch64-nonfree": ["aarch64"],
+              "aarch64-nvidia": ["aarch64"],
               "raspberrypi": ["aarch64"],
-              "ALL": ["x86_64", "aarch64"]
+              "riscv64": ["riscv64"],
+              "riscv64-nonfree": ["riscv64"],
+              "ALL": ["x86_64", "aarch64", "riscv64"]
             }')[github.event.inputs.platform || 'ALL']
           }}
-    runs-on: ${{ fromJson('["ubuntu-22.04", "buildjet-32vcpu-ubuntu-2204"]')[github.event.inputs.runner == 'fast'] }}
+    runs-on: >-
+      ${{
+        fromJson(
+          format(
+            '["{0}", "{1}"]',
+            fromJson('{
+              "x86_64": "ubuntu-latest",
+              "aarch64": "ubuntu-24.04-arm",
+              "riscv64": "ubuntu-latest"
+            }')[matrix.arch],
+            fromJson('{
+              "x86_64": "buildjet-32vcpu-ubuntu-2204",
+              "aarch64": "buildjet-32vcpu-ubuntu-2204-arm",
+              "riscv64": "buildjet-32vcpu-ubuntu-2204"
+            }')[matrix.arch]
+          )
+        )[github.event.inputs.runner == 'fast']
+      }}
     steps:
-      - run: |
-          sudo mount -t tmpfs tmpfs .
+      - name: Mount tmpfs
         if: ${{ github.event.inputs.runner == 'fast' }}
-
-      - uses: actions/checkout@v3
+        run: sudo mount -t tmpfs tmpfs .
+      - uses: actions/checkout@v4
         with:
           submodules: recursive
-
-      - uses: actions/setup-node@v3
+      - uses: ./.github/actions/setup-build
         with:
-          node-version: ${{ env.NODEJS_VERSION }}
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v2
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+          nodejs-version: ${{ env.NODEJS_VERSION }}
+          setup-python: "true"
 
       - name: Make
         run: make ARCH=${{ matrix.arch }} compiled-${{ matrix.arch }}.tar
+        env:
+          SCCACHE_GHA_ENABLED: on
+          SCCACHE_GHA_VERSION: 0
 
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: compiled-${{ matrix.arch }}.tar
           path: compiled-${{ matrix.arch }}.tar
@@ -101,13 +124,14 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        # TODO: re-add "raspberrypi" to the platform list below
         platform: >-
           ${{
             fromJson(
               format(
                 '[
                   ["{0}"],
-                  ["x86_64", "x86_64-nonfree", "aarch64", "aarch64-nonfree", "raspberrypi"]
+                  ["x86_64", "x86_64-nonfree", "x86_64-nvidia", "aarch64", "aarch64-nonfree", "aarch64-nvidia", "riscv64", "riscv64-nonfree"]
                 ]',
                 github.event.inputs.platform || 'ALL'
               )
@@ -117,13 +141,28 @@ jobs:
       ${{
         fromJson(
           format(
-            '["ubuntu-22.04", "{0}"]',
+            '["{0}", "{1}"]',
+            fromJson('{
+              "x86_64": "ubuntu-latest",
+              "x86_64-nonfree": "ubuntu-latest",
+              "x86_64-nvidia": "ubuntu-latest",
+              "aarch64": "ubuntu-24.04-arm",
+              "aarch64-nonfree": "ubuntu-24.04-arm",
+              "aarch64-nvidia": "ubuntu-24.04-arm",
+              "raspberrypi": "ubuntu-24.04-arm",
+              "riscv64": "ubuntu-24.04-arm",
+              "riscv64-nonfree": "ubuntu-24.04-arm",
+            }')[matrix.platform],
             fromJson('{
               "x86_64": "buildjet-8vcpu-ubuntu-2204",
               "x86_64-nonfree": "buildjet-8vcpu-ubuntu-2204",
+              "x86_64-nvidia": "buildjet-8vcpu-ubuntu-2204",
               "aarch64": "buildjet-8vcpu-ubuntu-2204-arm",
               "aarch64-nonfree": "buildjet-8vcpu-ubuntu-2204-arm",
+              "aarch64-nvidia": "buildjet-8vcpu-ubuntu-2204-arm",
               "raspberrypi": "buildjet-8vcpu-ubuntu-2204-arm",
+              "riscv64": "buildjet-8vcpu-ubuntu-2204",
+              "riscv64-nonfree": "buildjet-8vcpu-ubuntu-2204",
             }')[matrix.platform]
           )
         )[github.event.inputs.runner == 'fast']
@@ -134,35 +173,50 @@ jobs:
           fromJson('{
             "x86_64": "x86_64",
             "x86_64-nonfree": "x86_64",
+            "x86_64-nvidia": "x86_64",
             "aarch64": "aarch64",
             "aarch64-nonfree": "aarch64",
+            "aarch64-nvidia": "aarch64",
             "raspberrypi": "aarch64",
+            "riscv64": "riscv64",
+            "riscv64-nonfree": "riscv64",
           }')[matrix.platform]
         }}
     steps:
-      - uses: actions/checkout@v3
+      - name: Free space
+        run: |
+          sudo apt-get remove --purge -y azure-cli || true
+          sudo apt-get remove --purge -y firefox || true
+          sudo apt-get remove --purge -y ghc-* || true
+          sudo apt-get remove --purge -y google-cloud-sdk || true
+          sudo apt-get remove --purge -y google-chrome-stable || true
+          sudo apt-get remove --purge -y powershell || true
+          sudo apt-get remove --purge -y php* || true
+          sudo apt-get remove --purge -y ruby* || true
+          sudo apt-get remove --purge -y mono-* || true
+          sudo apt-get autoremove -y
+          sudo apt-get clean
+          sudo rm -rf /usr/lib/jvm               # All JDKs
+          sudo rm -rf /usr/local/.ghcup          # Haskell toolchain
+          sudo rm -rf /usr/local/lib/android     # Android SDK/NDK, emulator
+          sudo rm -rf /usr/share/dotnet          # .NET SDKs
+          sudo rm -rf /usr/share/swift           # Swift toolchain (if present)
+          sudo rm -rf "$AGENT_TOOLSDIRECTORY"    # Pre-cached tool cache (Go, Node, etc.)
+        if: ${{ github.event.inputs.runner != 'fast' }}
+
+      # BuildJet runners lack /opt/hostedtoolcache, which setup-qemu expects
+      - name: Ensure hostedtoolcache exists
+        run: sudo mkdir -p /opt/hostedtoolcache && sudo chown $USER:$USER /opt/hostedtoolcache
+
+      - name: Set up docker QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - uses: actions/checkout@v4
         with:
           submodules: recursive
 
-      - name: Install dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y qemu-user-static
-          wget https://deb.debian.org/debian/pool/main/d/debspawn/debspawn_0.6.2-1_all.deb
-          sha256sum ./debspawn_0.6.2-1_all.deb | grep 37ef27458cb1e35e8bce4d4f639b06b4b3866fc0b9191ec6b9bd157afd06a817
-          sudo apt-get install -y ./debspawn_0.6.2-1_all.deb
-
-      - name: Configure debspawn
-        run: |
-          sudo mkdir -p /etc/debspawn/
-          echo "AllowUnsafePermissions=true" | sudo tee /etc/debspawn/global.toml
-          sudo mkdir -p /var/tmp/debspawn
-
-      - run: sudo mount -t tmpfs tmpfs /var/tmp/debspawn
-        if: ${{ github.event.inputs.runner == 'fast' && (matrix.platform == 'x86_64' || matrix.platform == 'x86_64-nonfree') }}
-
       - name: Download compiled artifacts
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: compiled-${{ env.ARCH }}.tar
 
@@ -171,9 +225,26 @@ jobs:
 
       - name: Prevent rebuild of compiled artifacts
         run: |
+          mkdir -p web/node_modules
           mkdir -p web/dist/raw
+          mkdir -p core/bindings
+          mkdir -p sdk/base/lib/osBindings
+          mkdir -p container-runtime/node_modules
+          mkdir -p container-runtime/dist
+          mkdir -p container-runtime/dist/node_modules
+          mkdir -p sdk/dist
+          mkdir -p sdk/baseDist
+          mkdir -p patch-db/client/node_modules
+          mkdir -p patch-db/client/dist
+          mkdir -p web/.angular
+          mkdir -p web/dist/raw/ui
+          mkdir -p web/dist/raw/setup-wizard
+          mkdir -p web/dist/static/ui
+          mkdir -p web/dist/static/setup-wizard
           PLATFORM=${{ matrix.platform }} make -t compiled-${{ env.ARCH }}.tar
 
+      - run: git status
+
       - name: Run iso build
         run: PLATFORM=${{ matrix.platform }} make iso
         if: ${{ matrix.platform != 'raspberrypi' }}
@@ -182,56 +253,19 @@ jobs:
         run: PLATFORM=${{ matrix.platform }} make img
         if: ${{ matrix.platform == 'raspberrypi' }}
 
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.platform }}.squashfs
           path: results/*.squashfs
 
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.platform }}.iso
           path: results/*.iso
         if: ${{ matrix.platform != 'raspberrypi' }}
 
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.platform }}.img
           path: results/*.img
         if: ${{ matrix.platform == 'raspberrypi' }}
-
-      - name: Upload OTA to registry
-        run: >-
-          PLATFORM=${{ matrix.platform }} make upload-ota TARGET="${{
-            fromJson('{
-              "alpha": "alpha-registry-x.start9.com",
-              "beta": "beta-registry.start9.com",
-            }')[github.event.inputs.deploy]
-          }}" KEY="${{
-            fromJson(
-              format('{{
-                "alpha": "{0}",
-                "beta": "{1}",
-              }}', secrets.ALPHA_INDEX_KEY, secrets.BETA_INDEX_KEY)
-            )[github.event.inputs.deploy]
-          }}"
-        if: ${{ github.event.inputs.deploy != '' && github.event.inputs.deploy != 'NONE' }}
-
-  index:
-    if: ${{ github.event.inputs.deploy != '' && github.event.inputs.deploy != 'NONE' }}
-    needs: [image]
-    runs-on: ubuntu-22.04
-    steps:
-      - run: >-
-          curl "https://${{
-            fromJson('{
-              "alpha": "alpha-registry-x.start9.com",
-              "beta": "beta-registry.start9.com",
-            }')[github.event.inputs.deploy]
-          }}:8443/resync.cgi?key=${{
-            fromJson(
-              format('{{
-                "alpha": "{0}",
-                "beta": "{1}",
-              }}', secrets.ALPHA_INDEX_KEY, secrets.BETA_INDEX_KEY)
-            )[github.event.inputs.deploy]
-          }}"

.github/workflows/test.yaml

@@ -10,22 +10,29 @@ on:
       - master
       - next/*
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 env:
-  NODEJS_VERSION: "18.15.0"
+  NODEJS_VERSION: "24.11.0"
   ENVIRONMENT: dev-unstable
 
 jobs:
   test:
     name: Run Automated Tests
-    runs-on: ubuntu-22.04
+    if: github.event.pull_request.draft != true
+    runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: recursive
-
-      - uses: actions/setup-node@v3
+      - uses: ./.github/actions/setup-build
         with:
-          node-version: ${{ env.NODEJS_VERSION }}
+          nodejs-version: ${{ env.NODEJS_VERSION }}
+          free-space: "false"
+          setup-docker: "false"
+          setup-sccache: "false"
 
       - name: Build And Run Tests
         run: make test

.gitignore

@@ -1,31 +1,24 @@
 .DS_Store
 .idea
-system-images/binfmt/binfmt.tar
-system-images/compat/compat.tar
-system-images/util/util.tar
-/*.img
-/*.img.gz
-/*.img.xz
-/*-raspios-bullseye-arm64-lite.img
-/*-raspios-bullseye-arm64-lite.zip
+*.img
+*.img.gz
+*.img.xz
+*.zip
 /product_key.txt
 /*_product_key.txt
 .vscode/settings.json
 deploy_web.sh
-deploy_web.sh
 secrets.db
 .vscode/
-/cargo-deps/**/*
-/PLATFORM.txt
-/ENVIRONMENT.txt
-/GIT_HASH.txt
-/VERSION.txt
-/eos-*.tar.gz
-/*.deb
+/build/env/*.txt
+*.deb
 /target
-/*.squashfs
+*.squashfs
 /results
 /dpkg-workdir
 /compiled.tar
 /compiled-*.tar
-/firmware
+/build/lib/firmware
+tmp
+web/.i18n-checked
+docs/USER.md

ARCHITECTURE.md

@@ -0,0 +1,101 @@
+# Architecture
+
+StartOS is an open-source Linux distribution for running personal servers. It manages discovery, installation, network configuration, backups, and health monitoring of self-hosted services.
+
+## Tech Stack
+
+- Backend: Rust (async/Tokio, Axum web framework)
+- Frontend: Angular 20 + TypeScript + TaigaUI
+- Container runtime: Node.js/TypeScript with LXC
+- Database/State: Patch-DB (git submodule) - storage layer with reactive frontend sync
+- API: JSON-RPC via rpc-toolkit (see `core/rpc-toolkit.md`)
+- Auth: Password + session cookie, public/private key signatures, local authcookie (see `core/src/middleware/auth/`)
+
+## Project Structure
+
+```bash
+/
+├── assets/              # Screenshots for README
+├── build/               # Auxiliary files and scripts for deployed images
+├── container-runtime/   # Node.js program managing package containers
+├── core/                # Rust backend: API, daemon (startd), CLI (start-cli)
+├── debian/              # Debian package maintainer scripts
+├── image-recipe/        # Scripts for building StartOS images
+├── patch-db/            # (submodule) Diff-based data store for frontend sync
+├── sdk/                 # TypeScript SDK for building StartOS packages
+└── web/                 # Web UIs (Angular)
+```
+
+## Components
+
+- **`core/`** — Rust backend daemon. Produces a single binary `startbox` that is symlinked as `startd` (main daemon), `start-cli` (CLI), `start-container` (runs inside LXC containers), `registrybox` (package registry), and `tunnelbox` (VPN/tunnel). Handles all backend logic: RPC API, service lifecycle, networking (DNS, ACME, WiFi, Tor, WireGuard), backups, and database state management. See [core/ARCHITECTURE.md](core/ARCHITECTURE.md).
+
+- **`web/`** — Angular 20 + TypeScript workspace using Taiga UI. Contains three applications (admin UI, setup wizard, VPN management) and two shared libraries (common components/services, marketplace). Communicates with the backend exclusively via JSON-RPC. See [web/ARCHITECTURE.md](web/ARCHITECTURE.md).
+
+- **`container-runtime/`** — Node.js runtime that runs inside each service's LXC container. Loads the service's JavaScript from its S9PK package and manages subcontainers. Communicates with the host daemon via JSON-RPC over Unix socket. See [container-runtime/CLAUDE.md](container-runtime/CLAUDE.md).
+
+- **`sdk/`** — TypeScript SDK for packaging services for StartOS (`@start9labs/start-sdk`). Split into `base/` (core types, ABI definitions, effects interface, consumed by web as `@start9labs/start-sdk-base`) and `package/` (full SDK for service developers, consumed by container-runtime as `@start9labs/start-sdk`).
+
+- **`patch-db/`** — Git submodule providing diff-based state synchronization. Uses CBOR encoding. Backend mutations produce diffs that are pushed to the frontend via WebSocket, enabling reactive UI updates without polling. See [patch-db repo](https://github.com/Start9Labs/patch-db).
+
+## Build Pipeline
+
+Components have a strict dependency chain. Changes flow in one direction:
+
+```
+Rust (core/)
+  → cargo test exports ts-rs types to core/bindings/
+    → rsync copies to sdk/base/lib/osBindings/
+      → SDK build produces baseDist/ and dist/
+        → web/ consumes baseDist/ (via @start9labs/start-sdk-base)
+        → container-runtime/ consumes dist/ (via @start9labs/start-sdk)
+```
+
+Key make targets along this chain:
+
+| Step | Command | What it does |
+|---|---|---|
+| 1 | `cargo check -p start-os` | Verify Rust compiles |
+| 2 | `make ts-bindings` | Export ts-rs types → rsync to SDK |
+| 3 | `cd sdk && make baseDist dist` | Build SDK packages |
+| 4 | `cd web && npm run check` | Type-check Angular projects |
+| 5 | `cd container-runtime && npm run check` | Type-check runtime |
+
+**Important**: Editing `sdk/base/lib/osBindings/*.ts` alone is NOT sufficient — you must rebuild the SDK bundle (step 3) before web/container-runtime can see the changes.
+
+## Cross-Layer Verification
+
+When making changes across multiple layers (Rust, SDK, web, container-runtime), verify in this order:
+
+1. **Rust**: `cargo check -p start-os` — verifies core compiles
+2. **TS bindings**: `make ts-bindings` — regenerates TypeScript types from Rust `#[ts(export)]` structs
+   - Runs `./core/build/build-ts.sh` to export ts-rs types to `core/bindings/`
+   - Syncs `core/bindings/` → `sdk/base/lib/osBindings/` via rsync
+   - If you manually edit files in `sdk/base/lib/osBindings/`, you must still rebuild the SDK (step 3)
+3. **SDK bundle**: `cd sdk && make baseDist dist` — compiles SDK source into packages
+   - `baseDist/` is consumed by `/web` (via `@start9labs/start-sdk-base`)
+   - `dist/` is consumed by `/container-runtime` (via `@start9labs/start-sdk`)
+   - Web and container-runtime reference the **built** SDK, not source files
+4. **Web type check**: `cd web && npm run check` — type-checks all Angular projects
+5. **Container runtime type check**: `cd container-runtime && npm run check` — type-checks the runtime
+
+## Data Flow: Backend to Frontend
+
+StartOS uses Patch-DB for reactive state synchronization:
+
+1. The backend mutates state via `db.mutate()`, producing CBOR diffs
+2. Diffs are pushed to the frontend over a persistent WebSocket connection
+3. The frontend applies diffs to its local state copy and notifies observers
+4. Components watch specific database paths via `PatchDB.watch$()`, receiving updates reactively
+
+This means the UI is always eventually consistent with the backend — after any mutating API call, the frontend waits for the corresponding PatchDB diff before resolving, so the UI reflects the result immediately.
+
+## Further Reading
+
+- [core/ARCHITECTURE.md](core/ARCHITECTURE.md) — Rust backend architecture
+- [web/ARCHITECTURE.md](web/ARCHITECTURE.md) — Angular frontend architecture
+- [container-runtime/CLAUDE.md](container-runtime/CLAUDE.md) — Container runtime details
+- [core/rpc-toolkit.md](core/rpc-toolkit.md) — JSON-RPC handler patterns
+- [core/s9pk-structure.md](core/s9pk-structure.md) — S9PK package format
+- [docs/exver.md](docs/exver.md) — Extended versioning format
+- [docs/VERSION_BUMP.md](docs/VERSION_BUMP.md) — Version bumping guide

CLAUDE.md

@@ -0,0 +1,59 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full system architecture, component map, build pipeline, and cross-layer verification order.
+
+Each major component has its own `CLAUDE.md` with detailed guidance: `core/`, `web/`, `container-runtime/`, `sdk/`.
+
+## Build & Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
+- Environment setup and requirements
+- Build commands and make targets
+- Testing and formatting commands
+- Environment variables
+
+**Quick reference:**
+
+```bash
+. ./devmode.sh                            # Enable dev mode
+make update-startbox REMOTE=start9@<ip>   # Fastest iteration (binary + UI)
+make test-core                            # Run Rust tests
+```
+
+## Operating Rules
+
+- Always verify cross-layer changes using the order described in [ARCHITECTURE.md](ARCHITECTURE.md#cross-layer-verification)
+- Check component-level CLAUDE.md files for component-specific conventions. ALWAYS read it before operating on that component.
+- Follow existing patterns before inventing new ones
+- Always use `make` recipes when they exist for testing builds rather than manually invoking build commands
+
+## Supplementary Documentation
+
+The `docs/` directory contains cross-cutting documentation for AI assistants:
+
+- `TODO.md` - Pending tasks for AI agents (check this first, remove items when completed)
+- `USER.md` - Current user identifier (gitignored, see below)
+- `exver.md` - Extended versioning format (used across core, sdk, and web)
+- `VERSION_BUMP.md` - Guide for bumping the StartOS version across the codebase
+
+Component-specific docs live alongside their code (e.g., `core/rpc-toolkit.md`, `core/i18n-patterns.md`).
+
+### Session Startup
+
+On startup:
+
+1. **Check for `docs/USER.md`** - If it doesn't exist, prompt the user for their name/identifier and create it. This file is gitignored since it varies per developer.
+
+2. **Check `docs/TODO.md` for relevant tasks** - Show TODOs that either:
+
+   - Have no `@username` tag (relevant to everyone)
+   - Are tagged with the current user's identifier
+
+   Skip TODOs tagged with a different user.
+
+3. **Ask "What would you like to do today?"** - Offer options for each relevant TODO item, plus "Something else" for other requests.

CONTRIBUTING.md

@@ -1,119 +1,240 @@
 # Contributing to StartOS
 
-This guide is for contributing to the StartOS. If you are interested in packaging a service for StartOS, visit the [service packaging guide](https://docs.start9.com/latest/developer-docs/). If you are interested in promoting, providing technical support, creating tutorials, or helping in other ways, please visit the [Start9 website](https://start9.com/contribute).
-
+This guide is for contributing to the StartOS. If you are interested in packaging a service for StartOS, visit the [service packaging guide](https://github.com/Start9Labs/ai-service-packaging). If you are interested in promoting, providing technical support, creating tutorials, or helping in other ways, please visit the [Start9 website](https://start9.com/contribute).
 
 ## Collaboration
 
-- [Matrix](https://matrix.to/#/#community-dev:matrix.start9labs.com)
-- [Telegram](https://t.me/start9_labs/47471)
+- [Matrix](https://matrix.to/#/#dev-startos:matrix.start9labs.com)
 
-## Project Structure
-
-```bash
-/
-├── assets/
-├── core/
-├── build/
-├── debian/
-├── web/
-├── image-recipe/
-├── patch-db
-└── system-images/
-```
-#### assets
-screenshots for the StartOS README
-
-#### core
-An API, daemon (startd), CLI (start-cli), and SDK (start-sdk) that together provide the core functionality of StartOS.
-
-#### build
-Auxiliary files and scripts to include in deployed StartOS images
-
-#### debian
-Maintainer scripts for the StartOS Debian package
-
-#### web
-Web UIs served under various conditions and used to interact with StartOS APIs.
-
-#### image-recipe
-Scripts for building StartOS images
-
-#### patch-db (submodule)
-A diff based data store used to synchronize data between the web interfaces and server.
-
-#### system-images
-Docker images that assist with creating backups.
+For project structure and system architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## Environment Setup
 
-#### Clone the StartOS repository
+### Installing Dependencies (Debian/Ubuntu)
+
+> Debian/Ubuntu is the only officially supported build environment.
+> MacOS has limited build capabilities and Windows requires [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install).
+
 ```sh
-git clone https://github.com/Start9Labs/start-os.git
+sudo apt update
+sudo apt install -y ca-certificates curl gpg build-essential
+curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
+echo "deb [arch=$(dpkg-architecture -q DEB_HOST_ARCH) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian bookworm stable" | sudo tee /etc/apt/sources.list.d/docker.list
+sudo apt update
+sudo apt install -y sed grep gawk jq gzip brotli containerd.io docker-ce docker-ce-cli docker-compose-plugin qemu-user-static binfmt-support squashfs-tools git debspawn rsync b3sum
+sudo mkdir -p /etc/debspawn/
+echo "AllowUnsafePermissions=true" | sudo tee /etc/debspawn/global.toml
+sudo usermod -aG docker $USER
+sudo su $USER
+docker run --privileged --rm tonistiigi/binfmt --install all
+docker buildx create --use
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # proceed with default installation
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
+source ~/.bashrc
+nvm install 24
+nvm use 24
+nvm alias default 24 # this prevents your machine from reverting back to another version
+```
+
+### Cloning the Repository
+
+```sh
+git clone --recursive https://github.com/Start9Labs/start-os.git --branch next/major
 cd start-os
 ```
 
-#### Load the PatchDB submodule
+### Development Mode
+
+For faster iteration during development:
+
 ```sh
-git submodule update --init --recursive
+. ./devmode.sh
 ```
 
-#### Continue to your project of interest for additional instructions:
-- [`core`](core/README.md)
-- [`web-interfaces`](web-interfaces/README.md)
-- [`build`](build/README.md)
-- [`patch-db`](https://github.com/Start9Labs/patch-db)
+This sets `ENVIRONMENT=dev` and `GIT_BRANCH_AS_HASH=1` to prevent rebuilds on every commit.
 
 ## Building
-This project uses [GNU Make](https://www.gnu.org/software/make/) to build its components. To build any specific component, simply run `make <TARGET>` replacing `<TARGET>` with the name of the target you'd like to build
+
+All builds can be performed on any operating system that can run Docker.
+
+This project uses [GNU Make](https://www.gnu.org/software/make/) to build its components.
 
 ### Requirements
+
 - [GNU Make](https://www.gnu.org/software/make/)
-- [Docker](https://docs.docker.com/get-docker/)
-- [NodeJS v18.15.0](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
-- [sed](https://www.gnu.org/software/sed/)
-- [grep](https://www.gnu.org/software/grep/)
-- [awk](https://www.gnu.org/software/gawk/)
+- [Docker](https://docs.docker.com/get-docker/) or [Podman](https://podman.io/)
+- [NodeJS v20.16.0](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+- [Rust](https://rustup.rs/) (nightly for formatting)
+- [sed](https://www.gnu.org/software/sed/), [grep](https://www.gnu.org/software/grep/), [awk](https://www.gnu.org/software/gawk/)
 - [jq](https://jqlang.github.io/jq/)
-- [gzip](https://www.gnu.org/software/gzip/)
-- [brotli](https://github.com/google/brotli)
+- [gzip](https://www.gnu.org/software/gzip/), [brotli](https://github.com/google/brotli)
 
-### Environment variables
-- `PLATFORM`: which platform you would like to build for. Must be one of `x86_64`, `x86_64-nonfree`, `aarch64`, `aarch64-nonfree`, `raspberrypi`
-    - NOTE: `nonfree` images are for including `nonfree` firmware packages in the built ISO
-- `ENVIRONMENT`: a hyphen separated set of feature flags to enable
-    - `dev`: enables password ssh (INSECURE!) and does not compress frontends
-    - `unstable`: enables assertions that will cause errors on unexpected inconsistencies that are undesirable in production use either for performance or reliability reasons
-    - `docker`: use `docker` instead of `podman`
-- `GIT_BRANCH_AS_HASH`: set to `1` to use the current git branch name as the git hash so that the project does not need to be rebuilt on each commit
+### Environment Variables
 
-### Useful Make Targets
-- `iso`: Create a full `.iso` image
-    - Only possible from Debian
-    - Not available for `PLATFORM=raspberrypi`
-    - Additional Requirements:
-        - [debspawn](https://github.com/lkhq/debspawn)
-- `img`: Create a full `.img` image
-    - Only possible from Debian
-    - Only available for `PLATFORM=raspberrypi`
-    - Additional Requirements:
-        - [debspawn](https://github.com/lkhq/debspawn)
-- `format`: Run automatic code formatting for the project
-    - Additional Requirements:
-        - [rust](https://rustup.rs/)
-- `test`: Run automated tests for the project
-    - Additional Requirements:
-        - [rust](https://rustup.rs/)
-- `update`: Deploy the current working project to a device over ssh as if through an over-the-air update
-    - Requires an argument `REMOTE` which is the ssh address of the device, i.e. `start9@192.168.122.2`
-- `reflash`: Deploy the current working project to a device over ssh as if using a live `iso` image to reflash it
-    - Requires an argument `REMOTE` which is the ssh address of the device, i.e. `start9@192.168.122.2`
-- `update-overlay`: Deploy the current working project to a device over ssh to the in-memory overlay without restarting it
-    - WARNING: changes will be reverted after the device is rebooted
-    - WARNING: changes to `init` will not take effect as the device is already initialized
-    - Requires an argument `REMOTE` which is the ssh address of the device, i.e. `start9@192.168.122.2`
-- `wormhole`: Deploy the `startbox` to a device using [magic-wormhole](https://github.com/magic-wormhole/magic-wormhole)
-    - When the build it complete will emit a command to paste into the shell of the device to upgrade it
-    - Additional Requirements:
-        - [magic-wormhole](https://github.com/magic-wormhole/magic-wormhole)
-- `clean`: Delete all compiled artifacts
+| Variable             | Description                                                                                         |
+| -------------------- | --------------------------------------------------------------------------------------------------- |
+| `PLATFORM`           | Target platform: `x86_64`, `x86_64-nonfree`, `aarch64`, `aarch64-nonfree`, `riscv64`, `raspberrypi` |
+| `ENVIRONMENT`        | Hyphen-separated feature flags (see below)                                                          |
+| `PROFILE`            | Build profile: `release` (default) or `dev`                                                         |
+| `GIT_BRANCH_AS_HASH` | Set to `1` to use git branch name as version hash (avoids rebuilds)                                 |
+
+**ENVIRONMENT flags:**
+
+- `dev` - Enables password SSH before setup, skips frontend compression
+- `unstable` - Enables assertions and debugging with performance penalty
+- `console` - Enables tokio-console for async debugging
+
+**Platform notes:**
+
+- `-nonfree` variants include proprietary firmware and drivers
+- `raspberrypi` includes non-free components by necessity
+- Platform is remembered between builds if not specified
+
+### Make Targets
+
+#### Building
+
+| Target        | Description                                    |
+| ------------- | ---------------------------------------------- |
+| `iso`         | Create full `.iso` image (not for raspberrypi) |
+| `img`         | Create full `.img` image (raspberrypi only)    |
+| `deb`         | Build Debian package                           |
+| `all`         | Build all Rust binaries                        |
+| `uis`         | Build all web UIs                              |
+| `ui`          | Build main UI only                             |
+| `ts-bindings` | Generate TypeScript bindings from Rust types   |
+
+#### Deploying to Device
+
+For devices on the same network:
+
+| Target                               | Description                                     |
+| ------------------------------------ | ----------------------------------------------- |
+| `update-startbox REMOTE=start9@<ip>` | Deploy binary + UI only (fastest)               |
+| `update-deb REMOTE=start9@<ip>`      | Deploy full Debian package                      |
+| `update REMOTE=start9@<ip>`          | OTA-style update                                |
+| `reflash REMOTE=start9@<ip>`         | Reflash as if using live ISO                    |
+| `update-overlay REMOTE=start9@<ip>`  | Deploy to in-memory overlay (reverts on reboot) |
+
+For devices on different networks (uses [magic-wormhole](https://github.com/magic-wormhole/magic-wormhole)):
+
+| Target              | Description          |
+| ------------------- | -------------------- |
+| `wormhole`          | Send startbox binary |
+| `wormhole-deb`      | Send Debian package  |
+| `wormhole-squashfs` | Send squashfs image  |
+
+### Creating a VM
+
+Install virt-manager:
+
+```sh
+sudo apt update
+sudo apt install -y virt-manager
+sudo usermod -aG libvirt $USER
+sudo su $USER
+virt-manager
+```
+
+Follow the screenshot walkthrough in [`assets/create-vm/`](assets/create-vm/) to create a new virtual machine. Key steps:
+
+1. Create a new virtual machine
+2. Browse for the ISO — create a storage pool pointing to your `results/` directory
+3. Select "Generic or unknown OS"
+4. Set memory and CPUs
+5. Create a disk and name the VM
+
+Build an ISO first:
+
+```sh
+PLATFORM=$(uname -m) ENVIRONMENT=dev make iso
+```
+
+#### Other
+
+| Target                   | Description                                 |
+| ------------------------ | ------------------------------------------- |
+| `format`                 | Run code formatting (Rust nightly required) |
+| `test`                   | Run all automated tests                     |
+| `test-core`              | Run Rust tests                              |
+| `test-sdk`               | Run SDK tests                               |
+| `test-container-runtime` | Run container runtime tests                 |
+| `clean`                  | Delete all compiled artifacts               |
+
+## Testing
+
+```bash
+make test                    # All tests
+make test-core               # Rust tests (via ./core/run-tests.sh)
+make test-sdk                # SDK tests
+make test-container-runtime  # Container runtime tests
+
+# Run specific Rust test
+cd core && cargo test <test_name> --features=test
+```
+
+## Code Formatting
+
+```bash
+# Rust (requires nightly)
+make format
+
+# TypeScript/HTML/SCSS (web)
+cd web && npm run format
+```
+
+## Code Style Guidelines
+
+### Formatting
+
+Run the formatters before committing. Configuration is handled by `rustfmt.toml` (Rust) and prettier configs (TypeScript).
+
+### Documentation & Comments
+
+**Rust:**
+
+- Add doc comments (`///`) to public APIs, structs, and non-obvious functions
+- Use `//` comments sparingly for complex logic that isn't self-evident
+- Prefer self-documenting code (clear naming, small functions) over comments
+
+**TypeScript:**
+
+- Document exported functions and complex types with JSDoc
+- Keep comments focused on "why" rather than "what"
+
+**General:**
+
+- Don't add comments that just restate the code
+- Update or remove comments when code changes
+- TODOs should include context: `// TODO(username): reason`
+
+### Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+
+- `feat` - New feature
+- `fix` - Bug fix
+- `docs` - Documentation only
+- `style` - Formatting, no code change
+- `refactor` - Code change that neither fixes a bug nor adds a feature
+- `test` - Adding or updating tests
+- `chore` - Build process, dependencies, etc.
+
+**Examples:**
+
+```
+feat(web): add dark mode toggle
+fix(core): resolve race condition in service startup
+docs: update CONTRIBUTING.md with style guidelines
+refactor(sdk): simplify package validation logic
+```

Makefile

@@ -1,32 +1,44 @@
-PLATFORM_FILE := $(shell ./check-platform.sh)
-ENVIRONMENT_FILE := $(shell ./check-environment.sh)
-GIT_HASH_FILE := $(shell ./check-git-hash.sh)
-VERSION_FILE := $(shell ./check-version.sh)
-BASENAME := $(shell ./basename.sh)
-PLATFORM := $(shell if [ -f ./PLATFORM.txt ]; then cat ./PLATFORM.txt; else echo unknown; fi)
-ARCH := $(shell if [ "$(PLATFORM)" = "raspberrypi" ]; then echo aarch64; else echo $(PLATFORM) | sed 's/-nonfree$$//g'; fi)
+ls-files = $(shell git ls-files --cached --others --exclude-standard $1) 
+PROFILE = release
+
+PLATFORM_FILE := $(shell ./build/env/check-platform.sh)
+ENVIRONMENT_FILE := $(shell ./build/env/check-environment.sh)
+GIT_HASH_FILE := $(shell ./build/env/check-git-hash.sh)
+VERSION_FILE := $(shell ./build/env/check-version.sh)
+BASENAME := $(shell PROJECT=startos ./build/env/basename.sh)
+PLATFORM := $(shell if [ -f $(PLATFORM_FILE) ]; then cat $(PLATFORM_FILE); else echo unknown; fi)
+ARCH := $(shell if [ "$(PLATFORM)" = "raspberrypi" ]; then echo aarch64; elif [ "$(PLATFORM)" = "rockchip64" ]; then echo aarch64; else echo $(PLATFORM) | sed 's/-nonfree$$//g; s/-nvidia$$//g'; fi)
+RUST_ARCH := $(shell if [ "$(ARCH)" = "riscv64" ]; then echo riscv64gc; else echo $(ARCH); fi)
+REGISTRY_BASENAME := $(shell PROJECT=start-registry PLATFORM=$(ARCH) ./build/env/basename.sh)
+TUNNEL_BASENAME := $(shell PROJECT=start-tunnel PLATFORM=$(ARCH) ./build/env/basename.sh)
 IMAGE_TYPE=$(shell if [ "$(PLATFORM)" = raspberrypi ]; then echo img; else echo iso; fi)
-BINS := core/target/$(ARCH)-unknown-linux-gnu/release/startbox core/target/aarch64-unknown-linux-musl/release/container-init core/target/x86_64-unknown-linux-musl/release/container-init
-WEB_UIS := web/dist/raw/ui web/dist/raw/setup-wizard web/dist/raw/diagnostic-ui web/dist/raw/install-wizard
-FIRMWARE_ROMS := ./firmware/$(PLATFORM) $(shell jq --raw-output '.[] | select(.platform[] | contains("$(PLATFORM)")) | "./firmware/$(PLATFORM)/" + .id + ".rom.gz"' build/lib/firmware.json)
-BUILD_SRC := $(shell git ls-files build) build/lib/depends build/lib/conflicts $(FIRMWARE_ROMS)
-DEBIAN_SRC := $(shell git ls-files debian/)
-IMAGE_RECIPE_SRC := $(shell git ls-files image-recipe/)
-STARTD_SRC := core/startos/startd.service $(BUILD_SRC)
-COMPAT_SRC := $(shell git ls-files system-images/compat/)
-UTILS_SRC := $(shell git ls-files system-images/utils/)
-BINFMT_SRC := $(shell git ls-files system-images/binfmt/)
-CORE_SRC := $(shell git ls-files core) $(shell git ls-files --recurse-submodules patch-db) web/dist/static web/patchdb-ui-seed.json $(GIT_HASH_FILE)
-WEB_SHARED_SRC := $(shell git ls-files web/projects/shared) $(shell ls -p web/ | grep -v / | sed 's/^/web\//g') web/node_modules web/config.json patch-db/client/dist web/patchdb-ui-seed.json
-WEB_UI_SRC := $(shell git ls-files web/projects/ui)
-WEB_SETUP_WIZARD_SRC := $(shell git ls-files web/projects/setup-wizard)
-WEB_DIAGNOSTIC_UI_SRC := $(shell git ls-files web/projects/diagnostic-ui)
-WEB_INSTALL_WIZARD_SRC := $(shell git ls-files web/projects/install-wizard)
+WEB_UIS := web/dist/raw/ui/index.html web/dist/raw/setup-wizard/index.html
+COMPRESSED_WEB_UIS := web/dist/static/ui/index.html web/dist/static/setup-wizard/index.html
+FIRMWARE_ROMS := build/lib/firmware/$(PLATFORM) $(shell jq --raw-output '.[] | select(.platform[] | contains("$(PLATFORM)")) | "./build/lib/firmware/$(PLATFORM)/" + .id + ".rom.gz"' build/lib/firmware.json)
+BUILD_SRC := $(call ls-files, build/lib) build/lib/depends build/lib/conflicts $(FIRMWARE_ROMS)
+IMAGE_RECIPE_SRC := $(call ls-files, build/image-recipe/)
+STARTD_SRC := core/startd.service $(BUILD_SRC)
+CORE_SRC := $(call ls-files, core) $(shell git ls-files --recurse-submodules patch-db) $(GIT_HASH_FILE)
+WEB_SHARED_SRC := $(call ls-files, web/projects/shared) $(call ls-files, web/projects/marketplace) $(shell ls -p web/ | grep -v / | sed 's/^/web\//g') web/node_modules/.package-lock.json web/config.json patch-db/client/dist/index.js sdk/baseDist/package.json web/patchdb-ui-seed.json sdk/dist/package.json
+WEB_UI_SRC := $(call ls-files, web/projects/ui)
+WEB_SETUP_WIZARD_SRC := $(call ls-files, web/projects/setup-wizard)
+WEB_START_TUNNEL_SRC := $(call ls-files, web/projects/start-tunnel)
 PATCH_DB_CLIENT_SRC := $(shell git ls-files --recurse-submodules patch-db/client)
 GZIP_BIN := $(shell which pigz || which gzip)
 TAR_BIN := $(shell which gtar || which tar)
-COMPILED_TARGETS := $(BINS) system-images/compat/docker-images/$(ARCH).tar system-images/utils/docker-images/$(ARCH).tar system-images/binfmt/docker-images/$(ARCH).tar
-ALL_TARGETS := $(STARTD_SRC) $(ENVIRONMENT_FILE) $(GIT_HASH_FILE) $(VERSION_FILE) $(COMPILED_TARGETS) $(shell if [ "$(PLATFORM)" = "raspberrypi" ]; then echo cargo-deps/aarch64-unknown-linux-gnu/release/pi-beep; fi)  $(shell /bin/bash -c 'if [[ "${ENVIRONMENT}" =~ (^|-)unstable($$|-) ]]; then echo cargo-deps/$(ARCH)-unknown-linux-gnu/release/tokio-console; fi') $(PLATFORM_FILE)
+COMPILED_TARGETS := core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/startbox core/target/$(RUST_ARCH)-unknown-linux-musl/release/start-container container-runtime/rootfs.$(ARCH).squashfs
+STARTOS_TARGETS := $(STARTD_SRC) $(ENVIRONMENT_FILE) $(GIT_HASH_FILE) $(VERSION_FILE) $(COMPILED_TARGETS) target/$(RUST_ARCH)-unknown-linux-musl/release/startos-backup-fs $(PLATFORM_FILE) \
+	$(shell if [ "$(PLATFORM)" = "raspberrypi" ]; then \
+		echo target/aarch64-unknown-linux-musl/release/pi-beep; \
+	fi) \
+	$(shell /bin/bash -c 'if [[ "${ENVIRONMENT}" =~ (^|-)unstable($$|-) ]]; then \
+		echo target/$(RUST_ARCH)-unknown-linux-musl/release/flamegraph; \
+	fi') \
+	$(shell /bin/bash -c 'if [[ "${ENVIRONMENT}" =~ (^|-)console($$|-) ]]; then \
+		echo target/$(RUST_ARCH)-unknown-linux-musl/release/tokio-console; \
+	fi')
+REGISTRY_TARGETS := core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/registrybox core/start-registryd.service
+TUNNEL_TARGETS := core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/tunnelbox core/start-tunneld.service
 
 ifeq ($(REMOTE),)
 	mkdir = mkdir -p $1
@@ -49,19 +61,18 @@ endif
 
 .DELETE_ON_ERROR:
 
-.PHONY: all metadata install clean format sdk snapshots uis ui reflash deb $(IMAGE_TYPE) squashfs sudo wormhole test
+.PHONY: all metadata install clean format install-cli cli uis ui reflash deb $(IMAGE_TYPE) squashfs wormhole wormhole-deb test test-core test-sdk test-container-runtime registry install-registry tunnel install-tunnel ts-bindings
 
-all: $(ALL_TARGETS)
+all: $(STARTOS_TARGETS)
+
+touch:
+	touch $(STARTOS_TARGETS)
 
 metadata: $(VERSION_FILE) $(PLATFORM_FILE) $(ENVIRONMENT_FILE) $(GIT_HASH_FILE)
 
-sudo:
-	sudo true
-
 clean:
-	rm -f system-images/**/*.tar
-	rm -rf system-images/compat/target
 	rm -rf core/target
+	rm -rf core/bindings
 	rm -rf web/.angular
 	rm -f web/config.json
 	rm -rf web/node_modules
@@ -69,157 +80,285 @@ clean:
 	rm -rf patch-db/client/node_modules
 	rm -rf patch-db/client/dist
 	rm -rf patch-db/target
-	rm -rf cargo-deps
+	rm -rf target
 	rm -rf dpkg-workdir
 	rm -rf image-recipe/deb
 	rm -rf results
 	rm -rf build/lib/firmware
-	rm -f ENVIRONMENT.txt
-	rm -f PLATFORM.txt
-	rm -f GIT_HASH.txt
-	rm -f VERSION.txt
+	rm -rf container-runtime/dist
+	rm -rf container-runtime/node_modules
+	rm -f container-runtime/*.squashfs
+	(cd sdk && make clean)
+	rm -f env/*.txt
 
 format:
 	cd core && cargo +nightly fmt
 
-test: $(CORE_SRC) $(ENVIRONMENT_FILE)
-	cd core && cargo build && cargo test
+test: | test-core test-sdk test-container-runtime
 
-sdk:
-	cd core && ./install-sdk.sh
+test-core: $(CORE_SRC) $(ENVIRONMENT_FILE) 
+	./core/run-tests.sh
+
+test-sdk: $(call ls-files, sdk) sdk/base/lib/osBindings/index.ts
+	cd sdk && make test
+
+test-container-runtime: container-runtime/node_modules/.package-lock.json $(call ls-files, container-runtime/src) container-runtime/package.json container-runtime/tsconfig.json 
+	cd container-runtime && npm test
+
+install-cli: $(GIT_HASH_FILE)
+	./core/build/build-cli.sh --install
+
+cli: $(GIT_HASH_FILE)
+	./core/build/build-cli.sh
+
+registry: core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/registrybox
+
+install-registry: $(REGISTRY_TARGETS)
+	$(call mkdir,$(DESTDIR)/usr/bin)
+	$(call cp,core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/registrybox,$(DESTDIR)/usr/bin/start-registrybox)
+	$(call ln,/usr/bin/start-registrybox,$(DESTDIR)/usr/bin/start-registryd)
+	$(call ln,/usr/bin/start-registrybox,$(DESTDIR)/usr/bin/start-registry)
+
+	$(call mkdir,$(DESTDIR)/lib/systemd/system)
+	$(call cp,core/start-registryd.service,$(DESTDIR)/lib/systemd/system/start-registryd.service)
+
+core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/registrybox: $(CORE_SRC) $(ENVIRONMENT_FILE)
+	ARCH=$(ARCH) PROFILE=$(PROFILE) ./core/build/build-registrybox.sh
+
+tunnel: core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/tunnelbox
+
+install-tunnel: core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/tunnelbox core/start-tunneld.service
+	$(call mkdir,$(DESTDIR)/usr/bin)
+	$(call cp,core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/tunnelbox,$(DESTDIR)/usr/bin/start-tunnelbox)
+	$(call ln,/usr/bin/start-tunnelbox,$(DESTDIR)/usr/bin/start-tunneld)
+	$(call ln,/usr/bin/start-tunnelbox,$(DESTDIR)/usr/bin/start-tunnel)
+
+	$(call mkdir,$(DESTDIR)/lib/systemd/system)
+	$(call cp,core/start-tunneld.service,$(DESTDIR)/lib/systemd/system/start-tunneld.service)
+
+	$(call mkdir,$(DESTDIR)/usr/lib/startos/scripts)
+	$(call cp,build/lib/scripts/forward-port,$(DESTDIR)/usr/lib/startos/scripts/forward-port)
+
+	$(call mkdir,$(DESTDIR)/etc/apt/sources.list.d)
+	$(call cp,apt/start9.list,$(DESTDIR)/etc/apt/sources.list.d/start9.list)
+	$(call mkdir,$(DESTDIR)/usr/share/keyrings)
+	$(call cp,apt/start9.gpg,$(DESTDIR)/usr/share/keyrings/start9.gpg)
+
+core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/tunnelbox: $(CORE_SRC) $(ENVIRONMENT_FILE) $(GIT_HASH_FILE) web/dist/static/start-tunnel/index.html
+	ARCH=$(ARCH) PROFILE=$(PROFILE) ./core/build/build-tunnelbox.sh
 
 deb: results/$(BASENAME).deb
 
-debian/control: build/lib/depends build/lib/conflicts
-	./debuild/control.sh
+results/$(BASENAME).deb: debian/dpkg-build.sh $(call ls-files,debian/startos) $(STARTOS_TARGETS)
+	PLATFORM=$(PLATFORM) REQUIRES=debian ./build/os-compat/run-compat.sh ./debian/dpkg-build.sh
 
-results/$(BASENAME).deb: dpkg-build.sh $(DEBIAN_SRC) $(VERSION_FILE) $(PLATFORM_FILE) $(ENVIRONMENT_FILE) $(GIT_HASH_FILE)
-	PLATFORM=$(PLATFORM) ./dpkg-build.sh
+registry-deb: results/$(REGISTRY_BASENAME).deb
+
+results/$(REGISTRY_BASENAME).deb: debian/dpkg-build.sh $(call ls-files,debian/start-registry) $(REGISTRY_TARGETS)
+	PROJECT=start-registry PLATFORM=$(ARCH) REQUIRES=debian ./build/os-compat/run-compat.sh ./debian/dpkg-build.sh
+
+tunnel-deb: results/$(TUNNEL_BASENAME).deb
+
+results/$(TUNNEL_BASENAME).deb: debian/dpkg-build.sh $(call ls-files,debian/start-tunnel) $(TUNNEL_TARGETS) build/lib/scripts/forward-port
+	PROJECT=start-tunnel PLATFORM=$(ARCH) REQUIRES=debian DEPENDS=wireguard-tools,iptables,conntrack ./build/os-compat/run-compat.sh ./debian/dpkg-build.sh
 
 $(IMAGE_TYPE): results/$(BASENAME).$(IMAGE_TYPE)
 
 squashfs: results/$(BASENAME).squashfs
 
 results/$(BASENAME).$(IMAGE_TYPE) results/$(BASENAME).squashfs: $(IMAGE_RECIPE_SRC) results/$(BASENAME).deb
-	./image-recipe/run-local-build.sh "results/$(BASENAME).deb"
+	ARCH=$(ARCH) ./build/image-recipe/run-local-build.sh "results/$(BASENAME).deb"
 
 # For creating os images. DO NOT USE
-install: $(ALL_TARGETS)
+install: $(STARTOS_TARGETS)
 	$(call mkdir,$(DESTDIR)/usr/bin)
-	$(call cp,core/target/$(ARCH)-unknown-linux-gnu/release/startbox,$(DESTDIR)/usr/bin/startbox)
+	$(call mkdir,$(DESTDIR)/usr/sbin)
+	$(call cp,core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/startbox,$(DESTDIR)/usr/bin/startbox)
 	$(call ln,/usr/bin/startbox,$(DESTDIR)/usr/bin/startd)
 	$(call ln,/usr/bin/startbox,$(DESTDIR)/usr/bin/start-cli)
-	$(call ln,/usr/bin/startbox,$(DESTDIR)/usr/bin/start-sdk)
-	$(call ln,/usr/bin/startbox,$(DESTDIR)/usr/bin/start-deno)
-	$(call ln,/usr/bin/startbox,$(DESTDIR)/usr/bin/avahi-alias)
-	$(call ln,/usr/bin/startbox,$(DESTDIR)/usr/bin/embassy-cli)
-	if [ "$(PLATFORM)" = "raspberrypi" ]; then $(call cp,cargo-deps/aarch64-unknown-linux-gnu/release/pi-beep,$(DESTDIR)/usr/bin/pi-beep); fi
-	if /bin/bash -c '[[ "${ENVIRONMENT}" =~ (^|-)unstable($$|-) ]]'; then $(call cp,cargo-deps/$(ARCH)-unknown-linux-gnu/release/tokio-console,$(DESTDIR)/usr/bin/tokio-console); fi
+	if [ "$(PLATFORM)" = "raspberrypi" ]; then $(call cp,target/aarch64-unknown-linux-musl/release/pi-beep,$(DESTDIR)/usr/bin/pi-beep); fi
+	if /bin/bash -c '[[ "${ENVIRONMENT}" =~ (^|-)unstable($$|-) ]]'; then \
+		$(call cp,target/$(RUST_ARCH)-unknown-linux-musl/release/flamegraph,$(DESTDIR)/usr/bin/flamegraph); \
+	fi
+	if /bin/bash -c '[[ "${ENVIRONMENT}" =~ (^|-)console($$|-) ]]'; then \
+		$(call cp,target/$(RUST_ARCH)-unknown-linux-musl/release/tokio-console,$(DESTDIR)/usr/bin/tokio-console); \
+	fi
+	$(call cp,target/$(RUST_ARCH)-unknown-linux-musl/release/startos-backup-fs,$(DESTDIR)/usr/bin/startos-backup-fs)
+	$(call ln,/usr/bin/startos-backup-fs,$(DESTDIR)/usr/sbin/mount.backup-fs)
 	
 	$(call mkdir,$(DESTDIR)/lib/systemd/system)
-	$(call cp,core/startos/startd.service,$(DESTDIR)/lib/systemd/system/startd.service)
+	$(call cp,core/startd.service,$(DESTDIR)/lib/systemd/system/startd.service)
 
 	$(call mkdir,$(DESTDIR)/usr/lib)
 	$(call rm,$(DESTDIR)/usr/lib/startos)
 	$(call cp,build/lib,$(DESTDIR)/usr/lib/startos)
+	$(call mkdir,$(DESTDIR)/usr/lib/startos/container-runtime)
+	$(call cp,container-runtime/rootfs.$(ARCH).squashfs,$(DESTDIR)/usr/lib/startos/container-runtime/rootfs.squashfs)
 
-	$(call cp,PLATFORM.txt,$(DESTDIR)/usr/lib/startos/PLATFORM.txt)
-	$(call cp,ENVIRONMENT.txt,$(DESTDIR)/usr/lib/startos/ENVIRONMENT.txt)
-	$(call cp,GIT_HASH.txt,$(DESTDIR)/usr/lib/startos/GIT_HASH.txt)
-	$(call cp,VERSION.txt,$(DESTDIR)/usr/lib/startos/VERSION.txt)
+	$(call cp,build/env/PLATFORM.txt,$(DESTDIR)/usr/lib/startos/PLATFORM.txt)
+	$(call cp,build/env/ENVIRONMENT.txt,$(DESTDIR)/usr/lib/startos/ENVIRONMENT.txt)
+	$(call cp,build/env/GIT_HASH.txt,$(DESTDIR)/usr/lib/startos/GIT_HASH.txt)
+	$(call cp,build/env/VERSION.txt,$(DESTDIR)/usr/lib/startos/VERSION.txt)
 
-	$(call mkdir,$(DESTDIR)/usr/lib/startos/container)
-	$(call cp,core/target/aarch64-unknown-linux-musl/release/container-init,$(DESTDIR)/usr/lib/startos/container/container-init.arm64)
-	$(call cp,core/target/x86_64-unknown-linux-musl/release/container-init,$(DESTDIR)/usr/lib/startos/container/container-init.amd64)
-
-	$(call mkdir,$(DESTDIR)/usr/lib/startos/system-images)
-	$(call cp,system-images/compat/docker-images/$(ARCH).tar,$(DESTDIR)/usr/lib/startos/system-images/compat.tar)
-	$(call cp,system-images/utils/docker-images/$(ARCH).tar,$(DESTDIR)/usr/lib/startos/system-images/utils.tar)
-	$(call cp,system-images/binfmt/docker-images/$(ARCH).tar,$(DESTDIR)/usr/lib/startos/system-images/binfmt.tar)
-	
-	$(call cp,firmware/$(PLATFORM),$(DESTDIR)/usr/lib/startos/firmware)
-
-update-overlay: $(ALL_TARGETS)
+update-overlay: $(STARTOS_TARGETS)
 	@echo "\033[33m!!! THIS WILL ONLY REFLASH YOUR DEVICE IN MEMORY !!!\033[0m"
 	@echo "\033[33mALL CHANGES WILL BE REVERTED IF YOU RESTART THE DEVICE\033[0m"
 	@if [ -z "$(REMOTE)" ]; then >&2 echo "Must specify REMOTE" && false; fi
-	@if [ "`ssh $(REMOTE) 'cat /usr/lib/startos/VERSION.txt'`" != "`cat ./VERSION.txt`" ]; then >&2 echo "StartOS requires migrations: update-overlay is unavailable." && false; fi
+	@if [ "`ssh $(REMOTE) 'cat /usr/lib/startos/VERSION.txt'`" != "`cat $(VERSION_FILE)`" ]; then >&2 echo "StartOS requires migrations: update-overlay is unavailable." && false; fi
 	$(call ssh,"sudo systemctl stop startd")
 	$(MAKE) install REMOTE=$(REMOTE) SSHPASS=$(SSHPASS) PLATFORM=$(PLATFORM)
 	$(call ssh,"sudo systemctl start startd")
 
-wormhole: core/target/$(ARCH)-unknown-linux-gnu/release/startbox
-	@wormhole send core/target/$(ARCH)-unknown-linux-gnu/release/startbox 2>&1 | awk -Winteractive '/wormhole receive/ { printf "sudo /usr/lib/startos/scripts/chroot-and-upgrade \"cd /usr/bin && rm startbox && wormhole receive --accept-file %s && chmod +x startbox\"\n", $$3 }'
+wormhole: core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/startbox
+	@echo "Paste the following command into the shell of your StartOS server:"
+	@echo
+	@wormhole send core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/startbox 2>&1 | awk -Winteractive '/wormhole receive/ { printf "sudo /usr/lib/startos/scripts/chroot-and-upgrade \"cd /usr/bin && rm startbox && wormhole receive --accept-file %s && chmod +x startbox\"\n", $$3 }'
 
-update: $(ALL_TARGETS)
-	@if [ -z "$(REMOTE)" ]; then >&2 echo "Must specify REMOTE" && false; fi
-	$(call ssh,"sudo rsync -a --delete --force --info=progress2 /media/embassy/embassyfs/current/ /media/embassy/next/")
-	$(MAKE) install REMOTE=$(REMOTE) SSHPASS=$(SSHPASS) DESTDIR=/media/embassy/next PLATFORM=$(PLATFORM)
-	$(call ssh,'sudo NO_SYNC=1 /media/embassy/next/usr/lib/startos/scripts/chroot-and-upgrade "apt-get install -y $(shell cat ./build/lib/depends)"')
+wormhole-deb: results/$(BASENAME).deb
+	@echo "Paste the following command into the shell of your StartOS server:"
+	@echo
+	@wormhole send results/$(BASENAME).deb 2>&1 | awk -Winteractive '/wormhole receive/ { printf "sudo /usr/lib/startos/scripts/chroot-and-upgrade '"'"'cd $$(mktemp -d) && wormhole receive --accept-file %s && apt-get install -y --reinstall ./$(BASENAME).deb'"'"'\n", $$3 }'
 
-emulate-reflash: $(ALL_TARGETS)
+wormhole-squashfs: results/$(BASENAME).squashfs
+	$(eval SQFS_SUM := $(shell b3sum results/$(BASENAME).squashfs | head -c 32))
+	$(eval SQFS_SIZE := $(shell du -s --bytes results/$(BASENAME).squashfs | awk '{print $$1}'))
+	@echo "Paste the following command into the shell of your StartOS server:"
+	@echo
+	@wormhole send results/$(BASENAME).squashfs 2>&1 | awk -Winteractive '/wormhole receive/ { printf "sudo sh -c '"'"'/usr/lib/startos/scripts/prune-images $(SQFS_SIZE) && /usr/lib/startos/scripts/prune-boot && cd /media/startos/images && wormhole receive --accept-file %s && CHECKSUM=$(SQFS_SUM) /usr/lib/startos/scripts/upgrade ./$(BASENAME).squashfs'"'"'\n", $$3 }'
+
+update: $(STARTOS_TARGETS)
 	@if [ -z "$(REMOTE)" ]; then >&2 echo "Must specify REMOTE" && false; fi
-	$(call ssh,"sudo rsync -a --delete --force --info=progress2 /media/embassy/embassyfs/current/ /media/embassy/next/")
-	$(MAKE) install REMOTE=$(REMOTE) SSHPASS=$(SSHPASS) DESTDIR=/media/embassy/next PLATFORM=$(PLATFORM)
-	$(call ssh,"sudo touch /media/embassy/config/upgrade && sudo rm -f /media/embassy/config/disk.guid && sudo sync && sudo reboot")
+	$(call ssh,'sudo /usr/lib/startos/scripts/chroot-and-upgrade --create')
+	$(MAKE) install REMOTE=$(REMOTE) SSHPASS=$(SSHPASS) DESTDIR=/media/startos/next PLATFORM=$(PLATFORM)
+	$(call ssh,'sudo /media/startos/next/usr/lib/startos/scripts/chroot-and-upgrade --no-sync "apt-get install -y $(shell cat ./build/lib/depends)"')
+
+update-startbox: core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/startbox # only update binary (faster than full update)
+	@if [ -z "$(REMOTE)" ]; then >&2 echo "Must specify REMOTE" && false; fi
+	$(call ssh,'sudo /usr/lib/startos/scripts/chroot-and-upgrade --create')
+	$(call cp,core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/startbox,/media/startos/next/usr/bin/startbox)
+	$(call ssh,'sudo /media/startos/next/usr/lib/startos/scripts/chroot-and-upgrade --no-sync true')
+
+update-deb: results/$(BASENAME).deb # better than update, but only available from debian
+	@if [ -z "$(REMOTE)" ]; then >&2 echo "Must specify REMOTE" && false; fi
+	$(call ssh,'sudo /usr/lib/startos/scripts/chroot-and-upgrade --create')
+	$(call mkdir,/media/startos/next/var/tmp/startos-deb)
+	$(call cp,results/$(BASENAME).deb,/media/startos/next/var/tmp/startos-deb/$(BASENAME).deb)
+	$(call ssh,'sudo /media/startos/next/usr/lib/startos/scripts/chroot-and-upgrade --no-sync "apt-get install -y --reinstall /var/tmp/startos-deb/$(BASENAME).deb"')
+
+update-squashfs: results/$(BASENAME).squashfs
+	@if [ -z "$(REMOTE)" ]; then >&2 echo "Must specify REMOTE" && false; fi
+	$(eval SQFS_SUM := $(shell b3sum results/$(BASENAME).squashfs))
+	$(eval SQFS_SIZE := $(shell du -s --bytes results/$(BASENAME).squashfs | awk '{print $$1}'))
+	$(call ssh,'/usr/lib/startos/scripts/prune-images $(SQFS_SIZE)')
+	$(call ssh,'/usr/lib/startos/scripts/prune-boot')
+	$(call cp,results/$(BASENAME).squashfs,/media/startos/images/next.rootfs)
+	$(call ssh,'sudo CHECKSUM=$(SQFS_SUM) /usr/lib/startos/scripts/upgrade /media/startos/images/next.rootfs')
+
+emulate-reflash: $(STARTOS_TARGETS)
+	@if [ -z "$(REMOTE)" ]; then >&2 echo "Must specify REMOTE" && false; fi
+	$(call ssh,'sudo /usr/lib/startos/scripts/chroot-and-upgrade --create')
+	$(MAKE) install REMOTE=$(REMOTE) SSHPASS=$(SSHPASS) DESTDIR=/media/startos/next PLATFORM=$(PLATFORM)
+	$(call ssh,'sudo rm -f /media/startos/config/disk.guid /media/startos/config/overlay/etc/hostname')
+	$(call ssh,'sudo /media/startos/next/usr/lib/startos/scripts/chroot-and-upgrade --no-sync "apt-get install -y $(shell cat ./build/lib/depends)"')
 
 upload-ota: results/$(BASENAME).squashfs
-	TARGET=$(TARGET) KEY=$(KEY) ./upload-ota.sh
+	TARGET=$(TARGET) KEY=$(KEY) ./build/upload-ota.sh
 
-build/lib/depends build/lib/conflicts: build/dpkg-deps/*
-	build/dpkg-deps/generate.sh
+container-runtime/debian.$(ARCH).squashfs: ./container-runtime/download-base-image.sh
+	ARCH=$(ARCH) ./container-runtime/download-base-image.sh
 
-$(FIRMWARE_ROMS): build/lib/firmware.json download-firmware.sh $(PLATFORM_FILE)
-	./download-firmware.sh $(PLATFORM)
+container-runtime/package-lock.json: sdk/dist/package.json
+	npm --prefix container-runtime i
+	touch container-runtime/package-lock.json
 
-system-images/compat/docker-images/$(ARCH).tar: $(COMPAT_SRC) core/Cargo.lock
-	cd system-images/compat && make docker-images/$(ARCH).tar && touch docker-images/$(ARCH).tar
+container-runtime/node_modules/.package-lock.json: container-runtime/package-lock.json
+	npm --prefix container-runtime ci
+	touch container-runtime/node_modules/.package-lock.json
 
-system-images/utils/docker-images/$(ARCH).tar: $(UTILS_SRC)
-	cd system-images/utils && make docker-images/$(ARCH).tar && touch docker-images/$(ARCH).tar
+ts-bindings: core/bindings/index.ts
+	mkdir -p sdk/base/lib/osBindings
+	rsync -ac --delete core/bindings/ sdk/base/lib/osBindings/
 
-system-images/binfmt/docker-images/$(ARCH).tar: $(BINFMT_SRC)
-	cd system-images/binfmt && make docker-images/$(ARCH).tar && touch docker-images/$(ARCH).tar
+core/bindings/index.ts: $(call ls-files, core) $(ENVIRONMENT_FILE)
+	rm -rf core/bindings
+	./core/build/build-ts.sh
+	ls core/bindings/*.ts | sed 's/core\/bindings\/\([^.]*\)\.ts/export { \1 } from ".\/\1";/g' | grep -v '"./index"' | tee core/bindings/index.ts
+	npm --prefix sdk/base exec -- prettier --config=./sdk/base/package.json -w './core/bindings/**/*.ts'
+	touch core/bindings/index.ts
 
-snapshots: core/snapshot-creator/Cargo.toml
-	cd core/ && ARCH=aarch64 ./build-v8-snapshot.sh
-	cd core/ && ARCH=x86_64 ./build-v8-snapshot.sh
+sdk/dist/package.json sdk/baseDist/package.json: $(call ls-files, sdk) sdk/base/lib/osBindings/index.ts
+	(cd sdk && make bundle)
+	touch sdk/dist/package.json
+	touch sdk/baseDist/package.json
 
-$(BINS): $(CORE_SRC) $(ENVIRONMENT_FILE)
-	cd core && ARCH=$(ARCH) ./build-prod.sh
-	touch $(BINS)
+# TODO: make container-runtime its own makefile?
+container-runtime/dist/index.js: container-runtime/node_modules/.package-lock.json $(call ls-files, container-runtime/src) container-runtime/package.json container-runtime/tsconfig.json 
+	npm --prefix container-runtime run build
 
-web/node_modules: web/package.json
+container-runtime/dist/node_modules/.package-lock.json container-runtime/dist/package.json container-runtime/dist/package-lock.json: container-runtime/package.json container-runtime/package-lock.json sdk/dist/package.json container-runtime/install-dist-deps.sh
+	./container-runtime/install-dist-deps.sh
+	touch container-runtime/dist/node_modules/.package-lock.json
+
+container-runtime/rootfs.$(ARCH).squashfs: container-runtime/debian.$(ARCH).squashfs container-runtime/container-runtime.service container-runtime/update-image.sh container-runtime/update-image-local.sh container-runtime/deb-install.sh container-runtime/dist/index.js container-runtime/dist/node_modules/.package-lock.json core/target/$(RUST_ARCH)-unknown-linux-musl/release/start-container
+	ARCH=$(ARCH) ./container-runtime/update-image-local.sh
+
+build/lib/depends build/lib/conflicts: $(ENVIRONMENT_FILE) $(PLATFORM_FILE) $(shell ls build/dpkg-deps/*)
+	PLATFORM=$(PLATFORM) ARCH=$(ARCH) build/dpkg-deps/generate.sh
+
+$(FIRMWARE_ROMS): build/lib/firmware.json ./build/download-firmware.sh $(PLATFORM_FILE)
+	./build/download-firmware.sh $(PLATFORM)
+
+core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/startbox: $(CORE_SRC) $(COMPRESSED_WEB_UIS) web/patchdb-ui-seed.json $(ENVIRONMENT_FILE)
+	ARCH=$(ARCH) PROFILE=$(PROFILE) ./core/build/build-startbox.sh
+	touch core/target/$(RUST_ARCH)-unknown-linux-musl/$(PROFILE)/startbox
+
+core/target/$(RUST_ARCH)-unknown-linux-musl/release/start-container: $(CORE_SRC) $(ENVIRONMENT_FILE)
+	ARCH=$(ARCH) ./core/build/build-start-container.sh
+	touch core/target/$(RUST_ARCH)-unknown-linux-musl/release/start-container
+
+web/package-lock.json: web/package.json sdk/baseDist/package.json
+	npm --prefix web i
+	touch web/package-lock.json
+
+web/node_modules/.package-lock.json: web/package-lock.json
 	npm --prefix web ci
+	touch web/node_modules/.package-lock.json
 
-web/dist/raw/ui: $(WEB_UI_SRC) $(WEB_SHARED_SRC)
+web/.angular/.updated: patch-db/client/dist/index.js sdk/baseDist/package.json web/node_modules/.package-lock.json
+	rm -rf web/.angular
+	mkdir -p web/.angular
+	touch web/.angular/.updated
+
+web/.i18n-checked: $(WEB_SHARED_SRC) $(WEB_UI_SRC) $(WEB_SETUP_WIZARD_SRC) $(WEB_START_TUNNEL_SRC)
+	npm --prefix web run check:i18n
+	touch web/.i18n-checked
+
+web/dist/raw/ui/index.html: $(WEB_UI_SRC) $(WEB_SHARED_SRC) web/.angular/.updated web/.i18n-checked
 	npm --prefix web run build:ui
+	touch web/dist/raw/ui/index.html
 
-web/dist/raw/setup-wizard: $(WEB_SETUP_WIZARD_SRC) $(WEB_SHARED_SRC)
+web/dist/raw/setup-wizard/index.html: $(WEB_SETUP_WIZARD_SRC) $(WEB_SHARED_SRC) web/.angular/.updated web/.i18n-checked
 	npm --prefix web run build:setup
+	touch web/dist/raw/setup-wizard/index.html
 
-web/dist/raw/diagnostic-ui: $(WEB_DIAGNOSTIC_UI_SRC) $(WEB_SHARED_SRC)
-	npm --prefix web run build:dui
+web/dist/raw/start-tunnel/index.html: $(WEB_START_TUNNEL_SRC) $(WEB_SHARED_SRC) web/.angular/.updated web/.i18n-checked
+	npm --prefix web run build:tunnel
+	touch web/dist/raw/start-tunnel/index.html
 
-web/dist/raw/install-wizard: $(WEB_INSTALL_WIZARD_SRC) $(WEB_SHARED_SRC)
-	npm --prefix web run build:install-wiz
+web/dist/static/%/index.html: web/dist/raw/%/index.html
+	./web/compress-uis.sh $*
 
-web/dist/static: $(WEB_UIS) $(ENVIRONMENT_FILE)
-	./compress-uis.sh
+web/config.json: $(GIT_HASH_FILE) $(ENVIRONMENT_FILE) web/config-sample.json web/update-config.sh
+	./web/update-config.sh	
 
-web/config.json: $(GIT_HASH_FILE) web/config-sample.json
-	jq '.useMocks = false' web/config-sample.json | jq '.gitHash = "$(shell cat GIT_HASH.txt)"' > web/config.json
-
-web/patchdb-ui-seed.json: web/package.json
-	jq '."ack-welcome" = $(shell jq '.version' web/package.json)' web/patchdb-ui-seed.json > ui-seed.tmp
-	mv ui-seed.tmp web/patchdb-ui-seed.json
-
-patch-db/client/node_modules: patch-db/client/package.json
+patch-db/client/node_modules/.package-lock.json: patch-db/client/package.json
 	npm --prefix patch-db/client ci
+	touch patch-db/client/node_modules/.package-lock.json
 
-patch-db/client/dist: $(PATCH_DB_CLIENT_SRC) patch-db/client/node_modules
-	! test -d patch-db/client/dist || rm -rf patch-db/client/dist
-	npm --prefix web run build:deps
+patch-db/client/dist/index.js: $(PATCH_DB_CLIENT_SRC) patch-db/client/node_modules/.package-lock.json
+	rm -rf patch-db/client/dist
+	npm --prefix patch-db/client run build
+	touch patch-db/client/dist/index.js
 
 # used by github actions
 compiled-$(ARCH).tar: $(COMPILED_TARGETS) $(ENVIRONMENT_FILE) $(GIT_HASH_FILE) $(VERSION_FILE)
@@ -231,8 +370,17 @@ uis: $(WEB_UIS)
 # this is a convenience step to build the UI
 ui: web/dist/raw/ui
 
-cargo-deps/aarch64-unknown-linux-gnu/release/pi-beep:
-	ARCH=aarch64 ./build-cargo-dep.sh pi-beep
+target/aarch64-unknown-linux-musl/release/pi-beep: ./build/build-cargo-dep.sh
+	ARCH=aarch64 ./build/build-cargo-dep.sh pi-beep
 
-cargo-deps/$(ARCH)-unknown-linux-gnu/release/tokio-console:
-	ARCH=$(ARCH) ./build-cargo-dep.sh tokio-console
+target/$(RUST_ARCH)-unknown-linux-musl/release/tokio-console: ./build/build-cargo-dep.sh
+	ARCH=$(ARCH) ./build/build-cargo-dep.sh tokio-console
+	touch $@
+
+target/$(RUST_ARCH)-unknown-linux-musl/release/startos-backup-fs: ./build/build-cargo-dep.sh
+	ARCH=$(ARCH) ./build/build-cargo-dep.sh --git https://github.com/Start9Labs/start-fs.git startos-backup-fs
+	touch $@
+
+target/$(RUST_ARCH)-unknown-linux-musl/release/flamegraph: ./build/build-cargo-dep.sh
+	ARCH=$(ARCH) ./build/build-cargo-dep.sh flamegraph
+	touch $@

README.md

@@ -7,79 +7,64 @@
   <a href="https://github.com/Start9Labs/start-os/actions/workflows/startos-iso.yaml">
     <img src="https://github.com/Start9Labs/start-os/actions/workflows/startos-iso.yaml/badge.svg">
   </a>
-    <a href="https://heyapollo.com/product/startos">
+  <a href="https://heyapollo.com/product/startos">
     <img alt="Static Badge" src="https://img.shields.io/badge/apollo-review%20%E2%AD%90%E2%AD%90%E2%AD%90%E2%AD%90%E2%AD%90%20-slateblue">
   </a>
   <a href="https://twitter.com/start9labs">
     <img alt="X (formerly Twitter) Follow" src="https://img.shields.io/twitter/follow/start9labs">
   </a>
-  <a href="https://mastodon.start9labs.com">
-    <img src="https://img.shields.io/mastodon/follow/000000001?domain=https%3A%2F%2Fmastodon.start9labs.com&label=Follow&style=social">
-  </a>
-  <a href="https://matrix.to/#/#community:matrix.start9labs.com">
-    <img alt="Static Badge" src="https://img.shields.io/badge/community-matrix-yellow?logo=matrix">
-  </a>
-  <a href="https://t.me/start9_labs">
-    <img alt="Static Badge" src="https://img.shields.io/badge/community-telegram-blue?logo=telegram">
-  </a>
   <a href="https://docs.start9.com">
     <img alt="Static Badge" src="https://img.shields.io/badge/docs-orange?label=%F0%9F%91%A4%20support">
   </a>
-  <a href="https://matrix.to/#/#community-dev:matrix.start9labs.com">
+  <a href="https://matrix.to/#/#dev-startos:matrix.start9labs.com">
     <img alt="Static Badge" src="https://img.shields.io/badge/developer-matrix-darkcyan?logo=matrix">
   </a>
   <a href="https://start9.com">
     <img alt="Website" src="https://img.shields.io/website?up_message=online&down_message=offline&url=https%3A%2F%2Fstart9.com&logo=website&label=%F0%9F%8C%90%20website">
   </a>
 </div>
-<br />
-<div align="center">
-  <h3>
-    Welcome to the era of Sovereign Computing
-  </h3>
-  <p>
-    StartOS is an open source Linux distribution optimized for running a personal server. It facilitates the discovery, installation, network configuration, service configuration, data backup, dependency management, and health monitoring of self-hosted software services.
-  </p>
-</div>
-<br />
-<p align="center">
-<img src="assets/StartOS.png" alt="StartOS" width="85%">
-</p>
-<br />
 
-## Running StartOS
-> [!WARNING]
-> StartOS is in beta. It lacks features. It doesn't always work perfectly. Start9 servers are not plug and play. Using them properly requires some effort and patience. Please do not use StartOS or purchase a server if you are unable or unwilling to follow instructions and learn new concepts.
+## What is StartOS?
 
-### 💰 Buy a Start9 server
-This is the most convenient option. Simply [buy a server](https://store.start9.com) from Start9 and plug it in.
+StartOS is an open-source Linux distribution for running a personal server. It handles discovery, installation, network configuration, data backup, dependency management, and health monitoring of self-hosted services.
 
-### 👷 Build your own server
-This option is easier than you might imagine, and there are 4 reasons why you might prefer it:
-1. You already have hardware
-1. You want to save on shipping costs
-1. You prefer not to divulge your physical address
-1. You just like building things
+**Tech stack:** Rust backend (Tokio/Axum), Angular frontend, Node.js container runtime with LXC, and a custom diff-based database ([Patch-DB](https://github.com/Start9Labs/patch-db)) for reactive state synchronization.
 
-To pursue this option, follow one of our [DIY guides](https://start9.com/latest/diy).
+Services run in isolated LXC containers, packaged as [S9PKs](https://github.com/Start9Labs/start-os/blob/master/core/s9pk-structure.md) — a signed, merkle-archived format that supports partial downloads and cryptographic verification.
 
-## ❤️ Contributing
-There are multiple ways to contribute: work directly on StartOS, package a service for the marketplace, or help with documentation and guides. To learn more about contributing, see [here](https://start9.com/contribute/).
+## What can you do with it?
 
-To report security issues, please email our security team - security@start9.com.
+StartOS lets you self-host services that would otherwise depend on third-party cloud providers — giving you full ownership of your data and infrastructure.
 
-## 🌎 Marketplace
-There are dozens of services available for StartOS, and new ones are being added all the time. Check out the full list of available services [here](https://marketplace.start9.com/marketplace). To read more about the Marketplace ecosystem, check out this [blog post](https://blog.start9.com/start9-marketplace-strategy/)
+Browse available services on the [Start9 Marketplace](https://marketplace.start9.com/), including:
 
-## 🖥️ User Interface Screenshots
+- **Bitcoin & Lightning** — Run a full Bitcoin node, Lightning node, BTCPay Server, and other payment infrastructure
+- **Communication** — Self-host Matrix, SimpleX, or other messaging platforms
+- **Cloud Storage** — Run Nextcloud, Vaultwarden, and other productivity tools
 
-<p align="center">
-<img src="assets/registry.png" alt="StartOS Marketplace" width="49%">
-<img src="assets/community.png" alt="StartOS Community Registry" width="49%">
-<img src="assets/c-lightning.png" alt="StartOS NextCloud Service" width="49%">
-<img src="assets/btcpay.png" alt="StartOS BTCPay Service" width="49%">
-<img src="assets/nextcloud.png" alt="StartOS System Settings" width="49%">
-<img src="assets/system.png" alt="StartOS System Settings" width="49%">
-<img src="assets/welcome.png" alt="StartOS System Settings" width="49%">
-<img src="assets/logs.png" alt="StartOS System Settings" width="49%">
-</p>
+Services are added by the community. If a service you want isn't available, you can [package it yourself](https://github.com/Start9Labs/ai-service-packaging/).
+
+## Getting StartOS
+
+### Buy a Start9 server
+
+The easiest path. [Buy a server](https://store.start9.com) from Start9 and plug it in.
+
+### Build your own
+
+Follow the [install guide](https://docs.start9.com/start-os/installing.html) to install StartOS on your own hardware. . Reasons to go this route:
+
+1. You already have compatible hardware
+2. You want to save on shipping costs
+3. You prefer not to share your physical address
+4. You enjoy building things
+
+### Build from source
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for environment setup, build instructions, and development workflow.
+
+## Contributing
+
+There are multiple ways to contribute: work directly on StartOS, package a service for the marketplace, or help with documentation and guides. See [CONTRIBUTING.md](CONTRIBUTING.md) or visit [start9.com/contribute](https://start9.com/contribute/).
+
+To report security issues, email [security@start9.com](mailto:security@start9.com).

apt/start9.list

@@ -0,0 +1 @@
+deb [arch=amd64,arm64,riscv64 signed-by=/usr/share/keyrings/start9.gpg] https://start9-debs.nyc3.cdn.digitaloceanspaces.com stable main

build-cargo-dep.sh

@@ -1,25 +0,0 @@
-#!/bin/bash
-
-set -e
-shopt -s expand_aliases
-
-if [ "$0" != "./build-cargo-dep.sh" ]; then
-	>&2 echo "Must be run from start-os directory"
-	exit 1
-fi
-
-USE_TTY=
-if tty -s; then
-	USE_TTY="-it"
-fi
-
-if [ -z "$ARCH" ]; then
-	ARCH=$(uname -m)
-fi
-
-mkdir -p cargo-deps
-alias 'rust-arm64-builder'='docker run $USE_TTY --rm -v "$HOME/.cargo/registry":/usr/local/cargo/registry -v "$(pwd)"/cargo-deps:/home/rust/src -P start9/rust-arm-cross:aarch64'
-
-rust-arm64-builder cargo install "$1" --target-dir /home/rust/src --target=$ARCH-unknown-linux-gnu
-sudo chown -R $USER cargo-deps
-sudo chown -R $USER ~/.cargo

build/.gitignore

@@ -1,2 +1,2 @@
-lib/depends
-lib/conflicts
+/lib/depends
+/lib/conflicts

build/README.md

@@ -1,107 +0,0 @@
-# Building StartOS
-
-⚠️ The commands given assume a Debian or Ubuntu-based environment. _Building in
-a VM is NOT yet supported_ ⚠️
-
-## Prerequisites
-
-1. Install dependencies
-
-- Avahi
-  - `sudo apt install -y avahi-daemon`
-  - Installed by default on most Debian systems - https://avahi.org
-- Build Essentials (needed to run `make`)
-  - `sudo apt install -y build-essential`
-- Docker
-  - `curl -fsSL https://get.docker.com | sh`
-  - https://docs.docker.com/get-docker
-  - Add your user to the docker group: `sudo usermod -a -G docker $USER`
-  - Reload user environment `exec sudo su -l $USER`
-- Prepare Docker environment
-  - Setup buildx (https://docs.docker.com/buildx/working-with-buildx/)
-  - Create a builder: `docker buildx create --use`
-  - Add multi-arch build ability:
-    `docker run --rm --privileged linuxkit/binfmt:v0.8`
-- Node Version 12+
-  - snap: `sudo snap install node`
-  - [nvm](https://github.com/nvm-sh/nvm#installing-and-updating):
-    `nvm install --lts`
-  - https://nodejs.org/en/docs
-- NPM Version 7+
-  - apt: `sudo apt install -y npm`
-  - [nvm](https://github.com/nvm-sh/nvm#installing-and-updating):
-    `nvm install --lts`
-  - https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
-- jq
-  - `sudo apt install -y jq`
-  - https://stedolan.github.io/jq
-- yq
-  - snap: `sudo snap install yq`
-  - binaries: https://github.com/mikefarah/yq/releases/
-  - https://mikefarah.gitbook.io/yq
-
-2. Clone the latest repo with required submodules
-   > :information_source: You chan check latest available version
-   > [here](https://github.com/Start9Labs/start-os/releases)
-   ```
-   git clone --recursive https://github.com/Start9Labs/start-os.git --branch latest
-   ```
-
-## Build Raspberry Pi Image
-
-```
-cd start-os
-make embassyos-raspi.img ARCH=aarch64
-```
-
-## Flash
-
-Flash the resulting `embassyos-raspi.img` to your SD Card
-
-We recommend [Balena Etcher](https://www.balena.io/etcher/)
-
-## Setup
-
-Visit http://start.local from any web browser - We recommend
-[Firefox](https://www.mozilla.org/firefox/browsers)
-
-Enter your product key. This is generated during the build process and can be
-found in `product_key.txt`, located in the root directory.
-
-## Troubleshooting
-
-1. I just flashed my SD card, fired up StartOS, bootup sounds and all, but my
-   browser is saying "Unable to connect" with start.local.
-
-- Try doing a hard refresh on your browser, or opening the url in a
-  private/incognito window. If you've ran an instance of StartOS before,
-  sometimes you can have a stale cache that will block you from navigating to
-  the page.
-
-2. Flashing the image isn't working with balenaEtcher. I'm getting
-   `Cannot read property 'message' of null` when I try.
-
-- The latest versions of Balena may not flash properly. This version here:
-  https://github.com/balena-io/etcher/releases/tag/v1.5.122 should work
-  properly.
-
-3. Startup isn't working properly and I'm curious as to why. How can I view logs
-   regarding startup for debugging?
-
-- Find the IP of your device
-- Run `nc <ip> 8080` and it will print the logs
-
-4. I need to ssh into my server to fix something, but I cannot get to the
-   console to add ssh keys normally.
-
-- During the Build step, instead of running just
-  `make embassyos-raspi.img ARCH=aarch64` run
-  `ENVIRONMENT=dev make embassyos-raspi.img ARCH=aarch64`. Flash like normal,
-  and insert into your server. Boot up StartOS, then on another computer on
-  the same network, ssh into the the server with the username `start9` password
-  `embassy`.
-
-4. I need to reset my password, how can I do that?
-
-- You will need to reflash your device. Select "Use Existing Drive" once you are
-  in setup, and it will prompt you to set a new password.

build/RELEASE.md

@@ -1,76 +0,0 @@
-# Release Process
-
-## `embassyos_0.3.x-1_amd64.deb`
-
-- Description: debian package for x86_64 - intended to be installed on pureos
-- Destination: GitHub Release Tag
-- Requires: N/A
-- Build steps:
-  - Clone `https://github.com/Start9Labs/embassy-os-deb` at `master`
-  - Run `make TAG=master` from that folder
-- Artifact: `./embassyos_0.3.x-1_amd64.deb`
-
-## `eos-<version>-<git hash>-<date>_amd64.iso`
-
-- Description: live usb image for x86_64
-- Destination: GitHub Release Tag
-- Requires: `embassyos_0.3.x-1_amd64.deb`
-- Build steps:
-  - Clone `https://github.com/Start9Labs/eos-image-recipes` at `master`
-  - Copy `embassyos_0.3.x-1_amd64.deb` to
-    `overlays/vendor/root/embassyos_0.3.x-1_amd64.deb`
-  - Run `./run-local-build.sh byzantium` from that folder
-- Artifact: `./results/eos-<version>-<git hash>-<date>_amd64.iso`
-
-## `eos.x86_64.squashfs`
-
-- Description: compressed embassyOS x86_64 filesystem image
-- Destination: GitHub Release Tag, Registry @
-  `resources/eos/<version>/eos.x86_64.squashfs`
-- Requires: `eos-<version>-<git hash>-<date>_amd64.iso`
-- Build steps:
-  - From `https://github.com/Start9Labs/eos-image-recipes` at `master`
-  - `./extract-squashfs.sh results/eos-<version>-<git hash>-<date>_amd64.iso`
-- Artifact: `./results/eos.x86_64.squashfs`
-
-## `eos.raspberrypi.squashfs`
-
-- Description: compressed embassyOS raspberrypi filesystem image
-- Destination: GitHub Release Tag, Registry @
-  `resources/eos/<version>/eos.raspberrypi.squashfs`
-- Requires: N/A
-- Build steps:
-  - Clone `https://github.com/Start9Labs/embassy-os` at `master`
-  - `make embassyos-raspi.img`
-  - flash `embassyos-raspi.img` to raspberry pi
-  - boot raspberry pi with ethernet
-  - wait for chime
-    - you can watch logs using `nc <ip> 8080`
-  - unplug raspberry pi, put sd card back in build machine
-  - `./build/raspberry-pi/rip-image.sh`
-- Artifact: `./eos.raspberrypi.squashfs`
-
-## `lite-upgrade.img`
-
-- Description: update image for users coming from 0.3.2.1 and before
-- Destination: Registry @ `resources/eos/<version>/eos.img`
-- Requires: `eos.raspberrypi.squashfs`
-- Build steps:
-  - From `https://github.com/Start9Labs/embassy-os` at `master`
-  - `make lite-upgrade.img`
-- Artifact `./lite-upgrade.img`
-
-## `eos-<version>-<git hash>-<date>_raspberrypi.tar.gz`
-
-- Description: pre-initialized raspberrypi image
-- Destination: GitHub Release Tag (as tar.gz)
-- Requires: `eos.raspberrypi.squashfs`
-- Build steps:
-  - From `https://github.com/Start9Labs/embassy-os` at `master`
-  - `make eos_raspberrypi.img`
-  - `tar --format=posix -cS -f- eos-<version>-<git hash>-<date>_raspberrypi.img | gzip > eos-<version>-<git hash>-<date>_raspberrypi.tar.gz`
-- Artifact `./eos-<version>-<git hash>-<date>_raspberrypi.tar.gz`
-
-## `embassy-sdk`
-
-- Build and deploy to all registries

build/apt/publish-deb.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+#
+# Publish .deb files to an S3-hosted apt repository.
+#
+# Usage: publish-deb.sh <deb-file-or-directory> [<deb-file-or-directory> ...]
+#
+# Environment variables:
+#   GPG_PRIVATE_KEY  - Armored GPG private key (imported if set)
+#   GPG_KEY_ID       - GPG key ID for signing
+#   S3_ACCESS_KEY    - S3 access key
+#   S3_SECRET_KEY    - S3 secret key
+#   S3_ENDPOINT      - S3 endpoint (default: https://nyc3.digitaloceanspaces.com)
+#   S3_BUCKET        - S3 bucket name (default: start9-debs)
+#   SUITE            - Apt suite name (default: stable)
+#   COMPONENT        - Apt component name (default: main)
+
+set -e
+
+if [ $# -eq 0 ]; then
+    echo "Usage: $0 <deb-file-or-directory> [...]" >&2
+    exit 1
+fi
+
+BUCKET="${S3_BUCKET:-start9-debs}"
+ENDPOINT="${S3_ENDPOINT:-https://nyc3.digitaloceanspaces.com}"
+SUITE="${SUITE:-stable}"
+COMPONENT="${COMPONENT:-main}"
+REPO_DIR="$(mktemp -d)"
+
+cleanup() {
+    rm -rf "$REPO_DIR"
+}
+trap cleanup EXIT
+
+# Import GPG key if provided
+if [ -n "$GPG_PRIVATE_KEY" ]; then
+    echo "$GPG_PRIVATE_KEY" | gpg --batch --import 2>/dev/null
+fi
+
+# Configure s3cmd
+if [ -n "$S3_ACCESS_KEY" ] && [ -n "$S3_SECRET_KEY" ]; then
+    S3CMD_CONFIG="$(mktemp)"
+    cat > "$S3CMD_CONFIG" <<EOF
+[default]
+access_key = ${S3_ACCESS_KEY}
+secret_key = ${S3_SECRET_KEY}
+host_base = $(echo "$ENDPOINT" | sed 's|https://||')
+host_bucket = %(bucket)s.$(echo "$ENDPOINT" | sed 's|https://||')
+use_https = True
+EOF
+    s3() {
+        s3cmd -c "$S3CMD_CONFIG" "$@"
+    }
+else
+    # Fall back to default ~/.s3cfg
+    S3CMD_CONFIG=""
+    s3() {
+        s3cmd "$@"
+    }
+fi
+
+# Sync existing repo from S3
+echo "Syncing existing repo from s3://${BUCKET}/ ..."
+s3 sync --no-mime-magic "s3://${BUCKET}/" "$REPO_DIR/" 2>/dev/null || true
+
+# Collect all .deb files from arguments
+DEB_FILES=()
+for arg in "$@"; do
+    if [ -d "$arg" ]; then
+        while IFS= read -r -d '' f; do
+            DEB_FILES+=("$f")
+        done < <(find "$arg" -name '*.deb' -print0)
+    elif [ -f "$arg" ]; then
+        DEB_FILES+=("$arg")
+    else
+        echo "Warning: $arg is not a file or directory, skipping" >&2
+    fi
+done
+
+if [ ${#DEB_FILES[@]} -eq 0 ]; then
+    echo "No .deb files found" >&2
+    exit 1
+fi
+
+# Copy each deb to the pool, renaming to standard format
+for deb in "${DEB_FILES[@]}"; do
+    PKG_NAME="$(dpkg-deb --field "$deb" Package)"
+    POOL_DIR="$REPO_DIR/pool/${COMPONENT}/${PKG_NAME:0:1}/${PKG_NAME}"
+    mkdir -p "$POOL_DIR"
+    cp "$deb" "$POOL_DIR/"
+    dpkg-name -o "$POOL_DIR/$(basename "$deb")" 2>/dev/null || true
+    echo "Added: $(basename "$deb") -> pool/${COMPONENT}/${PKG_NAME:0:1}/${PKG_NAME}/"
+done
+
+# Generate Packages indices for each architecture
+for arch in amd64 arm64 riscv64; do
+    BINARY_DIR="$REPO_DIR/dists/${SUITE}/${COMPONENT}/binary-${arch}"
+    mkdir -p "$BINARY_DIR"
+    (
+        cd "$REPO_DIR"
+        dpkg-scanpackages --arch "$arch" pool/ > "$BINARY_DIR/Packages"
+        gzip -k -f "$BINARY_DIR/Packages"
+    )
+    echo "Generated Packages index for ${arch}"
+done
+
+# Generate Release file
+(
+    cd "$REPO_DIR/dists/${SUITE}"
+    apt-ftparchive release \
+        -o "APT::FTPArchive::Release::Origin=Start9" \
+        -o "APT::FTPArchive::Release::Label=Start9" \
+        -o "APT::FTPArchive::Release::Suite=${SUITE}" \
+        -o "APT::FTPArchive::Release::Codename=${SUITE}" \
+        -o "APT::FTPArchive::Release::Architectures=amd64 arm64 riscv64" \
+        -o "APT::FTPArchive::Release::Components=${COMPONENT}" \
+        . > Release
+)
+echo "Generated Release file"
+
+# Sign if GPG key is available
+if [ -n "$GPG_KEY_ID" ]; then
+    (
+        cd "$REPO_DIR/dists/${SUITE}"
+        gpg --default-key "$GPG_KEY_ID" --batch --yes --detach-sign -o Release.gpg Release
+        gpg --default-key "$GPG_KEY_ID" --batch --yes --clearsign -o InRelease Release
+    )
+    echo "Signed Release file with key ${GPG_KEY_ID}"
+else
+    echo "Warning: GPG_KEY_ID not set, Release file is unsigned" >&2
+fi
+
+# Upload to S3
+echo "Uploading to s3://${BUCKET}/ ..."
+s3 sync --acl-public --no-mime-magic "$REPO_DIR/" "s3://${BUCKET}/"
+
+[ -n "$S3CMD_CONFIG" ] && rm -f "$S3CMD_CONFIG"
+echo "Done."

build/build-cargo-dep.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+
+set -e
+shopt -s expand_aliases
+
+if [ -z "$ARCH" ]; then
+	ARCH=$(uname -m)
+fi
+
+RUST_ARCH="$ARCH"
+if [ "$ARCH" = "riscv64" ]; then
+  RUST_ARCH="riscv64gc"
+fi
+
+mkdir -p target
+
+source core/build/builder-alias.sh
+
+RUSTFLAGS="-C target-feature=+crt-static"
+
+rust-zig-builder cargo-zigbuild install $* --target-dir /workdir/target/ --target=$RUST_ARCH-unknown-linux-musl
+if [ "$(ls -nd "target/$RUST_ARCH-unknown-linux-musl/release/${!#}" | awk '{ print $3 }')" != "$UID" ]; then
+  rust-zig-builder sh -c "chown -R $UID:$UID target && chown -R $UID:$UID  /usr/local/cargo"
+fi

build/download-firmware.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+set -e
+
+PLATFORM=$1
+
+if [ -z "$PLATFORM" ]; then
+	>&2 echo "usage: $0 <PLATFORM>"
+	exit 1
+fi
+
+rm -rf ./lib/firmware/$PLATFORM
+mkdir -p ./lib/firmware/$PLATFORM
+
+cd ./lib/firmware/$PLATFORM
+
+firmwares=()
+while IFS= read -r line; do firmwares+=("$line"); done < <(jq -c ".[] | select(.platform[] | contains(\"$PLATFORM\"))" ../../firmware.json)
+for firmware in "${firmwares[@]}"; do
+	if [ -n "$firmware" ]; then
+		id=$(echo "$firmware" | jq --raw-output '.id')
+		url=$(echo "$firmware" | jq --raw-output '.url')
+		shasum=$(echo "$firmware" | jq --raw-output '.shasum')
+		curl --fail -L -o "${id}.rom.gz" "$url"
+		echo "$shasum ${id}.rom.gz" | sha256sum -c
+	fi
+done

build/dpkg-deps/depends

@@ -1,49 +1,61 @@
 avahi-daemon
 avahi-utils
+b3sum
 bash-completion
 beep
+binfmt-support
 bmon
 btrfs-progs
 ca-certificates
 cifs-utils
+conntrack
 cryptsetup
 curl
 dmidecode
+dnsutils
 dosfstools
 e2fsprogs
 ecryptfs-utils
+equivs
 exfatprogs
 flashrom
+fuse3
 grub-common
+grub-efi
 htop
 httpdirfs
 iotop
+iptables
 iw
 jq
-libavahi-client3
 libyajl2
 linux-cpupower
 lm-sensors
 lshw
 lvm2
+lxc
 magic-wormhole
 man-db
 ncdu
 net-tools
 network-manager
+nfs-common
 nvme-cli
 nyx
 openssh-server
 podman
-postgresql
 psmisc
 qemu-guest-agent
+qemu-user-static
+rfkill
 rsync
 samba-common-bin
 smartmontools
 socat
 sqlite3
 squashfs-tools
+squashfs-tools-ng
+ssl-cert
 sudo
 systemd
 systemd-resolved
@@ -52,4 +64,5 @@ systemd-timesyncd
 tor
 util-linux
 vim
+wireguard-tools
 wireless-tools

build/dpkg-deps/dev.depends

@@ -0,0 +1 @@
++ nmap

build/dpkg-deps/docker.depends

@@ -1,5 +0,0 @@
-+ containerd.io
-+ docker-ce
-+ docker-ce-cli
-+ docker-compose-plugin
-- podman

build/dpkg-deps/generate.sh

@@ -5,11 +5,22 @@ set -e
 cd "$(dirname "${BASH_SOURCE[0]}")"
 
 IFS="-" read -ra FEATURES <<< "$ENVIRONMENT"
+FEATURES+=("${ARCH}")
+if [ "$ARCH" != "$PLATFORM" ]; then
+    FEATURES+=("${PLATFORM}")
+fi
+if [[ "$PLATFORM" =~ -nonfree$ ]]; then
+    FEATURES+=("nonfree")
+fi
+if [[ "$PLATFORM" =~ -nvidia$ ]]; then
+    FEATURES+=("nonfree")
+    FEATURES+=("nvidia")
+fi
 
 feature_file_checker='
 /^#/ { next }
-/^\+ [a-z0-9]+$/ { next }
-/^- [a-z0-9]+$/ { next }
+/^\+ [a-z0-9.-]+$/ { next }
+/^- [a-z0-9.-]+$/ { next }
 { exit 1 }
 '
 
@@ -30,8 +41,8 @@ for type in conflicts depends; do
         for feature in ${FEATURES[@]}; do
             file="$feature.$type"
             if [ -f $file ]; then
-                if grep "^- $pkg$" $file; then
-                    SKIP=1
+                if grep "^- $pkg$" $file > /dev/null; then
+                    SKIP=yes
                 fi
             fi
         done

build/dpkg-deps/nonfree.depends

@@ -0,0 +1,7 @@
++ firmware-amd-graphics
++ firmware-atheros
++ firmware-brcm80211
++ firmware-iwlwifi
++ firmware-libertas
++ firmware-misc-nonfree
++ firmware-realtek

build/dpkg-deps/nvidia.depends

@@ -0,0 +1 @@
++ nvidia-container-toolkit

build/dpkg-deps/raspberrypi.depends

@@ -0,0 +1,10 @@
+- grub-efi
++ parted
++ raspberrypi-net-mods
++ raspberrypi-sys-mods
++ raspi-config
++ raspi-firmware
++ raspi-utils
++ rpi-eeprom
++ rpi-update
++ rpi.gpio-common

build/dpkg-deps/unstable.depends

@@ -1,2 +1,3 @@
 + gdb
-+ heaptrack
++ heaptrack
++ linux-perf

build/dpkg-deps/x86_64.depends

@@ -0,0 +1 @@
++ grub-pc-bin

build/env/basename.sh

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+PROJECT=${PROJECT:-"startos"}
+
 cd "$(dirname "${BASH_SOURCE[0]}")"
 
 PLATFORM="$(if [ -f ./PLATFORM.txt ]; then cat ./PLATFORM.txt; else echo unknown; fi)"
@@ -16,4 +18,4 @@ if [ -n "$STARTOS_ENV" ]; then
   VERSION_FULL="$VERSION_FULL~${STARTOS_ENV}"
 fi
 
-echo -n "startos-${VERSION_FULL}_${PLATFORM}"
+echo -n "${PROJECT}-${VERSION_FULL}_${PLATFORM}"

build/env/check-environment.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+if ! [ -f ./ENVIRONMENT.txt ] || [ "$(cat ./ENVIRONMENT.txt)" != "$ENVIRONMENT" ]; then
+    >&2 echo "Updating ENVIRONMENT.txt to \"$ENVIRONMENT\""
+    echo -n "$ENVIRONMENT" > ./ENVIRONMENT.txt
+fi
+
+echo -n ./build/env/ENVIRONMENT.txt

build/env/check-git-hash.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+if [ "$GIT_BRANCH_AS_HASH" != 1 ]; then
+    GIT_HASH="$(git rev-parse HEAD)$(if ! git diff-index --quiet HEAD --; then echo '-modified'; fi)"
+else
+    GIT_HASH="@$(git rev-parse --abbrev-ref HEAD)"
+fi
+
+if ! [ -f ./GIT_HASH.txt ] || [ "$(cat ./GIT_HASH.txt)" != "$GIT_HASH" ]; then
+    >&2 echo Git hash changed from "$([ -f ./GIT_HASH.txt ] && cat ./GIT_HASH.txt)" to "$GIT_HASH"
+    echo -n "$GIT_HASH" > ./GIT_HASH.txt
+fi
+
+echo -n ./build/env/GIT_HASH.txt

build/env/check-platform.sh

@@ -1,8 +1,10 @@
 #!/bin/bash
 
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
 if ! [ -f ./PLATFORM.txt ] || [ "$(cat ./PLATFORM.txt)" != "$PLATFORM" ] && [ -n "$PLATFORM" ]; then
     >&2 echo "Updating PLATFORM.txt to \"$PLATFORM\""
     echo -n "$PLATFORM" > ./PLATFORM.txt
 fi
 
-echo -n ./PLATFORM.txt
+echo -n ./build/env/PLATFORM.txt

build/env/check-version.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+FE_VERSION="$(cat ../../web/package.json | grep '"version"' | sed 's/[ \t]*"version":[ \t]*"\([^"]*\)",/\1/')"
+
+# TODO: Validate other version sources - backend/Cargo.toml, backend/src/version/mod.rs
+
+VERSION=$FE_VERSION
+
+if ! [ -f ./VERSION.txt ] || [ "$(cat ./VERSION.txt)" != "$VERSION" ]; then
+    echo -n "$VERSION" > ./VERSION.txt
+fi
+
+echo -n ./build/env/VERSION.txt

build/image-recipe/Dockerfile

@@ -0,0 +1,35 @@
+ARG SUITE=trixie
+
+FROM debian:${SUITE}
+
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && \
+    apt-get install -yq \
+    live-build \
+    procps \
+    binfmt-support \
+    qemu-utils \
+    qemu-user-static \
+    xorriso \
+    isolinux \
+    ca-certificates \
+    curl \
+    wget \
+    gpg \
+    git \
+    fdisk \
+    dosfstools \
+    e2fsprogs \
+    squashfs-tools \
+    rsync \
+    b3sum \
+    dpkg-dev
+
+
+COPY binary_grub-efi.patch /root/binary_grub-efi.patch
+RUN patch /usr/lib/live/build/binary_grub-efi < /root/binary_grub-efi.patch && rm /root/binary_grub-efi.patch
+
+RUN echo 'retry_connrefused = on' > /etc/wgetrc && \
+    echo 'tries = 100' >> /etc/wgetrc
+
+WORKDIR /root

build/image-recipe/README.md

@@ -0,0 +1,19 @@
+# StartOS Image Recipes
+
+Code and `debos` recipes that are used to create the StartOS live and installer
+images.
+
+If you want to build a local image in the exact same environment used to build
+official StartOS images, you can use the `run-local-build.sh` helper script:
+
+```bash
+# Prerequisites
+sudo apt-get install -y debspawn binfmt-support
+sudo mkdir -p /etc/debspawn/ && echo "AllowUnsafePermissions=true" | sudo tee /etc/debspawn/global.toml
+
+# Build image
+./run-local-build.sh
+```
+
+In order for the build to work properly, you will need debspawn >= 0.5.1, the
+build may fail with prior versions.

build/image-recipe/binary_grub-efi.patch

@@ -0,0 +1,47 @@
+--- /usr/lib/live/build/binary_grub-efi	2024-05-25 05:22:52.000000000 -0600
++++ binary_grub-efi	2025-10-16 13:04:32.338740922 -0600
+@@ -54,6 +54,8 @@
+ 	armhf)
+ 		Check_package chroot /usr/lib/grub/arm-efi/configfile.mod grub-efi-arm-bin
+ 		;;
++	riscv64)
++		Check_package chroot /usr/lib/grub/riscv64-efi/configfile.mod grub-efi-riscv64-bin
+ esac
+ Check_package chroot /usr/bin/grub-mkimage grub-common
+ Check_package chroot /usr/bin/mcopy mtools
+@@ -136,7 +138,7 @@
+ esac
+ 
+ # Cleanup files that we generate
+-rm -rf binary/boot/efi.img binary/boot/grub/i386-efi/ binary/boot/grub/x86_64-efi binary/boot/grub/arm64-efi binary/boot/grub/arm-efi
++rm -rf binary/boot/efi.img binary/boot/grub/i386-efi/ binary/boot/grub/x86_64-efi binary/boot/grub/arm64-efi binary/boot/grub/arm-efi binary/boot/grub/riscv64-efi
+ 
+ # This is workaround till both efi-image and grub-cpmodules are put into a binary package
+ case "${LB_BUILD_WITH_CHROOT}" in
+@@ -243,6 +245,10 @@
+ 		gen_efi_boot_img "arm-efi" "arm" "debian-live/arm"
+ 		PATH="\${PRE_EFI_IMAGE_PATH}"
+ 		;;
++	riscv64)
++		gen_efi_boot_img "riscv64-efi" "riscv64" "debian-live/riscv64"
++		PATH="\${PRE_EFI_IMAGE_PATH}"
++		;;
+ esac
+ 
+ 
+@@ -324,6 +330,7 @@
+ rm -f chroot/grub-efi-temp/bootnetx64.efi
+ rm -f chroot/grub-efi-temp/bootnetaa64.efi
+ rm -f chroot/grub-efi-temp/bootnetarm.efi
++rm -f chroot/grub-efi-temp/bootnetriscv64.efi
+ 
+ mkdir -p binary
+ cp -a chroot/grub-efi-temp/* binary/
+@@ -331,6 +338,7 @@
+ rm -rf chroot/grub-efi-temp-i386-efi
+ rm -rf chroot/grub-efi-temp-arm64-efi
+ rm -rf chroot/grub-efi-temp-arm-efi
++rm -rf chroot/grub-efi-temp-riscv64-efi
+ rm -rf chroot/grub-efi-temp-cfg
+ rm -rf chroot/grub-efi-temp
+ 

build/image-recipe/build.sh

@@ -0,0 +1,456 @@
+#!/bin/bash
+set -e
+
+MAX_IMG_LEN=$((4 * 1024 * 1024 * 1024)) # 4GB
+
+echo "==== StartOS Image Build ===="
+
+echo "Building for architecture: $IB_TARGET_ARCH"
+
+SOURCE_DIR="$(realpath $(dirname "${BASH_SOURCE[0]}"))"
+
+base_dir="$(pwd	-P)"
+prep_results_dir="$base_dir/images-prep"
+RESULTS_DIR="$base_dir/results"
+echo "Saving results in: $RESULTS_DIR"
+
+DEB_PATH="$base_dir/$1"
+
+VERSION="$(dpkg-deb --fsys-tarfile $DEB_PATH | tar --to-stdout -xvf - ./usr/lib/startos/VERSION.txt)"
+GIT_HASH="$(dpkg-deb --fsys-tarfile $DEB_PATH | tar --to-stdout -xvf - ./usr/lib/startos/GIT_HASH.txt)"
+if [[ "$GIT_HASH" =~ ^@ ]]; then
+  GIT_HASH="unknown"
+else
+  GIT_HASH="$(echo -n "$GIT_HASH" |  head -c 7)"
+fi
+IB_OS_ENV="$(dpkg-deb --fsys-tarfile $DEB_PATH | tar --to-stdout -xvf - ./usr/lib/startos/ENVIRONMENT.txt)"
+IB_TARGET_PLATFORM="$(dpkg-deb --fsys-tarfile $DEB_PATH | tar --to-stdout -xvf - ./usr/lib/startos/PLATFORM.txt)"
+
+VERSION_FULL="${VERSION}-${GIT_HASH}"
+if [ -n "$IB_OS_ENV" ]; then
+  VERSION_FULL="$VERSION_FULL~${IB_OS_ENV}"
+fi
+
+IMAGE_BASENAME=startos-${VERSION_FULL}_${IB_TARGET_PLATFORM}
+
+BOOTLOADERS=grub-efi
+if [ "$IB_TARGET_PLATFORM" = "x86_64" ] || [ "$IB_TARGET_PLATFORM" = "x86_64-nonfree" ] || [ "$IB_TARGET_PLATFORM" = "x86_64-nvidia" ]; then
+	IB_TARGET_ARCH=amd64
+	QEMU_ARCH=x86_64
+	BOOTLOADERS=grub-efi,syslinux
+elif [ "$IB_TARGET_PLATFORM" = "aarch64" ] || [ "$IB_TARGET_PLATFORM" = "aarch64-nonfree" ] || [ "$IB_TARGET_PLATFORM" = "aarch64-nvidia" ] || [ "$IB_TARGET_PLATFORM" = "raspberrypi" ]  || [ "$IB_TARGET_PLATFORM" = "rockchip64" ]; then
+	IB_TARGET_ARCH=arm64
+	QEMU_ARCH=aarch64
+elif [ "$IB_TARGET_PLATFORM" = "riscv64" ] || [ "$IB_TARGET_PLATFORM" = "riscv64-nonfree" ]; then
+	IB_TARGET_ARCH=riscv64
+	QEMU_ARCH=riscv64
+else
+	IB_TARGET_ARCH="$IB_TARGET_PLATFORM"
+	QEMU_ARCH="$IB_TARGET_PLATFORM"
+fi
+
+QEMU_ARGS=()
+if [ "$QEMU_ARCH" != $(uname -m) ]; then
+	QEMU_ARGS+=(--bootstrap-qemu-arch ${IB_TARGET_ARCH})
+	QEMU_ARGS+=(--bootstrap-qemu-static /usr/bin/qemu-${QEMU_ARCH}-static)
+fi
+
+mkdir -p $prep_results_dir
+
+cd $prep_results_dir
+
+NON_FREE=
+if [[ "${IB_TARGET_PLATFORM}" =~ -nonfree$ ]] || [[ "${IB_TARGET_PLATFORM}" =~ -nvidia$ ]] || [ "${IB_TARGET_PLATFORM}" = "raspberrypi" ]; then
+	NON_FREE=1
+fi
+NVIDIA=
+if [[ "${IB_TARGET_PLATFORM}" =~ -nvidia$ ]]; then
+	NVIDIA=1
+fi
+IMAGE_TYPE=iso
+if [ "${IB_TARGET_PLATFORM}" = "raspberrypi" ] || [ "${IB_TARGET_PLATFORM}" = "rockchip64" ]; then
+	IMAGE_TYPE=img
+fi
+
+ARCHIVE_AREAS="main contrib"
+if [ "$NON_FREE" = 1 ]; then
+	if [ "$IB_SUITE" = "bullseye" ]; then
+		ARCHIVE_AREAS="$ARCHIVE_AREAS non-free"
+	else
+		ARCHIVE_AREAS="$ARCHIVE_AREAS non-free non-free-firmware"
+	fi
+fi
+
+PLATFORM_CONFIG_EXTRAS=()
+if [ "${IB_TARGET_PLATFORM}" = "raspberrypi" ]; then
+	PLATFORM_CONFIG_EXTRAS+=( --firmware-binary false )
+	PLATFORM_CONFIG_EXTRAS+=( --firmware-chroot false )
+	RPI_KERNEL_VERSION=6.12.47+rpt
+	PLATFORM_CONFIG_EXTRAS+=( --linux-packages linux-image-$RPI_KERNEL_VERSION )
+	PLATFORM_CONFIG_EXTRAS+=( --linux-flavours "rpi-v8 rpi-2712" )
+elif [ "${IB_TARGET_PLATFORM}" = "rockchip64" ]; then
+	PLATFORM_CONFIG_EXTRAS+=( --linux-flavours rockchip64 )
+elif [ "${IB_TARGET_ARCH}" = "riscv64" ]; then
+	PLATFORM_CONFIG_EXTRAS+=( --uefi-secure-boot=disable )
+fi
+
+
+cat > /etc/wgetrc << EOF
+retry_connrefused = on
+tries = 100
+EOF
+lb config \
+	--iso-application "StartOS v${VERSION_FULL} ${IB_TARGET_ARCH}" \
+	--iso-volume "StartOS v${VERSION} ${IB_TARGET_ARCH}" \
+	--iso-preparer "START9 LABS; HTTPS://START9.COM" \
+	--iso-publisher "START9 LABS; HTTPS://START9.COM" \
+	--backports true \
+	--bootappend-live "boot=live noautologin console=tty0" \
+	--bootloaders $BOOTLOADERS \
+	--cache false \
+	--mirror-bootstrap "https://deb.debian.org/debian/" \
+	--mirror-chroot "https://deb.debian.org/debian/" \
+	--mirror-chroot-security "https://security.debian.org/debian-security" \
+	-d ${IB_SUITE} \
+	-a ${IB_TARGET_ARCH} \
+	${QEMU_ARGS[@]} \
+	--archive-areas "${ARCHIVE_AREAS}" \
+	${PLATFORM_CONFIG_EXTRAS[@]}
+
+# Overlays
+
+mkdir -p config/packages.chroot/
+cp $RESULTS_DIR/$IMAGE_BASENAME.deb config/packages.chroot/
+dpkg-name config/packages.chroot/*.deb
+
+mkdir -p config/includes.chroot/etc
+echo start > config/includes.chroot/etc/hostname
+cat > config/includes.chroot/etc/hosts << EOT
+127.0.0.1       localhost start
+::1             localhost start ip6-localhost ip6-loopback
+ff02::1         ip6-allnodes
+ff02::2         ip6-allrouters
+EOT
+
+if [ "${IB_TARGET_PLATFORM}" = "raspberrypi" ]; then
+	mkdir -p config/includes.chroot
+	git clone --depth=1 --branch=stable https://github.com/raspberrypi/rpi-firmware.git config/includes.chroot/boot
+	rm -rf config/includes.chroot/boot/.git config/includes.chroot/boot/modules
+	rsync -rLp $SOURCE_DIR/raspberrypi/squashfs/ config/includes.chroot/
+fi
+
+# Bootloaders
+
+rm -rf config/bootloaders
+cp -r /usr/share/live/build/bootloaders config/bootloaders
+
+cat > config/bootloaders/syslinux/syslinux.cfg << EOF
+include menu.cfg
+default vesamenu.c32
+prompt 0
+timeout 50
+EOF
+
+cat > config/bootloaders/isolinux/isolinux.cfg << EOF
+include menu.cfg
+default vesamenu.c32
+prompt 0
+timeout 50
+EOF
+
+# Extract splash.png from the deb package
+dpkg-deb --fsys-tarfile $DEB_PATH | tar --to-stdout -xf - ./usr/lib/startos/splash.png > /tmp/splash.png
+cp /tmp/splash.png config/bootloaders/syslinux_common/splash.png
+cp /tmp/splash.png config/bootloaders/isolinux/splash.png
+cp /tmp/splash.png config/bootloaders/grub-pc/splash.png
+rm /tmp/splash.png
+
+sed -i -e '2i set timeout=5' config/bootloaders/grub-pc/config.cfg
+
+# Archives
+
+mkdir -p config/archives
+
+if [ "${IB_TARGET_PLATFORM}" = "raspberrypi" ]; then
+	curl -fsSL https://archive.raspberrypi.com/debian/raspberrypi.gpg.key | gpg --dearmor -o config/archives/raspi.key
+	echo "deb [arch=${IB_TARGET_ARCH} signed-by=/etc/apt/trusted.gpg.d/raspi.key.gpg] https://archive.raspberrypi.com/debian/ ${IB_SUITE} main" > config/archives/raspi.list
+fi
+
+if [ "${IB_TARGET_PLATFORM}" = "rockchip64" ]; then
+	curl -fsSL https://apt.armbian.com/armbian.key | gpg --dearmor -o config/archives/armbian.key
+	echo "deb https://apt.armbian.com/ ${IB_SUITE} main" > config/archives/armbian.list
+fi
+
+if [ "$NVIDIA" = 1 ]; then
+	curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | gpg --dearmor -o config/archives/nvidia-container-toolkit.key
+	curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
+		| sed 's#deb https://#deb [signed-by=/etc/apt/trusted.gpg.d/nvidia-container-toolkit.key.gpg] https://#g' \
+		> config/archives/nvidia-container-toolkit.list
+fi
+
+cat > config/archives/backports.pref <<-EOF
+Package: linux-image-*
+Pin: release n=${IB_SUITE}-backports
+Pin-Priority: 500
+
+Package: linux-headers-*
+Pin: release n=${IB_SUITE}-backports
+Pin-Priority: 500
+
+Package: *nvidia*
+Pin: release n=${IB_SUITE}-backports
+Pin-Priority: 500
+EOF
+
+# Hooks
+
+cat > config/hooks/normal/9000-install-startos.hook.chroot << EOF
+#!/bin/bash
+
+set -e
+
+if [ "${NVIDIA}" = "1" ]; then
+    # install a specific NVIDIA driver version
+
+    # ---------------- configuration ----------------
+    NVIDIA_DRIVER_VERSION="\${NVIDIA_DRIVER_VERSION:-580.126.09}"
+
+    BASE_URL="https://download.nvidia.com/XFree86/Linux-${QEMU_ARCH}"
+
+    echo "[nvidia-hook] Using NVIDIA driver: \${NVIDIA_DRIVER_VERSION}" >&2
+
+    # ---------------- kernel version ----------------
+
+    # Determine target kernel version from newest /boot/vmlinuz-* in the chroot.
+    KVER="\$(
+        ls -1t /boot/vmlinuz-* 2>/dev/null \
+            | head -n1 \
+            | sed 's|.*/vmlinuz-||'
+    )"
+
+    if [ -z "\${KVER}" ]; then
+        echo "[nvidia-hook] ERROR: no /boot/vmlinuz-* found; cannot determine kernel version" >&2
+        exit 1
+    fi
+
+    echo "[nvidia-hook] Target kernel version: \${KVER}" >&2
+
+    # Ensure kernel headers are present
+	TEMP_APT_DEPS=(build-essential)
+    if [ ! -e "/lib/modules/\${KVER}/build" ]; then
+		TEMP_APT_DEPS+=(linux-headers-\${KVER})
+    fi
+
+    echo "[nvidia-hook] Installing build dependencies" >&2
+
+	/usr/lib/startos/scripts/install-equivs <<-EOF
+	Package: nvidia-depends
+	Version: \${NVIDIA_DRIVER_VERSION}
+	Section: unknown
+	Priority: optional
+	Depends: \${dep_list="\$(IFS=', '; echo "\${TEMP_APT_DEPS[*]}")"}
+	EOF
+
+    # ---------------- download and run installer ----------------
+
+    RUN_NAME="NVIDIA-Linux-${QEMU_ARCH}-\${NVIDIA_DRIVER_VERSION}.run"
+    RUN_PATH="/root/\${RUN_NAME}"
+    RUN_URL="\${BASE_URL}/\${NVIDIA_DRIVER_VERSION}/\${RUN_NAME}"
+
+    echo "[nvidia-hook] Downloading \${RUN_URL}" >&2
+    wget -O "\${RUN_PATH}" "\${RUN_URL}"
+    chmod +x "\${RUN_PATH}"
+
+    echo "[nvidia-hook] Running NVIDIA installer for kernel \${KVER}" >&2
+
+    if ! sh "\${RUN_PATH}" \
+        --silent \
+        --kernel-name="\${KVER}" \
+        --no-x-check \
+        --no-nouveau-check \
+        --no-runlevel-check; then
+		cat /var/log/nvidia-installer.log
+		exit 1
+	fi
+
+    # Rebuild module metadata
+    echo "[nvidia-hook] Running depmod for \${KVER}" >&2
+    depmod -a "\${KVER}"
+
+    echo "[nvidia-hook] NVIDIA \${NVIDIA_DRIVER_VERSION} installation complete for kernel \${KVER}" >&2
+
+    echo "[nvidia-hook] Removing build dependencies..." >&2
+	apt-get purge -y nvidia-depends
+	apt-get autoremove -y
+    echo "[nvidia-hook] Removed build dependencies." >&2
+fi
+
+cp /etc/resolv.conf /etc/resolv.conf.bak
+
+if [ "${IB_SUITE}" = trixie ] && [ "${IB_TARGET_ARCH}" != riscv64 ]; then
+    echo 'deb https://deb.debian.org/debian/ bookworm main' > /etc/apt/sources.list.d/bookworm.list
+    apt-get update
+    apt-get install -y postgresql-15
+    rm /etc/apt/sources.list.d/bookworm.list
+    apt-get update
+    systemctl mask postgresql
+fi
+
+if [ "${IB_TARGET_PLATFORM}" = "raspberrypi" ]; then
+    ln -sf /usr/bin/pi-beep /usr/local/bin/beep
+    KERNEL_VERSION=${RPI_KERNEL_VERSION} sh /boot/config.sh > /boot/config.txt
+    mkinitramfs -c gzip -o /boot/initrd.img-${RPI_KERNEL_VERSION}-rpi-v8 ${RPI_KERNEL_VERSION}-rpi-v8
+    mkinitramfs -c gzip -o /boot/initrd.img-${RPI_KERNEL_VERSION}-rpi-2712 ${RPI_KERNEL_VERSION}-rpi-2712
+fi
+
+useradd --shell /bin/bash -G startos -m start9
+echo start9:embassy | chpasswd
+usermod -aG sudo start9
+usermod -aG systemd-journal start9
+
+echo "start9 ALL=(ALL:ALL) NOPASSWD: ALL" | sudo tee "/etc/sudoers.d/010_start9-nopasswd"
+
+if [ "${IB_TARGET_PLATFORM}" != "raspberrypi" ]; then
+    /usr/lib/startos/scripts/enable-kiosk
+fi
+
+if ! [[ "${IB_OS_ENV}" =~ (^|-)dev($|-) ]]; then
+    passwd -l start9
+fi
+
+EOF
+
+SOURCE_DATE_EPOCH="${SOURCE_DATE_EPOCH:-$(date '+%s')}"
+
+if lb bootstrap; then
+	true
+else
+	EXIT=$?
+	cat ./chroot/debootstrap/debootstrap.log
+	exit $EXIT
+fi
+lb chroot
+lb installer
+lb binary_chroot
+lb chroot_prep install all mode-apt-install-binary mode-archives-chroot
+mv chroot/chroot/etc/resolv.conf.bak chroot/chroot/etc/resolv.conf
+lb binary_rootfs
+
+cp $prep_results_dir/binary/live/filesystem.squashfs $RESULTS_DIR/$IMAGE_BASENAME.squashfs
+
+if [ "${IMAGE_TYPE}" = iso ]; then
+
+	lb binary_manifest
+	lb binary_package-lists
+	lb binary_linux-image
+	lb binary_memtest
+	lb binary_grub-legacy
+	lb binary_grub-pc
+	lb binary_grub_cfg
+	lb binary_syslinux
+	lb binary_disk
+	lb binary_loadlin
+	lb binary_win32-loader
+	lb binary_includes
+	lb binary_grub-efi
+	lb binary_hooks
+	lb binary_checksums
+	find binary -newermt "$(date -d@${SOURCE_DATE_EPOCH} '+%Y-%m-%d %H:%M:%S')" -printf "%y %p\n" -exec touch '{}' -d@${SOURCE_DATE_EPOCH} --no-dereference ';' > binary.modified_timestamps
+	lb binary_iso
+	lb binary_onie
+	lb binary_netboot
+	lb binary_tar
+	lb binary_hdd
+	lb binary_zsync
+	lb chroot_prep remove all mode-archives-chroot
+	lb source
+
+	mv $prep_results_dir/live-image-${IB_TARGET_ARCH}.hybrid.iso $RESULTS_DIR/$IMAGE_BASENAME.iso
+
+elif [ "${IMAGE_TYPE}" = img ]; then
+
+	SECTOR_LEN=512
+	BOOT_START=$((1024 * 1024)) # 1MiB
+	BOOT_LEN=$((512 * 1024 * 1024)) # 512MiB
+	BOOT_END=$((BOOT_START + BOOT_LEN - 1))
+	ROOT_START=$((BOOT_END + 1))
+	ROOT_LEN=$((MAX_IMG_LEN - ROOT_START))
+	ROOT_END=$((MAX_IMG_LEN - 1))
+
+	TARGET_NAME=$prep_results_dir/${IMAGE_BASENAME}.img
+	truncate -s $MAX_IMG_LEN $TARGET_NAME
+
+	sfdisk $TARGET_NAME <<-EOF
+		label: dos
+		label-id: 0xcb15ae4d
+		unit: sectors
+		sector-size: 512
+
+		${TARGET_NAME}1 : start=$((BOOT_START / SECTOR_LEN)), size=$((BOOT_LEN / SECTOR_LEN)), type=c, bootable
+		${TARGET_NAME}2 : start=$((ROOT_START / SECTOR_LEN)), size=$((ROOT_LEN / SECTOR_LEN)), type=83
+	EOF
+
+	BOOT_DEV=$(losetup --show -f --offset $BOOT_START --sizelimit $BOOT_LEN $TARGET_NAME)
+	ROOT_DEV=$(losetup --show -f --offset $ROOT_START --sizelimit $ROOT_LEN $TARGET_NAME)
+
+	mkfs.vfat -F32 $BOOT_DEV
+	mkfs.ext4 $ROOT_DEV
+
+	TMPDIR=$(mktemp -d)
+
+	mkdir -p $TMPDIR/boot $TMPDIR/root
+	mount $ROOT_DEV $TMPDIR/root
+	mount $BOOT_DEV $TMPDIR/boot
+	unsquashfs -n -f -d $TMPDIR $prep_results_dir/binary/live/filesystem.squashfs boot
+
+	mkdir $TMPDIR/root/images $TMPDIR/root/config
+	B3SUM=$(b3sum $prep_results_dir/binary/live/filesystem.squashfs | head -c 16)
+	cp $prep_results_dir/binary/live/filesystem.squashfs $TMPDIR/root/images/$B3SUM.rootfs
+	ln -rsf $TMPDIR/root/images/$B3SUM.rootfs $TMPDIR/root/config/current.rootfs
+
+	mkdir -p $TMPDIR/next $TMPDIR/lower $TMPDIR/root/config/work $TMPDIR/root/config/overlay
+	mount $TMPDIR/root/config/current.rootfs $TMPDIR/lower
+
+	mount -t overlay -o lowerdir=$TMPDIR/lower,workdir=$TMPDIR/root/config/work,upperdir=$TMPDIR/root/config/overlay overlay $TMPDIR/next
+
+	if [ "${IB_TARGET_PLATFORM}" = "raspberrypi" ]; then
+		sed -i 's| boot=startos| boot=startos init=/usr/lib/startos/scripts/init_resize\.sh|' $TMPDIR/boot/cmdline.txt
+		rsync -a $SOURCE_DIR/raspberrypi/img/ $TMPDIR/next/
+	fi
+
+	umount $TMPDIR/next
+	umount $TMPDIR/lower
+
+	umount $TMPDIR/boot
+	umount $TMPDIR/root
+
+
+	e2fsck -fy $ROOT_DEV
+	resize2fs -M $ROOT_DEV
+
+	BLOCK_COUNT=$(dumpe2fs -h $ROOT_DEV | awk '/^Block count:/ { print $3 }')
+	BLOCK_SIZE=$(dumpe2fs -h $ROOT_DEV | awk '/^Block size:/ { print $3 }')
+	ROOT_LEN=$((BLOCK_COUNT * BLOCK_SIZE))
+
+	losetup -d $ROOT_DEV
+	losetup -d $BOOT_DEV
+
+	# Recreate partition 2 with the new size using sfdisk
+	sfdisk $TARGET_NAME <<-EOF
+		label: dos
+		label-id: 0xcb15ae4d
+		unit: sectors
+		sector-size: 512
+
+		${TARGET_NAME}1 : start=$((BOOT_START / SECTOR_LEN)), size=$((BOOT_LEN / SECTOR_LEN)), type=c, bootable
+		${TARGET_NAME}2 : start=$((ROOT_START / SECTOR_LEN)), size=$((ROOT_LEN / SECTOR_LEN)), type=83
+	EOF
+
+	TARGET_SIZE=$((ROOT_START + ROOT_LEN))
+	truncate -s $TARGET_SIZE $TARGET_NAME
+
+	mv $TARGET_NAME $RESULTS_DIR/$IMAGE_BASENAME.img
+
+fi
+
+chown $IB_UID:$IB_UID $RESULTS_DIR/$IMAGE_BASENAME.*

build/image-recipe/raspberrypi/img/etc/fstab

@@ -0,0 +1,2 @@
+/dev/mmcblk0p1  /boot   vfat    umask=0077  0   2
+/dev/mmcblk0p2  /       ext4    defaults    0   1

build/image-recipe/raspberrypi/img/usr/lib/startos/scripts/init_resize.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 get_variables () {
-  ROOT_PART_DEV=$(findmnt / -o source -n)
+  ROOT_PART_DEV=$(findmnt /media/startos/root -o source -n)
   ROOT_PART_NAME=$(echo "$ROOT_PART_DEV" | cut -d "/" -f 3)
   ROOT_DEV_NAME=$(echo /sys/block/*/"${ROOT_PART_NAME}" | cut -d "/" -f 4)
   ROOT_DEV="/dev/${ROOT_DEV_NAME}"
@@ -89,12 +89,12 @@ main () {
 
   resize2fs $ROOT_PART_DEV
 
-  if ! systemd-machine-id-setup; then
+  if ! systemd-machine-id-setup --root=/media/startos/config/overlay/; then
     FAIL_REASON="systemd-machine-id-setup failed"
     return 1
   fi
 
-  if ! ssh-keygen -A; then
+  if ! (mkdir -p /media/startos/config/overlay/etc/ssh && ssh-keygen -A -f /media/startos/config/overlay/); then
     FAIL_REASON="ssh host key generation failed"
     return 1
   fi
@@ -104,9 +104,6 @@ main () {
   return 0
 }
 
-mount -t proc proc /proc
-mount -t sysfs sys /sys
-mount -t tmpfs tmp /run
 mkdir -p /run/systemd
 mount /boot
 mount / -o remount,ro
@@ -114,7 +111,7 @@ mount / -o remount,ro
 beep
 
 if main; then
-  sed -i 's| init=/usr/lib/startos/scripts/init_resize\.sh| boot=embassy|' /boot/cmdline.txt
+  sed -i 's| init=/usr/lib/startos/scripts/init_resize\.sh||' /boot/cmdline.txt
   echo "Resized root filesystem. Rebooting in 5 seconds..."
   sleep 5
 else

build/image-recipe/raspberrypi/squashfs/boot/cmdline.txt

@@ -1 +1 @@
-usb-storage.quirks=152d:0562:u,14cd:121c:u,0781:cfcb:u console=serial0,115200 console=tty1 root=PARTUUID=cb15ae4d-02 rootfstype=ext4 fsck.repair=yes rootwait cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory quiet boot=embassy
+usb-storage.quirks=152d:0562:u,14cd:121c:u,0781:cfcb:u console=serial0,115200 console=tty1 root=PARTUUID=cb15ae4d-02 rootfstype=ext4 fsck.repair=yes rootwait cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory boot=startos

build/image-recipe/raspberrypi/squashfs/boot/config.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+
+cat << EOF
+
+# Enable audio (loads snd_bcm2835)
+dtparam=audio=on
+
+# Automatically load overlays for detected cameras
+camera_auto_detect=1
+
+# Automatically load overlays for detected DSI displays
+display_auto_detect=1
+
+# Enable DRM VC4 V3D driver
+dtoverlay=vc4-kms-v3d
+max_framebuffers=2
+
+# Run in 64-bit mode
+arm_64bit=1
+
+# Disable compensation for displays with overscan
+disable_overscan=1
+
+[cm4]
+# Enable host mode on the 2711 built-in XHCI USB controller.
+# This line should be removed if the legacy DWC2 controller is required
+# (e.g. for USB device mode) or if USB support is not required.
+otg_mode=1
+
+[all]
+
+[pi4]
+# Run as fast as firmware / board allows
+arm_boost=1
+kernel=vmlinuz-${KERNEL_VERSION}-rpi-v8
+initramfs initrd.img-${KERNEL_VERSION}-rpi-v8 followkernel
+
+[pi5]
+kernel=vmlinuz-${KERNEL_VERSION}-rpi-2712
+initramfs initrd.img-${KERNEL_VERSION}-rpi-2712 followkernel
+
+[all]
+gpu_mem=16
+dtoverlay=pwm-2chan,disable-bt
+
+EOF

build/image-recipe/raspberrypi/squashfs/boot/config.txt

@@ -83,4 +83,5 @@ arm_boost=1
 [all]
 gpu_mem=16
 dtoverlay=pwm-2chan,disable-bt
-initramfs initrd.img-6.1.21-v8+
+
+auto_initramfs=1

build/image-recipe/run-local-build.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+set -e
+
+cd "$(dirname "${BASH_SOURCE[0]}")/../.."
+
+BASEDIR="$(pwd -P)"
+
+SUITE=trixie
+
+USE_TTY=
+if tty -s; then
+  USE_TTY="-it"
+fi
+
+dockerfile_hash=$(sha256sum ${BASEDIR}/build/image-recipe/Dockerfile | head -c 7)
+
+docker_img_name="start9/build-iso:${SUITE}-${dockerfile_hash}"
+
+platform=linux/${ARCH}
+case $ARCH in
+	x86_64)
+		platform=linux/amd64;;
+	aarch64)
+		platform=linux/arm64;;
+esac
+
+if ! docker run --rm --platform=$platform "${docker_img_name}" true 2> /dev/null; then
+	docker buildx build --load --platform=$platform --build-arg=SUITE=${SUITE} -t "${docker_img_name}" ./build/image-recipe
+fi
+
+docker run $USE_TTY --rm --platform=$platform --privileged -v "$(pwd)/build/image-recipe:/root/image-recipe" -v "$(pwd)/results:/root/results" \
+	-e IB_SUITE="$SUITE" \
+	-e IB_UID="$UID" \
+	-e IB_INCLUDE \
+	"${docker_img_name}" /root/image-recipe/build.sh $@

build/lib/firmware.json

@@ -1,13 +1,13 @@
 [
   {
-    "id": "pureboot-librem_mini_v2-basic_usb_autoboot_blob_jail-Release-28.3",
+    "id": "pureboot-librem_mini_v2-basic_usb_autoboot_blob_jail-Release-29",
     "platform": ["x86_64"],
     "system-product-name": "librem_mini_v2",
     "bios-version": {
       "semver-prefix": "PureBoot-Release-",
-      "semver-range": "<28.3"
+      "semver-range": "<29"
     },
-    "url": "https://source.puri.sm/firmware/releases/-/raw/98418b5b8e9edc2bd1243ad7052a062f79e2b88e/librem_mini_v2/custom/pureboot-librem_mini_v2-basic_usb_autoboot_blob_jail-Release-28.3.rom.gz",
-    "shasum": "5019bcf53f7493c7aa74f8ef680d18b5fc26ec156c705a841433aaa2fdef8f35"
+    "url": "https://source.puri.sm/firmware/releases/-/raw/75631ad6dcf7e6ee73e06a517ac7dc4e017518b7/librem_mini_v2/custom/pureboot-librem_mini_v2-basic_usb_autoboot_blob_jail-Release-29.rom.gz",
+    "shasum": "96ec04f21b1cfe8e28d9a2418f1ff533efe21f9bbbbf16e162f7c814761b068b"
   }
 ]

build/lib/grub-theme/theme.txt

@@ -0,0 +1,51 @@
+desktop-image: "../splash.png"
+title-color: "#ffffff"
+title-font: "Unifont Regular 16"
+title-text: "StartOS Boot Menu with GRUB"
+message-font: "Unifont Regular 16"
+terminal-font: "Unifont Regular 16"
+
+#help bar at the bottom
++ label {
+        top = 100%-50
+        left = 0
+        width = 100%
+        height = 20
+        text = "@KEYMAP_SHORT@"
+        align = "center"
+        color = "#ffffff"
+        font = "Unifont Regular 16"
+}
+
+#boot menu
++ boot_menu {
+        left = 10%
+        width = 80%
+        top = 52%
+        height = 48%-80
+        item_color = "#a8a8a8"
+        item_font = "Unifont Regular 16"
+        selected_item_color= "#ffffff"
+        selected_item_font = "Unifont Regular 16"
+        item_height = 16
+        item_padding = 0
+        item_spacing = 4
+        icon_width = 0
+        icon_heigh = 0
+        item_icon_space = 0
+}
+
+#progress bar
++ progress_bar {
+        id = "__timeout__"
+        left = 15%
+        top = 100%-80
+        height = 16
+        width = 70%
+        font = "Unifont Regular 16"
+        text_color = "#000000"
+        fg_color = "#ffffff"
+        bg_color = "#a8a8a8"
+        border_color = "#ffffff"
+        text = "@TIMEOUT_NOTIFICATION_LONG@"
+}

build/lib/motd

@@ -1,34 +1,123 @@
 #!/bin/sh
-printf "\n"
-printf "Welcome to\n"
-cat << "ASCII"
 
-           ███████        
-         █    █    █      
-       █     █ █     █    
-      █     █   █     █   
-      █    █     █    █   
-       █  █       █  █    
-         █         █      
-           ███████        
+parse_essential_db_info() {
+    DB_DUMP="/tmp/startos_db.json"
 
-    _____     __ ___  __  __
-   (_  |  /\ |__) |  /  \(_
-   __) | /  \|  \ |  \__/__)
-ASCII
-printf "                            v$(cat /usr/lib/startos/VERSION.txt)\n\n"
-printf "   %s (%s %s)\n" "$(uname -o)" "$(uname -r)" "$(uname -m)"
-printf "   Git Hash: $(cat /usr/lib/startos/GIT_HASH.txt)"
-if [ -n "$(cat /usr/lib/startos/ENVIRONMENT.txt)" ]; then
-    printf " ~ $(cat /usr/lib/startos/ENVIRONMENT.txt)\n"
-else
-    printf "\n"
+    if command -v start-cli >/dev/null 2>&1; then
+        timeout 30 start-cli db dump > "$DB_DUMP" 2>/dev/null || return 1
+    else
+        return 1
+    fi
+
+    if command -v jq >/dev/null 2>&1 && [ -f "$DB_DUMP" ]; then
+        HOSTNAME=$(jq -r '.value.serverInfo.hostname // "unknown"' "$DB_DUMP" 2>/dev/null)
+        VERSION=$(jq -r '.value.serverInfo.version // "unknown"' "$DB_DUMP" 2>/dev/null)
+        RAM_BYTES=$(jq -r '.value.serverInfo.ram // 0' "$DB_DUMP" 2>/dev/null)
+        WAN_IP=$(jq -r '.value.serverInfo.network.gateways[].ipInfo.wanIp // "unknown"' "$DB_DUMP" 2>/dev/null | head -1)
+        NTP_SYNCED=$(jq -r '.value.serverInfo.ntpSynced // false' "$DB_DUMP" 2>/dev/null)
+
+        if [ "$RAM_BYTES" != "0" ] && [ "$RAM_BYTES" != "null" ]; then
+            RAM_GB=$(echo "scale=1; $RAM_BYTES / 1073741824" | bc 2>/dev/null || echo "unknown")
+        else
+            RAM_GB="unknown"
+        fi
+
+        RUNNING_SERVICES=$(jq -r '[.value.packageData[] | select(.statusInfo.started != null)] | length' "$DB_DUMP" 2>/dev/null)
+        TOTAL_SERVICES=$(jq -r '.value.packageData | length' "$DB_DUMP" 2>/dev/null)
+
+        rm -f "$DB_DUMP"
+        return 0
+    else
+        rm -f "$DB_DUMP" 2>/dev/null
+        return 1
+    fi
+}
+
+DB_INFO_AVAILABLE=0
+if parse_essential_db_info; then
+    DB_INFO_AVAILABLE=1
 fi
 
-printf "\n"
-printf " * Documentation:  https://docs.start9.com\n"
-printf " * Management:     https://%s.local\n" "$(hostname)"
-printf " * Support:        https://start9.com/contact\n"
-printf " * Source Code:    https://github.com/Start9Labs/start-os\n"
-printf " * License:        MIT\n"
-printf "\n"
+if [ "$DB_INFO_AVAILABLE" -eq 1 ] && [ "$VERSION" != "unknown" ]; then
+    version_display="v$VERSION"
+else
+    version_display="v$(cat /usr/lib/startos/VERSION.txt 2>/dev/null || echo 'unknown')"
+fi
+
+printf "\n\033[1;37m    ▄▄▀▀▀▀▀▄▄\033[0m\n"
+printf "\033[1;37m  ▄▀    ▄    ▀▄      ▄▄▄▄▄  ▄▄▄▄▄▄▄    ▄      ▄▄▄▄▄   ▄▄▄▄▄▄▄ \033[1;31m▄██████▄ ▄██████\033[0m\n"
+printf "\033[1;37m █     █ █     █    █          █      █ █     █    ▀▄    █    \033[1;31m██    ██ ██     \033[0m\n"
+printf "\033[1;37m█     █   █     █   ▀▄▄▄▄      █     █   █    █ ▄▄▄▀     █    \033[1;31m██    ██ ▀█████▄\033[0m\n"
+printf "\033[1;37m█    █     █    █        █     █    █     █   █  ▀▄      █    \033[1;31m██    ██      ██\033[0m\n"
+printf "\033[1;37m █  █       █  █    ▄▄▄▄▄▀     █   █       █  █    ▀▄    █    \033[1;31m▀██████▀ ██████▀\033[0m\n"
+printf "\033[1;37m   █         █\033[0m\n"
+printf "\033[1;37m     ▀▀▄▄▄▀▀                                                  $version_display\033[0m\n\n"
+
+uptime_str=$(uptime | awk -F'up ' '{print $2}' | awk -F',' '{print $1}' | sed 's/^ *//')
+
+if [ "$DB_INFO_AVAILABLE" -eq 1 ] && [ "$RAM_GB" != "unknown" ]; then
+    memory_used=$(free -m | awk 'NR==2{printf "%.0fMB", $3}')
+    memory_display="$memory_used / ${RAM_GB}GB"
+else
+    memory_display=$(free -m | awk 'NR==2{printf "%.0fMB / %.0fMB", $3, $2}')
+fi
+
+root_usage=$(df -h / | awk 'NR==2{printf "%s (%s free)", $5, $4}')
+
+if [ -d "/media/startos/data/package-data" ]; then
+    data_usage=$(df -h /media/startos/data/package-data | awk 'NR==2{printf "%s (%s free)", $5, $4}')
+else
+    data_usage="N/A"
+fi
+
+if [ "$DB_INFO_AVAILABLE" -eq 1 ]; then
+    services_text="$RUNNING_SERVICES/$TOTAL_SERVICES running"
+else
+    services_text="Unknown"
+fi
+
+local_ip=$(ip route get 1.1.1.1 2>/dev/null | awk '{for(i=1;i<=NF;i++) if($i=="src") print $(i+1)}' | head -1)
+if [ -z "$local_ip" ]; then local_ip="N/A"; fi
+
+if [ "$DB_INFO_AVAILABLE" -eq 1 ] && [ "$WAN_IP" != "unknown" ]; then
+    wan_ip="$WAN_IP"
+else
+    wan_ip="N/A"
+fi
+
+printf "    \033[1;37m┌─ SYSTEM STATUS ───────────────────────────────────────────────────┐\033[0m\n"
+printf "    \033[1;37m│\033[0m %-8s  \033[0;33m%-22s\033[0m %-8s \033[0;33m%-23s\033[0m \033[1;37m│\033[0m\n" "Uptime:" "$uptime_str" "Memory:" "$memory_display"
+printf "    \033[1;37m│\033[0m %-8s  \033[0;33m%-22s\033[0m %-8s \033[0;33m%-23s\033[0m \033[1;37m│\033[0m\n" "Root:" "$root_usage" "Data:" "$data_usage"
+
+if [ "$DB_INFO_AVAILABLE" -eq 1 ]; then
+    if [ "$RUNNING_SERVICES" -eq "$TOTAL_SERVICES" ] && [ "$TOTAL_SERVICES" -gt 0 ]; then
+        printf "    \033[1;37m│\033[0m %-8s \033[0;32m%-22s\033[0m %-8s \033[0;33m%-23s\033[0m \033[1;37m│\033[0m\n" "Services:" "$services_text" "WAN:" "$wan_ip"
+    elif [ "$RUNNING_SERVICES" -gt 0 ]; then
+        printf "    \033[1;37m│\033[0m %-8s \033[0;33m%-22s\033[0m %-8s \033[0;33m%-23s\033[0m \033[1;37m│\033[0m\n" "Services:" "$services_text" "WAN:" "$wan_ip"
+    else
+        printf "    \033[1;37m│\033[0m %-8s \033[0;31m%-22s\033[0m %-8s \033[0;33m%-23s\033[0m \033[1;37m│\033[0m\n" "Services:" "$services_text" "WAN:" "$wan_ip"
+    fi
+else
+    printf "    \033[1;37m│\033[0m %-8s \033[0;37m%-22s\033[0m %-8s \033[0;33m%-23s\033[0m \033[1;37m│\033[0m\n" "Services:" "$services_text" "WAN:" "$wan_ip"
+fi
+
+if [ "$DB_INFO_AVAILABLE" -eq 1 ] && [ "$NTP_SYNCED" = "true" ]; then
+    printf "    \033[1;37m│\033[0m %-8s  \033[0;33m%-22s\033[0m %-8s \033[0;32m%-23s\033[0m \033[1;37m│\033[0m\n" "Local:" "$local_ip" "NTP:" "Synced"
+elif [ "$DB_INFO_AVAILABLE" -eq 1 ] && [ "$NTP_SYNCED" = "false" ]; then
+    printf "    \033[1;37m│\033[0m %-8s  \033[0;33m%-22s\033[0m %-8s \033[0;31m%-23s\033[0m \033[1;37m│\033[0m\n" "Local:" "$local_ip" "NTP:" "Not Synced"
+else
+    printf "    \033[1;37m│\033[0m %-8s  \033[0;33m%-22s\033[0m %-8s \033[0;37m%-23s\033[0m \033[1;37m│\033[0m\n" "Local:" "$local_ip" "NTP:" "Unknown"
+fi
+
+printf "    \033[1;37m└───────────────────────────────────────────────────────────────────┘\033[0m"
+
+if [ "$DB_INFO_AVAILABLE" -eq 1 ] && [ "$HOSTNAME" != "unknown" ]; then
+    web_url="https://$HOSTNAME.local"
+else
+    web_url="https://$(hostname).local"
+fi
+printf "\n    \033[1;37m┌──────────────────────────────────────────────────── QUICK ACCESS ─┐\033[0m\n"
+printf "    \033[1;37m│\033[0m Web Interface: \033[0;36m%-50s\033[0m \033[1;37m│\033[0m\n" "$web_url"
+printf "    \033[1;37m│\033[0m Documentation: \033[0;36m%-50s\033[0m \033[1;37m│\033[0m\n" "https://staging.docs.start9.com"
+printf "    \033[1;37m│\033[0m Support:       \033[0;36m%-50s\033[0m \033[1;37m│\033[0m\n" "https://start9.com/contact"
+printf "    \033[1;37m└───────────────────────────────────────────────────────────────────┘\033[0m\n\n"

build/lib/scripts/add-apt-sources

@@ -4,6 +4,3 @@ set -e
 
 curl -fsSL https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --dearmor -o- > /usr/share/keyrings/tor-archive-keyring.gpg
 echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/tor-archive-keyring.gpg] https://deb.torproject.org/torproject.org bullseye main" > /etc/apt/sources.list.d/tor.list
-
-curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o- > /usr/share/keyrings/docker-archive-keyring.gpg
-echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian bullseye stable" > /etc/apt/sources.list.d/docker.list

build/lib/scripts/check-monitor

@@ -1,8 +0,0 @@
-#!/bin/sh
-
-
-if cat /sys/class/drm/*/status | grep -qw connected; then
-    exit 0
-else
-    exit 1
-fi

build/lib/scripts/chroot-and-upgrade

@@ -1,46 +1,116 @@
 #!/bin/bash
 
+SOURCE_DIR="$(dirname $(realpath "${BASH_SOURCE[0]}"))"
+
 if [ "$UID" -ne 0 ]; then
     >&2 echo 'Must be run as root'
     exit 1
 fi
 
+POSITIONAL_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+      --no-sync)
+          NO_SYNC=1
+          shift
+          ;;
+      --create)
+          ONLY_CREATE=1
+          shift
+          ;;
+      -*|--*)
+          echo "Unknown option $1"
+          exit 1
+          ;;
+      *)
+          POSITIONAL_ARGS+=("$1") # save positional arg
+          shift # past argument
+          ;;
+    esac
+done
+
+set -- "${POSITIONAL_ARGS[@]}" # restore positional parameters
+
 if [ -z "$NO_SYNC" ]; then
     echo 'Syncing...'
-    rsync -a --delete --force --info=progress2 /media/embassy/embassyfs/current/ /media/embassy/next
+    umount -R /media/startos/next 2> /dev/null
+    umount /media/startos/upper 2> /dev/null
+    rm -rf /media/startos/upper /media/startos/next
+    mkdir /media/startos/upper
+    mount -t tmpfs tmpfs /media/startos/upper
+    mkdir -p /media/startos/upper/data /media/startos/upper/work /media/startos/next
+    mount -t overlay \
+		  -olowerdir=/media/startos/current,upperdir=/media/startos/upper/data,workdir=/media/startos/upper/work \
+		  overlay /media/startos/next
 fi
 
-mkdir -p /media/embassy/next/run
-mkdir -p /media/embassy/next/dev
-mkdir -p /media/embassy/next/sys
-mkdir -p /media/embassy/next/proc
-mkdir -p /media/embassy/next/boot
-mount --bind /run /media/embassy/next/run
-mount --bind /dev /media/embassy/next/dev
-mount --bind /sys /media/embassy/next/sys
-mount --bind /proc /media/embassy/next/proc
-mount --bind /boot /media/embassy/next/boot
+if [ -n "$ONLY_CREATE" ]; then
+    exit 0
+fi
+
+mkdir -p /media/startos/next/run
+mkdir -p /media/startos/next/dev
+mkdir -p /media/startos/next/sys
+mkdir -p /media/startos/next/proc
+mkdir -p /media/startos/next/boot
+mkdir -p /media/startos/next/media/startos/root
+mount --bind /run /media/startos/next/run
+mount --bind /tmp /media/startos/next/tmp
+mount --bind /dev /media/startos/next/dev
+mount --bind /sys /media/startos/next/sys
+mount --bind /proc /media/startos/next/proc
+mount --bind /boot /media/startos/next/boot
+mount --bind /media/startos/root /media/startos/next/media/startos/root
+
+if mountpoint /sys/firmware/efi/efivars 2>&1 > /dev/null; then
+  mount --bind /sys/firmware/efi/efivars /media/startos/next/sys/firmware/efi/efivars
+fi
 
 if [ -z "$*" ]; then
-    chroot /media/embassy/next
+    chroot /media/startos/next
     CHROOT_RES=$?
 else
-    chroot /media/embassy/next "$SHELL" -c "$*"
+    chroot /media/startos/next "$SHELL" -c "$*"
     CHROOT_RES=$?
 fi
 
-umount /media/embassy/next/run
-umount /media/embassy/next/dev
-umount /media/embassy/next/sys
-umount /media/embassy/next/proc
-umount /media/embassy/next/boot
+if mountpoint /media/startos/next/sys/firmware/efi/efivars 2>&1 > /dev/null; then
+  umount /media/startos/next/sys/firmware/efi/efivars 
+fi
+
+umount /media/startos/next/run
+umount /media/startos/next/tmp
+umount /media/startos/next/dev
+umount /media/startos/next/sys
+umount /media/startos/next/proc
+umount /media/startos/next/boot
+umount /media/startos/next/media/startos/root
 
 if [ "$CHROOT_RES" -eq 0 ]; then
+
+    if [ -h /media/startos/config/current.rootfs ] && [ -e /media/startos/config/current.rootfs ]; then
+        ${SOURCE_DIR}/prune-images $(du -s --bytes /media/startos/next | awk '{print $1}')
+    fi
+
     echo 'Upgrading...'
 
-    touch /media/embassy/config/upgrade
+    rm -f /media/startos/images/next.squashfs
+    if ! time mksquashfs /media/startos/next /media/startos/images/next.squashfs -b 4096 -comp gzip; then
+        umount -l /media/startos/next
+        umount -l /media/startos/upper
+        rm -rf /media/startos/upper /media/startos/next
+        exit 1
+    fi
+    hash=$(b3sum /media/startos/images/next.squashfs | head -c 32)
+    mv /media/startos/images/next.squashfs /media/startos/images/${hash}.rootfs
+    ln -rsf /media/startos/images/${hash}.rootfs /media/startos/config/current.rootfs
 
     sync
 
     reboot
-fi
+fi
+
+umount /media/startos/next
+umount /media/startos/upper
+rm -rf /media/startos/upper /media/startos/next

build/lib/scripts/dhclient-exit-hook

@@ -1 +0,0 @@
-start-cli net dhcp update $interface

build/lib/scripts/embassy-initramfs-module

@@ -1,98 +0,0 @@
-# Local filesystem mounting			-*- shell-script -*-
-
-#
-# This script overrides local_mount_root() in /scripts/local
-# and mounts root as a read-only filesystem with a temporary (rw)
-# overlay filesystem.
-#
-
-. /scripts/local
-
-local_mount_root()
-{
-	echo 'using embassy initramfs module'
-
-	local_top
-	local_device_setup "${ROOT}" "root file system"
-	ROOT="${DEV}"
-
-	# Get the root filesystem type if not set
-	if [ -z "${ROOTFSTYPE}" ]; then
-		FSTYPE=$(get_fstype "${ROOT}")
-	else
-		FSTYPE=${ROOTFSTYPE}
-	fi
-
-	local_premount
-
-	# CHANGES TO THE ORIGINAL FUNCTION BEGIN HERE
-	# N.B. this code still lacks error checking
-
-	modprobe ${FSTYPE}
-	checkfs ${ROOT} root "${FSTYPE}"
-
-	ROOTFLAGS="$(echo "${ROOTFLAGS}" | sed 's/subvol=\(next\|current\)//' | sed 's/^-o *$//')"
-
-	if [ "${FSTYPE}" != "unknown" ]; then
-		mount -t ${FSTYPE} ${ROOTFLAGS} ${ROOT} ${rootmnt}
-	else
-		mount ${ROOTFLAGS} ${ROOT} ${rootmnt}
-	fi
-
-	echo 'mounting embassyfs'
-
-	mkdir /embassyfs
-
-	mount --move ${rootmnt} /embassyfs
-
-	if ! [ -d /embassyfs/current ] && [ -d /embassyfs/prev ]; then
-		mv /embassyfs/prev /embassyfs/current
-	fi
-
-	if ! [ -d /embassyfs/current ]; then
-		mkdir /embassyfs/current
-		for FILE in $(ls /embassyfs); do
-			if [ "$FILE" != current ]; then
-				mv /embassyfs/$FILE /embassyfs/current/
-			fi
-		done
-	fi
-
-	mkdir -p /embassyfs/config
-
-	if [ -f /embassyfs/config/upgrade ] && [ -d /embassyfs/next ]; then
-		mv /embassyfs/current /embassyfs/prev
-		mv /embassyfs/next /embassyfs/current
-		rm /embassyfs/config/upgrade
-	fi
-
-	if ! [ -d /embassyfs/next ]; then
-		if [ -d /embassyfs/prev ]; then
-			mv /embassyfs/prev /embassyfs/next
-		else
-			mkdir /embassyfs/next
-		fi
-	fi
-
-	mkdir /lower /upper
-
-	mount -r --bind /embassyfs/current /lower
-
-	modprobe overlay || insmod "/lower/lib/modules/$(uname -r)/kernel/fs/overlayfs/overlay.ko"
-
-	# Mount a tmpfs for the overlay in /upper
-	mount -t tmpfs tmpfs /upper
-	mkdir /upper/data /upper/work
-
-	# Mount the final overlay-root in $rootmnt
-	mount -t overlay \
-	    -olowerdir=/lower,upperdir=/upper/data,workdir=/upper/work \
-	    overlay ${rootmnt}
-
-	mkdir -p ${rootmnt}/media/embassy/config
-	mount --bind /embassyfs/config ${rootmnt}/media/embassy/config
-	mkdir -p ${rootmnt}/media/embassy/next
-	mount --bind /embassyfs/next ${rootmnt}/media/embassy/next
-	mkdir -p ${rootmnt}/media/embassy/embassyfs
-	mount -r --bind /embassyfs ${rootmnt}/media/embassy/embassyfs
-}

build/lib/scripts/enable-kiosk

@@ -4,7 +4,7 @@ set -e
 
 # install dependencies
 /usr/bin/apt update
-/usr/bin/apt install --no-install-recommends -y xserver-xorg x11-xserver-utils xinit firefox-esr matchbox-window-manager libnss3-tools
+/usr/bin/apt install --no-install-recommends -y xserver-xorg x11-xserver-utils xinit firefox-esr matchbox-window-manager libnss3-tools p11-kit-modules
 
 #Change a default preference set by stock debian firefox-esr
 sed -i 's|^pref("extensions.update.enabled", true);$|pref("extensions.update.enabled", false);|' /etc/firefox-esr/firefox-esr.js
@@ -14,14 +14,8 @@ if ! id kiosk; then
     useradd -s /bin/bash --create-home kiosk
 fi
 
-# create kiosk script
-cat > /home/kiosk/kiosk.sh << 'EOF'
-#!/bin/sh
-PROFILE=$(mktemp -d)
-if [ -f /usr/local/share/ca-certificates/startos-root-ca.crt ]; then
-    certutil -A -n "StartOS Local Root CA" -t "TCu,Cuw,Tuw" -i /usr/local/share/ca-certificates/startos-root-ca.crt -d $PROFILE
-fi
-cat >> $PROFILE/prefs.js << EOT
+mkdir /home/kiosk/fx-profile
+cat >> /home/kiosk/fx-profile/prefs.js << EOF
 user_pref("app.normandy.api_url", "");
 user_pref("app.normandy.enabled", false);
 user_pref("app.shield.optoutstudies.enabled", false);
@@ -33,7 +27,6 @@ user_pref("browser.crashReports.unsubmittedCheck.autoSubmit2", false);
 user_pref("browser.newtabpage.activity-stream.feeds.asrouterfeed", false);
 user_pref("browser.newtabpage.activity-stream.feeds.topsites", false);
 user_pref("browser.newtabpage.activity-stream.showSponsoredTopSites", false);
-user_pref("browser.onboarding.enabled", false);
 user_pref("browser.ping-centre.telemetry", false);
 user_pref("browser.pocket.enabled",	false);
 user_pref("browser.safebrowsing.blockedURIs.enabled", false);
@@ -49,7 +42,7 @@ user_pref("browser.startup.homepage_override.mstone", "ignore");
 user_pref("browser.theme.content-theme", 0);
 user_pref("browser.theme.toolbar-theme", 0);
 user_pref("browser.urlbar.groupLabels.enabled", false);
-user_pref("browser.urlbar.suggest.searches" false);
+user_pref("browser.urlbar.suggest.searches", false);
 user_pref("datareporting.policy.firstRunURL", "");
 user_pref("datareporting.healthreport.service.enabled", false);
 user_pref("datareporting.healthreport.uploadEnabled", false);
@@ -58,10 +51,9 @@ user_pref("dom.securecontext.allowlist_onions", true);
 user_pref("dom.securecontext.whitelist_onions", true);
 user_pref("experiments.enabled", false);
 user_pref("experiments.activeExperiment", false);
-user_pref("experiments.supported", false);
 user_pref("extensions.activeThemeID", "firefox-compact-dark@mozilla.org");
 user_pref("extensions.blocklist.enabled", false);
-user_pref("extensions.getAddons.cache.enabled", false);
+user_pref("extensions.htmlaboutaddons.recommendations.enabled", false);
 user_pref("extensions.pocket.enabled", false);
 user_pref("extensions.update.enabled", false);
 user_pref("extensions.shield-recipe-client.enabled", false);
@@ -72,9 +64,15 @@ user_pref("messaging-system.rsexperimentloader.enabled", false);
 user_pref("network.allow-experiments", false);
 user_pref("network.captive-portal-service.enabled", false);
 user_pref("network.connectivity-service.enabled", false);
-user_pref("network.proxy.autoconfig_url", "file:///usr/lib/startos/proxy.pac");
+user_pref("network.proxy.socks", "10.0.3.1");
+user_pref("network.proxy.socks_port", 9050);
+user_pref("network.proxy.socks_version", 5);
 user_pref("network.proxy.socks_remote_dns", true);
-user_pref("network.proxy.type", 2);
+user_pref("network.proxy.type", 1);
+user_pref("privacy.resistFingerprinting", true);
+//Enable letterboxing if we want the window size sent to the server to snap to common resolutions:
+//user_pref("privacy.resistFingerprinting.letterboxing", true);
+user_pref("privacy.trackingprotection.enabled", true);
 user_pref("signon.rememberSignons", false);
 user_pref("toolkit.telemetry.archive.enabled", false);
 user_pref("toolkit.telemetry.bhrPing.enabled", false);
@@ -87,22 +85,31 @@ user_pref("toolkit.telemetry.shutdownPingSender.enabled", false);
 user_pref("toolkit.telemetry.unified", false);
 user_pref("toolkit.telemetry.updatePing.enabled", false);
 user_pref("toolkit.telemetry.cachedClientID", "");
-EOT
+//Blocking automatic Mozilla CDN server requests
+user_pref("extensions.getAddons.showPane", false);
+user_pref("extensions.getAddons.cache.enabled", false);
+//user_pref("services.settings.server", ""); // Remote settings server (HSTS preload updates and Cerfiticate Revocation Lists are fetched)
+user_pref("browser.aboutHomeSnippets.updateUrl", "");
+user_pref("browser.newtabpage.activity-stream.feeds.snippets", false);
+user_pref("browser.newtabpage.activity-stream.feeds.section.topstories", false);
+user_pref("browser.newtabpage.activity-stream.feeds.system.topstories", false);
+user_pref("browser.newtabpage.activity-stream.feeds.discoverystreamfeed", false);
+user_pref("browser.safebrowsing.provider.mozilla.updateURL", "");
+user_pref("browser.safebrowsing.provider.mozilla.gethashURL", "");
+EOF
+
+ln -sf /usr/lib/$(uname -m)-linux-gnu/pkcs11/p11-kit-trust.so /usr/lib/firefox-esr/libnssckbi.so
+
+# create kiosk script
+cat > /home/kiosk/kiosk.sh << 'EOF'
+#!/bin/sh
 while ! curl "http://localhost" > /dev/null; do
     sleep 1
 done
-while ! /usr/lib/startos/scripts/check-monitor; do
-    sleep 15
-done
-(
-    while /usr/lib/startos/scripts/check-monitor; do
-        sleep 15
-    done
-    killall firefox-esr
-) &
 matchbox-window-manager -use_titlebar no &
-firefox-esr http://localhost --profile $PROFILE
-rm -rf $PROFILE
+cp -r /home/kiosk/fx-profile /home/kiosk/fx-profile-tmp
+firefox-esr http://localhost --profile /home/kiosk/fx-profile-tmp
+rm -rf /home/kiosk/fx-profile-tmp
 EOF
 chmod +x /home/kiosk/kiosk.sh
 
@@ -116,6 +123,8 @@ fi
 EOF
 fi
 
+chown -R kiosk:kiosk /home/kiosk
+
 # enable autologin
 mkdir -p /etc/systemd/system/getty@tty1.service.d
 cat > /etc/systemd/system/getty@tty1.service.d/autologin.conf << 'EOF'

build/lib/scripts/forward-port

@@ -0,0 +1,72 @@
+#!/bin/bash
+
+if [ -z "$sip" ] || [ -z "$dip" ] || [ -z "$dprefix" ] || [ -z "$sport" ] || [ -z "$dport" ]; then
+    >&2 echo 'missing required env var'
+    exit 1
+fi
+
+NAME="F$(echo "$sip:$sport -> $dip/$dprefix:$dport ${src_subnet:-any}" | sha256sum | head -c 15)"
+
+for kind in INPUT FORWARD ACCEPT; do
+    if ! iptables -C $kind -j "${NAME}_${kind}" 2> /dev/null; then
+        iptables -N "${NAME}_${kind}" 2> /dev/null
+        iptables -A $kind -j "${NAME}_${kind}"
+    fi
+done
+for kind in PREROUTING OUTPUT POSTROUTING; do
+    if ! iptables -t nat -C $kind -j "${NAME}_${kind}" 2> /dev/null; then
+        iptables -t nat -N "${NAME}_${kind}" 2> /dev/null
+        iptables -t nat -A $kind -j "${NAME}_${kind}"
+    fi
+done
+
+err=0
+trap 'err=1' ERR
+
+for kind in INPUT FORWARD ACCEPT; do
+    iptables -F "${NAME}_${kind}" 2> /dev/null
+done
+for kind in PREROUTING OUTPUT POSTROUTING; do
+    iptables -t nat -F "${NAME}_${kind}" 2> /dev/null
+done
+if [ "$UNDO" = 1 ]; then
+    conntrack -D -p tcp -d $sip --dport $sport || true # conntrack returns exit 1 if no connections are active
+    conntrack -D -p udp -d $sip --dport $sport || true # conntrack returns exit 1 if no connections are active
+    exit $err
+fi
+
+# DNAT: rewrite destination for incoming packets (external traffic)
+# When src_subnet is set, only forward traffic from that subnet (private forwards)
+if [ -n "$src_subnet" ]; then
+    iptables -t nat -A ${NAME}_PREROUTING -s "$src_subnet" -d "$sip" -p tcp --dport "$sport" -j DNAT --to-destination "$dip:$dport"
+    iptables -t nat -A ${NAME}_PREROUTING -s "$src_subnet" -d "$sip" -p udp --dport "$sport" -j DNAT --to-destination "$dip:$dport"
+    # Also allow containers on the bridge subnet to reach this forward
+    if [ -n "$bridge_subnet" ]; then
+        iptables -t nat -A ${NAME}_PREROUTING -s "$bridge_subnet" -d "$sip" -p tcp --dport "$sport" -j DNAT --to-destination "$dip:$dport"
+        iptables -t nat -A ${NAME}_PREROUTING -s "$bridge_subnet" -d "$sip" -p udp --dport "$sport" -j DNAT --to-destination "$dip:$dport"
+    fi
+else
+    iptables -t nat -A ${NAME}_PREROUTING -d "$sip" -p tcp --dport "$sport" -j DNAT --to-destination "$dip:$dport"
+    iptables -t nat -A ${NAME}_PREROUTING -d "$sip" -p udp --dport "$sport" -j DNAT --to-destination "$dip:$dport"
+fi
+
+# DNAT: rewrite destination for locally-originated packets (hairpin from host itself)
+iptables -t nat -A ${NAME}_OUTPUT -d "$sip" -p tcp --dport "$sport" -j DNAT --to-destination "$dip:$dport"
+iptables -t nat -A ${NAME}_OUTPUT -d "$sip" -p udp --dport "$sport" -j DNAT --to-destination "$dip:$dport"
+
+# Allow new connections to be forwarded to the destination
+iptables -A ${NAME}_FORWARD -d $dip -p tcp --dport $dport -m state --state NEW -j ACCEPT
+iptables -A ${NAME}_FORWARD -d $dip -p udp --dport $dport -m state --state NEW -j ACCEPT
+
+# NAT hairpin: masquerade traffic from the bridge subnet or host to the DNAT
+# target, so replies route back through the host for proper NAT reversal.
+# Container-to-container hairpin (source is on the bridge subnet)
+if [ -n "$bridge_subnet" ]; then
+    iptables -t nat -A ${NAME}_POSTROUTING -s "$bridge_subnet" -d "$dip" -p tcp --dport "$dport" -j MASQUERADE
+    iptables -t nat -A ${NAME}_POSTROUTING -s "$bridge_subnet" -d "$dip" -p udp --dport "$dport" -j MASQUERADE
+fi
+# Host-to-container hairpin (host connects to its own gateway IP, source is sip)
+iptables -t nat -A ${NAME}_POSTROUTING -s "$sip" -d "$dip" -p tcp --dport "$dport" -j MASQUERADE
+iptables -t nat -A ${NAME}_POSTROUTING -s "$sip" -d "$dip" -p udp --dport "$dport" -j MASQUERADE
+
+exit $err

build/lib/scripts/gather-debug-info

@@ -0,0 +1,105 @@
+#!/bin/bash
+
+# Define the output file
+OUTPUT_FILE="system_debug_info.txt"
+
+# Check if the script is run as root, if not, restart with sudo
+if [ "$(id -u)" -ne 0 ]; then
+    exec sudo bash "$0" "$@"
+fi
+
+# Create or clear the output file and add a header
+echo "===================================================================" > "$OUTPUT_FILE"
+echo "                     StartOS System Debug Information              " >> "$OUTPUT_FILE"
+echo "===================================================================" >> "$OUTPUT_FILE"
+echo "Generated on: $(date)" >> "$OUTPUT_FILE"
+echo "" >> "$OUTPUT_FILE"
+
+# Function to check if a command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Function to run a command if it exists and append its output to the file with headers
+run_command() {
+    local CMD="$1"
+    local DESC="$2"
+    local CMD_NAME="${CMD%% *}"  # Extract the command name (first word)
+
+    if command_exists "$CMD_NAME"; then
+        echo "===================================================================" >> "$OUTPUT_FILE"
+        echo "COMMAND: $CMD" >> "$OUTPUT_FILE"
+        echo "DESCRIPTION: $DESC" >> "$OUTPUT_FILE"
+        echo "===================================================================" >> "$OUTPUT_FILE"
+        echo "" >> "$OUTPUT_FILE"
+        eval "$CMD" >> "$OUTPUT_FILE" 2>&1
+        echo "" >> "$OUTPUT_FILE"
+    else
+        echo "===================================================================" >> "$OUTPUT_FILE"
+        echo "COMMAND: $CMD" >> "$OUTPUT_FILE"
+        echo "DESCRIPTION: $DESC" >> "$OUTPUT_FILE"
+        echo "===================================================================" >> "$OUTPUT_FILE"
+        echo "SKIPPED: Command not found" >> "$OUTPUT_FILE"
+        echo "" >> "$OUTPUT_FILE"
+    fi
+}
+
+# Collecting basic system information
+run_command "start-cli --version; start-cli git-info" "StartOS CLI version and Git information"
+run_command "hostname" "Hostname of the system"
+run_command "uname -a" "Kernel version and system architecture"
+
+# Services Info
+run_command "start-cli lxc stats" "All Running Services"
+
+# Collecting CPU information
+run_command "lscpu" "CPU architecture information"
+run_command "cat /proc/cpuinfo" "Detailed CPU information"
+
+# Collecting memory information
+run_command "free -h" "Available and used memory"
+run_command "cat /proc/meminfo" "Detailed memory information"
+
+# Collecting storage information
+run_command "lsblk" "List of block devices"
+run_command "df -h" "Disk space usage"
+run_command "fdisk -l" "Detailed disk partition information"
+
+# Collecting network information
+run_command "ip a" "Network interfaces and IP addresses"
+run_command "ip route" "Routing table"
+run_command "netstat -i" "Network interface statistics"
+
+# Collecting RAID information (if applicable)
+run_command "cat /proc/mdstat" "List of RAID devices (if applicable)"
+
+# Collecting virtualization information
+run_command "egrep -c '(vmx|svm)' /proc/cpuinfo" "Check if CPU supports virtualization"
+run_command "systemd-detect-virt" "Check if the system is running inside a virtual machine"
+
+# Final message
+echo "===================================================================" >> "$OUTPUT_FILE"
+echo "                    End of StartOS System Debug Information        " >> "$OUTPUT_FILE"
+echo "===================================================================" >> "$OUTPUT_FILE"
+
+# Prompt user to send the log file to a Start9 Technician
+echo "System debug information has been collected in $OUTPUT_FILE."
+echo ""
+echo "Would you like to send this log file to a Start9 Technician? (yes/no)"
+read SEND_LOG
+
+if [[ "$SEND_LOG" == "yes" || "$SEND_LOG" == "y" ]]; then
+    if command -v wormhole >/dev/null 2>&1; then
+        echo ""
+        echo "==================================================================="
+        echo "      Running wormhole to send the file. Please follow the          "
+        echo "      instructions and provide the code to the Start9 support team. "
+        echo "==================================================================="
+        wormhole send "$OUTPUT_FILE"
+        echo "==================================================================="
+    else
+        echo "Error: wormhole command not found."
+    fi
+else
+    echo "Log file not sent. You can manually share $OUTPUT_FILE with the Start9 support team if needed."
+fi

build/lib/scripts/grub-probe-eos

@@ -3,8 +3,8 @@
 ARGS=
 
 for ARG in $@; do
-  if [ -d "/media/embassy/embassyfs" ] && [ "$ARG" = "/" ]; then
-   ARG=/media/embassy/embassyfs
+  if [ -d "/media/startos/root" ] && [ "$ARG" = "/" ]; then
+   ARG=/media/startos/root
   fi
   ARGS="$ARGS $ARG"
 done

build/lib/scripts/install-equivs

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+export DEBIAN_FRONTEND=noninteractive
+export DEBCONF_NONINTERACTIVE_SEEN=true
+
+TMP_DIR=$(mktemp -d)
+
+(
+    set -e
+    cd $TMP_DIR
+
+    cat > control.equivs
+    equivs-build control.equivs
+    apt-get install -y ./*.deb < /dev/null
+)
+
+rm -rf $TMP_DIR
+
+echo Install complete. >&2
+exit 0

build/lib/scripts/prune-boot

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+set -e
+
+if [ "$UID" -ne 0 ]; then
+    >&2 echo 'Must be run as root'
+    exit 1
+fi
+
+# Get the current kernel version
+current_kernel=$(uname -r)
+
+echo "Current kernel: $current_kernel"
+echo "Searching for old kernel files in /boot..."
+
+# Extract base kernel version (without possible suffixes)
+current_base=$(echo "$current_kernel" | sed 's/-.*//')
+
+cd /boot || { echo "/boot directory not found!"; exit 1; }
+
+for file in vmlinuz-* initrd.img-* System.map-* config-*; do
+    # Extract version from filename
+    version=$(echo "$file" | sed -E 's/^[^0-9]*([0-9][^ ]*).*/\1/')
+    # Skip if file matches current kernel version
+    if [[ "$file" == *"$current_kernel"* ]]; then
+        continue
+    fi
+    # Compare versions, delete if less than current
+    if dpkg --compare-versions "$version" lt "$current_kernel"; then
+        echo "Deleting $file (version $version is older than $current_kernel)"
+        sudo rm -f "$file"
+    fi
+done
+
+echo "Old kernel files deleted."

build/lib/scripts/prune-images

@@ -0,0 +1,53 @@
+#!/bin/bash
+
+if [ "$UID" -ne 0 ]; then
+    >&2 echo 'Must be run as root'
+    exit 1
+fi
+
+POSITIONAL_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -*|--*)
+      echo "Unknown option $1"
+      exit 1
+      ;;
+    *)
+      POSITIONAL_ARGS+=("$1") # save positional arg
+      shift # past argument
+      ;;
+  esac
+done
+
+set -- "${POSITIONAL_ARGS[@]}" # restore positional parameters
+
+needed=$1
+
+if [ -z "$needed" ]; then
+    >&2 echo "usage: $0 <SPACE NEEDED>"
+    exit 1
+fi
+
+MARGIN=${MARGIN:-1073741824}
+target=$((needed + MARGIN))
+
+if [ -h /media/startos/config/current.rootfs ] && [ -e /media/startos/config/current.rootfs ]; then
+    echo 'Pruning...'
+    current="$(readlink -f /media/startos/config/current.rootfs)"
+    while [[ "$(df -B1 --output=avail --sync /media/startos/images | tail -n1)" -lt "$target" ]]; do
+        to_prune="$(ls -t1 /media/startos/images/*.rootfs /media/startos/images/*.squashfs 2> /dev/null | grep -v "$current" | tail -n1)"
+        if [ -e "$to_prune" ]; then
+            echo "  Pruning $to_prune"
+            rm -rf "$to_prune"
+            sync
+        else
+            >&2 echo "Not enough space and nothing to prune!"
+            exit 1
+        fi
+    done
+    echo 'done.'
+else
+    >&2 echo 'No current.rootfs, not safe to prune'
+    exit 1
+fi

build/lib/scripts/startos-initramfs-module

@@ -0,0 +1,115 @@
+# Local filesystem mounting			-*- shell-script -*-
+
+#
+# This script overrides local_mount_root() in /scripts/local
+# and mounts root as a read-only filesystem with a temporary (rw)
+# overlay filesystem.
+#
+
+. /scripts/local
+
+local_mount_root()
+{
+	echo 'using startos initramfs module'
+
+	local_top
+	local_device_setup "${ROOT}" "root file system"
+	ROOT="${DEV}"
+
+	# Get the root filesystem type if not set
+	if [ -z "${ROOTFSTYPE}" ]; then
+		FSTYPE=$(get_fstype "${ROOT}")
+	else
+		FSTYPE=${ROOTFSTYPE}
+	fi
+
+	local_premount
+
+	# CHANGES TO THE ORIGINAL FUNCTION BEGIN HERE
+	# N.B. this code still lacks error checking
+
+	modprobe ${FSTYPE}
+	checkfs ${ROOT} root "${FSTYPE}"
+
+	echo 'mounting startos'
+	mkdir /startos
+
+	ROOTFLAGS="$(echo "${ROOTFLAGS}" | sed 's/subvol=\(next\|current\)//' | sed 's/^-o *$//')"
+
+	if [ "${FSTYPE}" != "unknown" ]; then
+		mount -t ${FSTYPE} ${ROOTFLAGS} ${ROOT} /startos
+	else
+		mount ${ROOTFLAGS} ${ROOT} /startos
+	fi
+
+	if [ -d /startos/images ]; then
+		if [ -h /startos/config/current.rootfs ] && [ -e /startos/config/current.rootfs ]; then
+			image=$(readlink -f /startos/config/current.rootfs)
+		else
+			image="$(ls -t1 /startos/images/*.rootfs | head -n1)"
+		fi
+		if ! [ -f "$image" ]; then
+			>&2 echo "image $image not available to boot"
+			exit 1
+		fi
+	else
+		if [ -f /startos/config/upgrade ] && [ -d /startos/next ]; then
+			oldroot=/startos/next
+		elif [ -d /startos/current ]; then
+			oldroot=/startos/current
+		elif [ -d /startos/prev ]; then
+			oldroot=/startos/prev
+		else
+			>&2 echo no StartOS filesystem found
+			exit 1
+		fi
+
+		mkdir -p /startos/config/overlay/etc
+		mv $oldroot/etc/fstab /startos/config/overlay/etc/fstab
+		mv $oldroot/etc/machine-id /startos/config/overlay/etc/machine-id
+		mv $oldroot/etc/ssh /startos/config/overlay/etc/ssh
+
+		mkdir -p /startos/images
+		mv $oldroot /startos/images/legacy.rootfs
+
+		rm -rf /startos/next /startos/current /startos/prev
+
+		ln -rsf /startos/images/old.squashfs /startos/config/current.rootfs
+		image=$(readlink -f /startos/config/current.rootfs)
+	fi
+
+	mkdir /lower /upper
+
+	if [ -d "$image" ]; then
+		mount -r --bind $image /lower
+	elif [ -f "$image" ]; then
+		modprobe loop
+		modprobe squashfs
+		mount -r $image /lower
+	else
+		>&2 echo "not a regular file or directory: $image"
+		exit 1
+	fi
+
+	modprobe overlay || insmod "/lower/lib/modules/$(uname -r)/kernel/fs/overlayfs/overlay.ko"
+
+	# Mount a tmpfs for the overlay in /upper
+	mount -t tmpfs tmpfs /upper
+	mkdir /upper/data /upper/work
+
+	mkdir -p /startos/config/overlay
+
+	# Mount the final overlay-root in $rootmnt
+	mount -t overlay \
+		-olowerdir=/startos/config/overlay:/lower,upperdir=/upper/data,workdir=/upper/work \
+		overlay ${rootmnt}
+
+	mkdir -p ${rootmnt}/media/startos/config
+	mount --bind /startos/config ${rootmnt}/media/startos/config
+	mkdir -p ${rootmnt}/media/startos/images
+	mount --bind /startos/images ${rootmnt}/media/startos/images
+	mkdir -p ${rootmnt}/media/startos/root
+	mount -r --bind /startos ${rootmnt}/media/startos/root
+	mkdir -p ${rootmnt}/media/startos/current
+	mount -r --bind /lower ${rootmnt}/media/startos/current
+}

build/lib/scripts/tor-check

@@ -0,0 +1,64 @@
+#!/bin/bash
+
+# --- Config ---
+# Colors (using printf to ensure compatibility)
+GRAY=$(printf '\033[90m')
+GREEN=$(printf '\033[32m')
+RED=$(printf '\033[31m')
+NC=$(printf '\033[0m') # No Color
+
+# Proxies to test
+proxies=(
+    "Host Tor|127.0.1.1:9050"
+    "Startd Tor|10.0.3.1:9050"
+)
+
+# Default URLs
+onion_list=(
+    "The Tor Project|http://2gzyxa5ihm7nsggfxnu52rck2vv4rvmdlkiu3zzui5du4xyclen53wid.onion"
+    "Start9|http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion"
+    "Mempool|http://mempoolhqx4isw62xs7abwphsq7ldayuidyx2v2oethdhhj6mlo2r6ad.onion"
+    "DuckDuckGo|https://duckduckgogg42xjoc72x3sjasowoarfbgcmvfimaftt6twagswzczad.onion"
+    "Brave Search|https://search.brave4u7jddbv7cyviptqjc7jusxh72uik7zt6adtckl5f4nwy2v72qd.onion"
+)
+
+# Load custom list
+[ -f ~/.startos/tor-check.list ] && readarray -t custom_list < <(grep -v '^#' ~/.startos/tor-check.list) && onion_list+=("${custom_list[@]}")
+
+# --- Functions ---
+print_line() { printf "${GRAY}────────────────────────────────────────${NC}\n"; }
+
+# --- Main ---
+echo "Testing Onion Connections..."
+
+for proxy_info in "${proxies[@]}"; do
+    proxy_name="${proxy_info%%|*}"
+    proxy_addr="${proxy_info#*|}"
+    
+    print_line
+    printf "${GRAY}Proxy: %s (%s)${NC}\n" "$proxy_name" "$proxy_addr"
+    
+    for data in "${onion_list[@]}"; do
+        name="${data%%|*}"
+        url="${data#*|}"
+        
+        # Capture verbose output + http code.
+        # --no-progress-meter: Suppresses the "0 0 0" stats but keeps -v output
+        output=$(curl -v --no-progress-meter --max-time 15 --socks5-hostname "$proxy_addr" "$url" 2>&1)
+        exit_code=$?
+        
+        if [ $exit_code -eq 0 ]; then
+            printf "  ${GREEN}[pass]${NC} %s (%s)\n" "$name" "$url"
+        else
+            printf "  ${RED}[fail]${NC} %s (%s)\n" "$name" "$url"
+            printf "         ${RED}↳ Curl Error %s${NC}\n" "$exit_code"
+            
+            # Print the last 4 lines of verbose log to show the specific handshake error
+            # We look for lines starting with '*' or '>' or '<' to filter out junk if any remains
+            echo "$output" | tail -n 4 | sed "s/^/         ${GRAY}/"
+        fi
+    done
+done
+print_line
+# Reset color just in case
+printf "${NC}"

build/lib/scripts/tor-check.sh

@@ -1,36 +0,0 @@
-#!/bin/bash
-
-fail=$(printf " [\033[31m fail \033[0m]")
-pass=$(printf " [\033[32m pass \033[0m]")
-
-onion_list=(
-    "Start9|http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion"
-    "Mempool|http://mempoolhqx4isw62xs7abwphsq7ldayuidyx2v2oethdhhj6mlo2r6ad.onion"
-    "DuckDuckGo|https://duckduckgogg42xjoc72x3sjasowoarfbgcmvfimaftt6twagswzczad.onion"
-    "Brave Search|https://search.brave4u7jddbv7cyviptqjc7jusxh72uik7zt6adtckl5f4nwy2v72qd.onion"
-)
-
-# Check if ~/.startos/tor-check.list exists and read its contents if available
-if [ -f ~/.startos/tor-check.list ]; then
-    while IFS= read -r line; do
-        # Check if the line starts with a #
-        if [[ ! "$line" =~ ^# ]]; then
-            onion_list+=("$line")
-        fi
-    done < ~/.startos/tor-check.list
-fi
-
-echo "Testing connection to Onion Pages ..."
-
-for data in "${onion_list[@]}"; do
-    name="${data%%|*}"
-    url="${data#*|}"
-    if curl --socks5-hostname localhost:9050 "$url" > /dev/null 2>&1; then
-        echo " ${pass}: $name ($url) "
-    else
-        echo " ${fail}: $name ($url) "
-    fi
-done
-
-echo
-echo "Done."

build/lib/scripts/upgrade

@@ -0,0 +1,82 @@
+#!/bin/bash
+
+set -e
+
+SOURCE_DIR="$(dirname $(realpath "${BASH_SOURCE[0]}"))"
+
+if [ "$UID" -ne 0 ]; then
+    >&2 echo 'Must be run as root'
+    exit 1
+fi
+
+if ! [ -f "$1" ]; then
+    >&2 echo "usage: $0 <SQUASHFS>"
+    exit 1
+fi
+
+echo 'Upgrading...'
+
+hash=$(b3sum $1 | head -c 32)
+if [ -n "$2" ] && [ "$hash" != "$CHECKSUM" ]; then
+    >&2 echo 'Checksum mismatch'
+    exit 2
+fi
+
+unsquashfs -f -d / $1 boot
+
+umount -R /media/startos/next 2> /dev/null || true
+umount /media/startos/upper 2> /dev/null || true
+umount /media/startos/lower 2> /dev/null || true
+
+mkdir -p /media/startos/upper
+mount -t tmpfs tmpfs /media/startos/upper
+mkdir -p /media/startos/lower /media/startos/upper/data /media/startos/upper/work /media/startos/next
+mount $1 /media/startos/lower
+mount -t overlay \
+      -olowerdir=/media/startos/lower,upperdir=/media/startos/upper/data,workdir=/media/startos/upper/work \
+	    overlay /media/startos/next
+
+mkdir -p /media/startos/next/run
+mkdir -p /media/startos/next/dev
+mkdir -p /media/startos/next/sys
+mkdir -p /media/startos/next/proc
+mkdir -p /media/startos/next/boot
+mkdir -p /media/startos/next/media/startos/root
+mount --bind /run /media/startos/next/run
+mount --bind /tmp /media/startos/next/tmp
+mount --bind /dev /media/startos/next/dev
+mount --bind /sys /media/startos/next/sys
+mount --bind /proc /media/startos/next/proc
+mount --bind /boot /media/startos/next/boot
+mount --bind /media/startos/root /media/startos/next/media/startos/root
+
+if mountpoint /boot/efi 2>&1 > /dev/null; then
+    mkdir -p /media/startos/next/boot/efi
+    mount --bind /boot/efi /media/startos/next/boot/efi
+fi
+
+if mountpoint /sys/firmware/efi/efivars 2>&1 > /dev/null; then
+    mount --bind /sys/firmware/efi/efivars /media/startos/next/sys/firmware/efi/efivars
+fi
+
+chroot /media/startos/next bash -e << "EOF"
+
+if [ -f /boot/grub/grub.cfg ]; then
+    grub-install --no-nvram /dev/$(eval $(lsblk -o MOUNTPOINT,PKNAME -P | grep 'MOUNTPOINT="/media/startos/root"') && echo $PKNAME)
+    update-grub
+fi
+
+EOF
+
+sync
+
+umount -Rl /media/startos/next
+umount /media/startos/upper
+umount /media/startos/lower
+
+mv $1 /media/startos/images/${hash}.rootfs
+ln -rsf /media/startos/images/${hash}.rootfs /media/startos/config/current.rootfs
+
+sync
+
+echo 'System upgrade complete. Reboot to apply changes...'

build/lib/scripts/wireguard-vps-proxy-setup

@@ -0,0 +1,555 @@
+#!/bin/bash
+
+# =============================================================================
+# Wireguard VPS Proxy Setup
+# =============================================================================
+#
+# This script automates the setup of a WireGuard VPN server on a remote VPS
+# for StartOS Clearnet functionality. It handles:
+#
+# 1. SSH key-based authentication setup
+# 2. Root access configuration (if needed)
+# 3. WireGuard server installation
+# 4. Configuration file generation and import
+#
+# Usage:
+#   wireguard-vps-proxy-setup [-h] [-i IP] [-u USERNAME] [-p PORT] [-k SSH_KEY]
+#
+# Options:
+#   -h    Show help message
+#   -i    VPS IP address
+#   -u    SSH username (default: root)
+#   -p    SSH port (default: 22)
+#   -k    Path to custom SSH private key
+#
+# Example:
+#   wireguard-vps-proxy-setup -i 110.18.1.1 -u debian
+#
+# Note: This script requires root privileges and will auto-elevate if needed.
+# =============================================================================
+
+# Colors for better output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[1;34m'
+YELLOW='\033[1;33m'
+NC='\033[0;37m' # No Color
+
+# --- Constants ---
+readonly WIREGUARD_INSTALL_URL="https://raw.githubusercontent.com/start9labs/wireguard-vps-proxy-setup/master/wireguard-install.sh"
+readonly SSH_KEY_DIR="/home/start9/.ssh"
+readonly SSH_KEY_NAME="id_ed25519"
+readonly SSH_PRIVATE_KEY="$SSH_KEY_DIR/$SSH_KEY_NAME"
+readonly SSH_PUBLIC_KEY="$SSH_PRIVATE_KEY.pub"
+
+# Store original arguments
+SCRIPT_ARGS=("$@")
+
+# --- Functions ---
+
+# Function to ensure script runs with root privileges by auto-elevating if needed
+check_root() {
+    if [[ "$EUID" -ne 0 ]]; then
+        exec sudo "$0" "${SCRIPT_ARGS[@]}"
+    fi
+    sudo chown -R start9:startos "$SSH_KEY_DIR"
+}
+
+# Function to print banner
+print_banner() {
+    echo -e "${BLUE}"
+    echo "================================================"
+    echo -e "     ${NC}Wireguard VPS Proxy Setup${BLUE}              "
+    echo "================================================"
+    echo -e "${NC}"
+}
+
+# Function to print usage
+print_usage() {
+    echo -e "Usage: $0 [-h] [-i IP] [-u USERNAME] [-p PORT] [-k SSH_KEY]"
+    echo "Options:"
+    echo "  -h    Show this help message"
+    echo "  -i    VPS IP address"
+    echo "  -u    SSH username (default: root)"
+    echo "  -p    SSH port (default: 22)"
+    echo "  -k    Path to the custom SSH private key (optional)"
+    echo "        If no key is provided, the default key '$SSH_PRIVATE_KEY' will be used."
+}
+
+# Function to display end message
+display_end_message() {
+    echo -e "\n${BLUE}------------------------------------------------------------------${NC}"
+    echo -e "${GREEN}Wireguard VPS Proxy server setup complete!${NC}"
+    echo -e "${BLUE}------------------------------------------------------------------${NC}"
+    echo -e "\n${GREEN}Clearnet functionality has been enabled via VPS (${VPS_IP})${NC}"
+    echo -e "\n${YELLOW}Next steps:${NC}"
+    echo -e "Visit https://docs.start9.com to complete the Clearnet setup"
+    echo -e "\n${BLUE}------------------------------------------------------------------${NC}"
+}
+
+# Function to validate IP address
+validate_ip() {
+    local ip=$1
+    # IPv4 validation
+    if [[ $ip =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
+        # Additional IPv4 validation to ensure each octet is <= 255
+        local IFS='.'
+        read -ra ADDR <<< "$ip"
+        for i in "${ADDR[@]}"; do
+            if [ "$i" -gt 255 ]; then
+                return 1
+            fi
+        done
+        return 0
+    # IPv6 validation
+    elif [[ $ip =~ ^([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){6}:[0-9a-fA-F]{1,4}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){5}(:[0-9a-fA-F]{1,4}){1,2}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){4}(:[0-9a-fA-F]{1,4}){1,3}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){3}(:[0-9a-fA-F]{1,4}){1,4}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){2}(:[0-9a-fA-F]{1,4}){1,5}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1}(:[0-9a-fA-F]{1,4}){1,6}$ ]] || \
+         [[ $ip =~ ^::([0-9a-fA-F]{1,4}:){0,6}[0-9a-fA-F]{1,4}$ ]] || \
+         [[ $ip =~ ^[0-9a-fA-F]{1,4}::([0-9a-fA-F]{1,4}:){0,5}[0-9a-fA-F]{1,4}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,4}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,3}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,2}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,1}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,7}:$ ]] || \
+         [[ $ip =~ ^::([0-9a-fA-F]{1,4}:){0,7}[0-9a-fA-F]{1,4}$ ]] || \
+         [[ $ip =~ ^[0-9a-fA-F]{1,4}::([0-9a-fA-F]{1,4}:){0,6}[0-9a-fA-F]{1,4}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,6}(:[0-9a-fA-F]{1,4}){1,1}$ ]] || \
+         [[ $ip =~ ^([0-9a-fA-F]{1,4}:){1,7}:$ ]] || \
+         [[ $ip =~ ^::$ ]]; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# Function for configuring SSH key authentication on remote server
+configure_ssh_key_auth() {
+    echo -e "${BLUE}Configuring SSH key authentication on remote server...${NC}"
+
+    ssh -i "$SSH_PRIVATE_KEY" -o StrictHostKeyChecking=no -p "$SSH_PORT" "$SSH_USER@$VPS_IP" '
+        # Check if PubkeyAuthentication is commented out
+        if grep -q "^#PubkeyAuthentication" /etc/ssh/sshd_config; then
+            sed -i "s/^#PubkeyAuthentication.*/PubkeyAuthentication yes/" /etc/ssh/sshd_config
+        # Check if PubkeyAuthentication exists but is not enabled
+        elif grep -q "^PubkeyAuthentication" /etc/ssh/sshd_config; then
+            sed -i "s/^PubkeyAuthentication.*/PubkeyAuthentication yes/" /etc/ssh/sshd_config
+        # Add PubkeyAuthentication if it doesnt exist
+        else
+            echo "PubkeyAuthentication yes" >> /etc/ssh/sshd_config
+        fi
+
+        # Enable root login
+        if grep -q "^#PermitRootLogin" /etc/ssh/sshd_config; then
+            sed -i "s/^#PermitRootLogin.*/PermitRootLogin yes/" /etc/ssh/sshd_config
+        elif grep -q "^PermitRootLogin" /etc/ssh/sshd_config; then
+            sed -i "s/^PermitRootLogin.*/PermitRootLogin yes/" /etc/ssh/sshd_config
+        else
+            echo "PermitRootLogin yes" >> /etc/ssh/sshd_config
+        fi
+
+        # Configure AuthorizedKeysFile if needed
+        if grep -q "^#AuthorizedKeysFile" /etc/ssh/sshd_config; then
+            sed -i "s/^#AuthorizedKeysFile.*/AuthorizedKeysFile     .ssh\/authorized_keys .ssh\/authorized_keys2/" /etc/ssh/sshd_config
+        elif ! grep -q "^AuthorizedKeysFile" /etc/ssh/sshd_config; then
+            echo "AuthorizedKeysFile     .ssh/authorized_keys .ssh/authorized_keys2" >> /etc/ssh/sshd_config
+        fi
+
+        # Reload SSH service
+        systemctl reload sshd
+    '
+}
+
+# Function to handle StartOS connection (download only)
+handle_startos_connection() {
+    echo -e "${BLUE}Fetching the WireGuard configuration file...${NC}"
+
+    # Fetch the client configuration file
+    config_file=$(ssh -i "$SSH_PRIVATE_KEY" -o StrictHostKeyChecking=no -p "$SSH_PORT" "$SSH_USER@$VPS_IP" 'ls -t ~/*.conf 2>/dev/null | head -n 1')
+    if [ -z "$config_file" ]; then
+        echo -e "${RED}Error: No WireGuard configuration file found on the remote server.${NC}"
+        return 1 # Exit with error
+    fi
+    CONFIG_NAME=$(basename "$config_file")
+
+    # Download the configuration file
+    if ! scp -i "$SSH_PRIVATE_KEY" -o StrictHostKeyChecking=no -P "$SSH_PORT" "$SSH_USER@$VPS_IP":~/"$CONFIG_NAME" ./; then
+        echo -e "${RED}Error: Failed to download the WireGuard configuration file.${NC}"
+        return 1 # Exit with error
+    fi
+    echo -e "${GREEN}WireGuard configuration file '$CONFIG_NAME' downloaded successfully.${NC}"
+    return 0
+}
+
+# Function to import WireGuard configuration
+import_wireguard_config() {
+    local config_name="$1"
+    if [ -z "$config_name" ]; then
+        echo -e "${RED}Error: Configuration file name is missing.${NC}"
+        return 1
+    fi
+
+    local connection_name=$(basename "$config_name" .conf) #Extract base name without extension
+
+    # Check if the connection with same name already exists
+    if nmcli connection show --active | grep -q "^${connection_name}\s"; then
+        read -r -p "A connection with the name '$connection_name' already exists. Do you want to override it? (y/N): " answer
+        if [[ "$answer" =~ ^[Yy]$ ]]; then
+            nmcli connection delete "$connection_name"
+            if [ $? -ne 0 ]; then
+                echo -e "${RED}Error: Failed to delete existing connection '$connection_name'.${NC}"
+                return 1
+            fi
+            # Import if user chose to override or if connection did not exist
+            if ! nmcli connection import type wireguard file "$config_name"; then
+                echo -e "${RED}Error: Failed to import the WireGuard configuration using NetworkManager.${NC}"
+                rm -f "$config_name"
+                return 1
+            fi
+            echo -e "${GREEN}WireGuard configuration '$config_name' has been imported to NetworkManager.${NC}"
+            rm -f "$config_name"
+            display_end_message
+        else
+            echo -e "${BLUE}Skipping import of the WireGuard configuration.${NC}"
+            rm -f "$config_name"
+            return 0
+        fi
+    else
+        # Import if connection did not exist
+        if command -v nmcli &>/dev/null; then
+            if ! nmcli connection import type wireguard file "$config_name"; then
+                echo -e "${RED}Error: Failed to import the WireGuard configuration using NetworkManager.${NC}"
+                rm -f "$config_name"
+                return 1
+            fi
+            echo -e "${GREEN}WireGuard configuration '$config_name' has been imported to NetworkManager.${NC}"
+            rm -f "$config_name"
+            display_end_message
+        else
+            echo -e "${YELLOW}Warning: NetworkManager 'nmcli' not found. Configuration file '$config_name' saved in current directory.${NC}"
+            echo -e "${YELLOW}Import the configuration to your StartOS manually by going to NetworkManager or using wg-quick up <config> command${NC}"
+        fi
+    fi
+    return 0
+}
+
+# Function to download the install script
+download_install_script() {
+    echo -e "${BLUE}Downloading latest WireGuard install script...${NC}"
+    # Download the script
+    if ! curl -sSf "$WIREGUARD_INSTALL_URL" -o wireguard-install.sh; then
+        echo -e "${RED}Failed to download WireGuard installation script.${NC}"
+        return 1
+    fi
+    chmod +x wireguard-install.sh
+    if [ $? -ne 0 ]; then
+        echo -e "${RED}Failed to chmod +x wireguard install script.${NC}"
+        return 1
+    fi
+    echo -e "${GREEN}WireGuard install script downloaded successfully!${NC}"
+    return 0
+}
+
+# Function to install WireGuard
+install_wireguard() {
+    echo -e "\n${BLUE}Installing WireGuard...${NC}"
+
+    # Check if install script exist
+    if [ ! -f "wireguard-install.sh" ]; then
+        echo -e "${RED}WireGuard install script is missing. Did it failed to download?${NC}"
+        return 1
+    fi
+
+    # Run the remote install script and let it complete
+    if ! ssh -o ConnectTimeout=60 -i "$SSH_PRIVATE_KEY" -o StrictHostKeyChecking=no -p "$SSH_PORT" -t "$SSH_USER@$VPS_IP" "bash -c 'export TERM=xterm-256color; export STARTOS_HOSTNAME=clearnet; bash ~/wireguard-install.sh'"; then
+        echo -e "${RED}WireGuard installation failed on remote server.${NC}"
+        return 1
+    fi
+
+    # Test if wireguard installed
+    if ! ssh -q -o BatchMode=yes -o ConnectTimeout=5 -i "$SSH_PRIVATE_KEY" -o StrictHostKeyChecking=no -p "$SSH_PORT" "$SSH_USER@$VPS_IP" "test -f /etc/wireguard/wg0.conf"; then
+        echo -e "\n${RED}WireGuard installation failed because /etc/wireguard/wg0.conf is missing, which means the script removed it.${NC}"
+        return 1
+    fi
+
+    echo -e "\n${GREEN}WireGuard installation completed successfully!${NC}"
+    return 0
+}
+
+# Function to enable root login via SSH
+enable_root_login() {
+    echo -e "${BLUE}Checking and configuring root SSH access...${NC}"
+    
+    # Try to modify sshd config using sudo
+    if ! ssh -i "$SSH_PRIVATE_KEY" -o StrictHostKeyChecking=no -p "$SSH_PORT" "$SSH_USER@$VPS_IP" '
+        # Check if we can use sudo without password
+        if ! sudo -n true 2>/dev/null; then
+            echo -e "\033[1;33mNOTE: You may be prompted for your sudo password.\033[0m"
+        fi
+        
+        # Check if user is in sudo group
+        if ! groups | grep -q sudo; then
+            echo -e "\033[1;31mError: Your user is not in the sudo group. Root access cannot be configured.\033[0m"
+            exit 1
+        fi
+        
+        # Backup sshd config
+        sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak
+        
+        # Enable root login with SSH keys only
+        if sudo grep -q "^PermitRootLogin" /etc/ssh/sshd_config; then
+            sudo sed -i "s/^PermitRootLogin.*/PermitRootLogin prohibit-password/" /etc/ssh/sshd_config
+        else
+            echo "PermitRootLogin prohibit-password" | sudo tee -a /etc/ssh/sshd_config
+        fi
+        
+        # Ensure password authentication is disabled
+        if sudo grep -q "^PasswordAuthentication" /etc/ssh/sshd_config; then
+            sudo sed -i "s/^PasswordAuthentication.*/PasswordAuthentication no/" /etc/ssh/sshd_config
+        else
+            echo "PasswordAuthentication no" | sudo tee -a /etc/ssh/sshd_config
+        fi
+        
+        # Set up root SSH directory and keys
+        echo -e "\033[1;33mSetting up root SSH access...\033[0m"
+        sudo mkdir -p /root/.ssh
+        sudo cp ~/.ssh/authorized_keys /root/.ssh/
+        sudo chown -R root:root /root/.ssh
+        sudo chmod 700 /root/.ssh
+        sudo chmod 600 /root/.ssh/authorized_keys
+        
+        # Reload SSH service
+        sudo systemctl reload sshd
+        
+        # Verify the changes
+        if ! sudo grep -q "^PermitRootLogin prohibit-password" /etc/ssh/sshd_config; then
+            echo -e "\033[1;31mError: Failed to verify root login configuration.\033[0m"
+            exit 1
+        fi
+        
+        # Test root SSH access
+        if ! sudo -n true 2>/dev/null; then
+            echo -e "\033[1;33mNOTE: Please try to log in as root now using your SSH key.\033[0m"
+            echo -e "\033[1;33mIf successful, run this script again without the -u parameter.\033[0m"
+        else
+            echo -e "\033[1;32mRoot SSH access has been configured successfully!\033[0m"
+        fi
+    '; then
+        echo -e "${RED}Failed to configure root SSH access.${NC}"
+        return 1
+    fi
+    
+    echo -e "${GREEN}Root SSH access has been configured successfully!${NC}"
+    echo -e "${YELLOW}Please try to log in as root now using your SSH key. If successful, run this script again without the -u parameter.${NC}"
+    return 0
+}
+
+# --- Main Script ---
+# Initialize variables
+VPS_IP=""
+SSH_USER="root"
+SSH_PORT="22"
+CUSTOM_SSH_KEY=""
+CONFIG_NAME=""
+
+# Check if the script is run as root before anything else
+check_root
+
+# Print banner
+print_banner
+
+# Parse command line arguments
+while getopts "hi:u:p:k:" opt; do
+    case $opt in
+    h)
+        print_usage
+        exit 0
+        ;;
+    i)
+        VPS_IP=$OPTARG
+        ;;
+    u)
+        SSH_USER=$OPTARG
+        ;;
+    p)
+        SSH_PORT=$OPTARG
+        ;;
+    k)
+        CUSTOM_SSH_KEY=$OPTARG
+        ;;
+    \?)
+        echo "Invalid option: -$OPTARG" >&2
+        print_usage
+        exit 1
+        ;;
+    esac
+done
+
+# Check if custom SSH key is passed and update the private key variable
+if [ -n "$CUSTOM_SSH_KEY" ]; then
+    if [ ! -f "$CUSTOM_SSH_KEY" ]; then
+        echo -e "${RED}Custom SSH key '$CUSTOM_SSH_KEY' not found.${NC}"
+        exit 1
+    fi
+    SSH_PRIVATE_KEY="$CUSTOM_SSH_KEY"
+    SSH_PUBLIC_KEY="$CUSTOM_SSH_KEY.pub"
+else
+    # Use default StartOS SSH key
+    if [ ! -f "$SSH_PRIVATE_KEY" ]; then
+        echo -e "${RED}No SSH key found at default location '$SSH_PRIVATE_KEY'. Please ensure StartOS SSH keys are properly configured.${NC}"
+        exit 1
+    fi
+fi
+
+if [ ! -f "$SSH_PUBLIC_KEY" ]; then
+    echo -e "${RED}Public key '$SSH_PUBLIC_KEY' not found. Please ensure both private and public keys exist.${NC}"
+    exit 1
+fi
+
+# If VPS_IP is not provided via command line, ask for it
+if [ -z "$VPS_IP" ]; then
+    while true; do
+        echo -n "Please enter your VPS IP address: "
+        read VPS_IP
+        if validate_ip "$VPS_IP"; then
+            break
+        else
+            echo -e "${RED}Invalid IP address format. Please try again.${NC}"
+        fi
+    done
+fi
+
+# Confirm SSH connection details
+echo -e "\n${GREEN}Connection details:${NC}"
+echo "VPS IP: $VPS_IP"
+echo "SSH User: $SSH_USER"
+echo "SSH Port: $SSH_PORT"
+
+echo -e "\n${GREEN}Proceeding with SSH key-based authentication...${NC}\n"
+
+# Copy SSH public key to the remote server
+if ! ssh-copy-id -i "$SSH_PUBLIC_KEY" -o StrictHostKeyChecking=no -p "$SSH_PORT" "$SSH_USER@$VPS_IP"; then
+    echo -e "${RED}Failed to copy SSH key to the remote server. Please ensure you have correct credentials.${NC}"
+    exit 1
+fi
+
+echo -e "${GREEN}SSH key-based authentication configured successfully!${NC}"
+
+# Test SSH connection using key-based authentication
+echo -e "\nTesting SSH connection with key-based authentication..."
+if ! ssh -q -o BatchMode=yes -o ConnectTimeout=5 -i "$SSH_PRIVATE_KEY" -o StrictHostKeyChecking=no -p "$SSH_PORT" "$SSH_USER@$VPS_IP" 'exit'; then
+    echo -e "${RED}SSH connection test failed. Please check your credentials and try again.${NC}"
+    exit 1
+fi
+
+# If we're connecting as a non-root user, set up root access first
+if [ "$SSH_USER" != "root" ]; then
+    echo -e "\n${YELLOW}You are connecting as a non-root user. This script needs to enable root SSH access.${NC}"
+    echo -e "${YELLOW}This is a one-time setup that will allow direct root login for WireGuard installation.${NC}"
+    echo -n -e "${YELLOW}Would you like to proceed? (y/N): ${NC}"
+    read -r answer
+    
+    if [[ "$answer" =~ ^[Yy]$ ]]; then
+        if enable_root_login; then
+            echo -e "\n${BLUE}------------------------------------------------------------------${NC}"
+            echo -e "${GREEN}Root SSH access has been configured successfully!${NC}"
+            echo -e "${YELLOW}Please run this script again without the -u parameter to continue setup.${NC}"
+            echo -e "${BLUE}------------------------------------------------------------------${NC}"
+            exit 0
+        else
+            echo -e "${RED}Failed to configure root SSH access. Please check your sudo privileges and try again.${NC}"
+            exit 1
+        fi
+    else
+        echo -e "\n${BLUE}------------------------------------------------------------------${NC}"
+        echo -e "${YELLOW}To manually configure SSH for root access:${NC}"
+        echo -e "\n   ${YELLOW}1. Connect to your VPS and edit sshd_config:${NC}"
+        echo "      sudo nano /etc/ssh/sshd_config"
+        echo -e "\n   ${YELLOW}2. Find and uncomment or add these lines:${NC}"
+        echo "      PubkeyAuthentication yes"
+        echo "      PermitRootLogin yes"
+        echo "      AuthorizedKeysFile     .ssh/authorized_keys .ssh/authorized_keys2"
+        echo -e "\n   ${YELLOW}3. Restart the SSH service:${NC}"
+        echo "      sudo systemctl restart sshd"
+        echo -e "\n   ${YELLOW}4. Copy your SSH key to root user:${NC}"
+        echo "      sudo mkdir -p /root/.ssh"
+        echo "      sudo cp ~/.ssh/authorized_keys /root/.ssh/"
+        echo "      sudo chown -R root:root /root/.ssh"
+        echo "      sudo chmod 700 /root/.ssh"
+        echo "      sudo chmod 600 /root/.ssh/authorized_keys"
+        echo -e "${BLUE}------------------------------------------------------------------${NC}"
+        echo -e "\n${YELLOW}After completing these steps, run this script again without the -u parameter.${NC}"
+        exit 1
+    fi
+fi
+
+# Check if root login is permitted when connecting as root
+if [ "$SSH_USER" = "root" ]; then
+    # Check for both "yes" and "prohibit-password" as valid root login settings
+    if ! ssh -q -o BatchMode=yes -o ConnectTimeout=5 -i "$SSH_PRIVATE_KEY" -o StrictHostKeyChecking=no -p "$SSH_PORT" "$SSH_USER@$VPS_IP" 'grep -q "^PermitRootLogin.*\(yes\|prohibit-password\)" /etc/ssh/sshd_config'; then
+        echo -e "\n${RED}Root SSH login is not enabled on your VPS.${NC}"
+        echo -e "\n${YELLOW}Would you like this script to automatically enable root SSH access? (y/N):${NC} "
+        read -r answer
+
+        if [[ "$answer" =~ ^[Yy]$ ]]; then
+            configure_ssh_key_auth
+        else
+            echo -e "\n${BLUE}------------------------------------------------------------------${NC}"
+            echo -e "${YELLOW}To manually configure SSH for root access:${NC}"
+            echo -e "\n   ${YELLOW}1. Connect to your VPS and edit sshd_config:${NC}"
+            echo "      sudo nano /etc/ssh/sshd_config"
+            echo -e "\n   ${YELLOW}2. Find and uncomment or add these lines:${NC}"
+            echo "      PubkeyAuthentication yes"
+            echo "      PermitRootLogin prohibit-password"
+            echo "      AuthorizedKeysFile     .ssh/authorized_keys .ssh/authorized_keys2"
+            echo -e "\n   ${YELLOW}3. Restart the SSH service:${NC}"
+            echo "      sudo systemctl restart sshd"
+            echo -e "${BLUE}------------------------------------------------------------------${NC}"
+            echo -e "\n${YELLOW}Please enable root SSH access and run this script again.${NC}"
+            exit 1
+        fi
+    fi
+fi
+
+echo -e "${GREEN}SSH connection successful with key-based authentication!${NC}"
+
+# Download the WireGuard install script locally
+if ! download_install_script; then
+    echo -e "${RED}Failed to download the latest install script. Exiting...${NC}"
+    exit 1
+fi
+
+# Upload the install script to the remote server
+if ! scp -i "$SSH_PRIVATE_KEY" -o StrictHostKeyChecking=no -P "$SSH_PORT" wireguard-install.sh "$SSH_USER@$VPS_IP":~/; then
+    echo -e "${RED}Failed to upload WireGuard install script to the remote server.${NC}"
+    exit 1
+fi
+
+# Install WireGuard on remote server using the downloaded script
+if ! install_wireguard; then
+    echo -e "${RED}WireGuard installation failed.${NC}"
+    exit 1
+fi
+
+# Remove the local install script
+rm wireguard-install.sh >/dev/null 2>&1
+
+# Handle the StartOS config (download)
+if ! handle_startos_connection; then
+    echo -e "${RED}StartOS configuration download failed!${NC}"
+    exit 1
+fi
+
+# Import the configuration
+if ! import_wireguard_config "$CONFIG_NAME"; then
+    echo -e "${RED}StartOS configuration import failed or skipped!${NC}"
+fi

build/manage-release.sh

@@ -0,0 +1,364 @@
+#!/bin/bash
+
+set -e
+
+REPO="Start9Labs/start-os"
+REGISTRY="https://alpha-registry-x.start9.com"
+S3_BUCKET="s3://startos-images"
+S3_CDN="https://startos-images.nyc3.cdn.digitaloceanspaces.com"
+START9_GPG_KEY="2D63C217"
+
+ARCHES="aarch64 aarch64-nonfree aarch64-nvidia riscv64 riscv64-nonfree x86_64 x86_64-nonfree x86_64-nvidia"
+CLI_ARCHES="aarch64 riscv64 x86_64"
+
+parse_run_id() {
+    local val="$1"
+    if [[ "$val" =~ /actions/runs/([0-9]+) ]]; then
+        echo "${BASH_REMATCH[1]}"
+    else
+        echo "$val"
+    fi
+}
+
+require_version() {
+    if [ -z "${VERSION:-}" ]; then
+        read -rp "VERSION: " VERSION
+        if [ -z "$VERSION" ]; then
+            >&2 echo '$VERSION required'
+            exit 2
+        fi
+    fi
+}
+
+release_dir() {
+    echo "$HOME/Downloads/v$VERSION"
+}
+
+ensure_release_dir() {
+    local dir
+    dir=$(release_dir)
+    if [ "$CLEAN" = "1" ]; then
+        rm -rf "$dir"
+    fi
+    mkdir -p "$dir"
+    cd "$dir"
+}
+
+enter_release_dir() {
+    local dir
+    dir=$(release_dir)
+    if [ ! -d "$dir" ]; then
+        >&2 echo "Release directory $dir does not exist. Run 'download' or 'pull' first."
+        exit 1
+    fi
+    cd "$dir"
+}
+
+cli_target_for() {
+    local arch=$1 os=$2
+    local pair="${arch}-${os}"
+    if [ "$pair" = "riscv64-linux" ]; then
+        echo "riscv64gc-unknown-linux-musl"
+    elif [ "$pair" = "riscv64-macos" ]; then
+        return 1
+    elif [ "$os" = "linux" ]; then
+        echo "${arch}-unknown-linux-musl"
+    elif [ "$os" = "macos" ]; then
+        echo "${arch}-apple-darwin"
+    fi
+}
+
+release_files() {
+    for file in *.iso *.squashfs *.deb; do
+        [ -f "$file" ] && echo "$file"
+    done
+    for file in start-cli_*; do
+        [[ "$file" == *.asc ]] && continue
+        [ -f "$file" ] && echo "$file"
+    done
+}
+
+resolve_gh_user() {
+    GH_USER=${GH_USER:-$(gh api user -q .login 2>/dev/null || true)}
+    GH_GPG_KEY=$(git config user.signingkey 2>/dev/null || true)
+}
+
+# --- Subcommands ---
+
+cmd_download() {
+    require_version
+
+    if [ -z "${RUN_ID:-}" ]; then
+        read -rp "RUN_ID (OS images, leave blank to skip): " RUN_ID
+    fi
+    RUN_ID=$(parse_run_id "${RUN_ID:-}")
+
+    if [ -z "${ST_RUN_ID:-}" ]; then
+        read -rp "ST_RUN_ID (start-tunnel, leave blank to skip): " ST_RUN_ID
+    fi
+    ST_RUN_ID=$(parse_run_id "${ST_RUN_ID:-}")
+
+    if [ -z "${CLI_RUN_ID:-}" ]; then
+        read -rp "CLI_RUN_ID (start-cli, leave blank to skip): " CLI_RUN_ID
+    fi
+    CLI_RUN_ID=$(parse_run_id "${CLI_RUN_ID:-}")
+
+    ensure_release_dir
+
+    if [ -n "$RUN_ID" ]; then
+        for arch in $ARCHES; do
+            while ! gh run download -R $REPO "$RUN_ID" -n "$arch.squashfs" -D "$(pwd)"; do sleep 1; done
+        done
+        for arch in $ARCHES; do
+            while ! gh run download -R $REPO "$RUN_ID" -n "$arch.iso" -D "$(pwd)"; do sleep 1; done
+        done
+    fi
+
+    if [ -n "$ST_RUN_ID" ]; then
+        for arch in $CLI_ARCHES; do
+            while ! gh run download -R $REPO "$ST_RUN_ID" -n "start-tunnel_$arch.deb" -D "$(pwd)"; do sleep 1; done
+        done
+    fi
+
+    if [ -n "$CLI_RUN_ID" ]; then
+        for arch in $CLI_ARCHES; do
+            for os in linux macos; do
+                local target
+                target=$(cli_target_for "$arch" "$os") || continue
+                while ! gh run download -R $REPO "$CLI_RUN_ID" -n "start-cli_$target" -D "$(pwd)"; do sleep 1; done
+                mv start-cli "start-cli_${arch}-${os}"
+            done
+        done
+    fi
+}
+
+cmd_pull() {
+    require_version
+    ensure_release_dir
+
+    echo "Downloading release assets from tag v$VERSION..."
+
+    # Download debs and CLI binaries from the GH release
+    for file in $(gh release view -R $REPO "v$VERSION" --json assets -q '.assets[].name' | grep -E '\.(deb)$|^start-cli_'); do
+        gh release download -R $REPO "v$VERSION" -p "$file" -D "$(pwd)" --clobber
+    done
+
+    # Download ISOs and squashfs from S3 CDN
+    for arch in $ARCHES; do
+        for ext in squashfs iso; do
+            # Get the actual filename from the GH release asset list or body
+            local filename
+            filename=$(gh release view -R $REPO "v$VERSION" --json assets -q ".assets[].name" | grep "_${arch}\\.${ext}$" || true)
+            if [ -z "$filename" ]; then
+                filename=$(gh release view -R $REPO "v$VERSION" --json body -q .body | grep -oP "[^ ]*_${arch}\\.${ext}" | head -1 || true)
+            fi
+            if [ -n "$filename" ]; then
+                echo "Downloading $filename from S3..."
+                curl -fSL -o "$filename" "$S3_CDN/v$VERSION/$filename"
+            fi
+        done
+    done
+}
+
+cmd_register() {
+    require_version
+    enter_release_dir
+    start-cli --registry=$REGISTRY registry os version add "$VERSION" "v$VERSION" '' ">=0.3.5 <=$VERSION"
+}
+
+cmd_upload() {
+    require_version
+    enter_release_dir
+
+    for file in $(release_files); do
+        case "$file" in
+            *.iso|*.squashfs)
+                s3cmd put -P "$file" "$S3_BUCKET/v$VERSION/$file"
+                ;;
+            *)
+                gh release upload -R $REPO "v$VERSION" "$file"
+                ;;
+        esac
+    done
+}
+
+cmd_index() {
+    require_version
+    enter_release_dir
+
+    for arch in $ARCHES; do
+        for file in *_"$arch".squashfs *_"$arch".iso; do
+            start-cli --registry=$REGISTRY registry os asset add --platform="$arch" --version="$VERSION" "$file" "$S3_CDN/v$VERSION/$file"
+        done
+    done
+}
+
+cmd_sign() {
+    require_version
+    enter_release_dir
+    resolve_gh_user
+
+    for file in $(release_files); do
+        gpg -u $START9_GPG_KEY --detach-sign --armor -o "${file}.start9.asc" "$file"
+        if [ -n "$GH_USER" ] && [ -n "$GH_GPG_KEY" ]; then
+            gpg -u "$GH_GPG_KEY" --detach-sign --armor -o "${file}.${GH_USER}.asc" "$file"
+        fi
+    done
+
+    gpg --export -a $START9_GPG_KEY > start9.key.asc
+    if [ -n "$GH_USER" ] && [ -n "$GH_GPG_KEY" ]; then
+        gpg --export -a "$GH_GPG_KEY" > "${GH_USER}.key.asc"
+    else
+        >&2 echo 'Warning: could not determine GitHub user or GPG signing key, skipping personal signature'
+    fi
+    tar -czvf signatures.tar.gz *.asc
+
+    gh release upload -R $REPO "v$VERSION" signatures.tar.gz --clobber
+}
+
+cmd_cosign() {
+    require_version
+    enter_release_dir
+    resolve_gh_user
+
+    if [ -z "$GH_USER" ] || [ -z "$GH_GPG_KEY" ]; then
+        >&2 echo 'Error: could not determine GitHub user or GPG signing key'
+        >&2 echo "Set GH_USER and/or configure git user.signingkey"
+        exit 1
+    fi
+
+    echo "Downloading existing signatures..."
+    gh release download -R $REPO "v$VERSION" -p "signatures.tar.gz" -D "$(pwd)" --clobber
+    tar -xzf signatures.tar.gz
+
+    echo "Adding personal signatures as $GH_USER..."
+    for file in $(release_files); do
+        gpg -u "$GH_GPG_KEY" --detach-sign --armor -o "${file}.${GH_USER}.asc" "$file"
+    done
+
+    gpg --export -a "$GH_GPG_KEY" > "${GH_USER}.key.asc"
+
+    echo "Re-packing signatures..."
+    tar -czvf signatures.tar.gz *.asc
+
+    gh release upload -R $REPO "v$VERSION" signatures.tar.gz --clobber
+    echo "Done. Personal signatures for $GH_USER added to v$VERSION."
+}
+
+cmd_notes() {
+    require_version
+    enter_release_dir
+
+    cat << EOF
+# ISO Downloads
+
+- [x86_64/AMD64]($S3_CDN/v$VERSION/$(ls *_x86_64-nonfree.iso))
+- [x86_64/AMD64 + NVIDIA]($S3_CDN/v$VERSION/$(ls *_x86_64-nvidia.iso))
+- [x86_64/AMD64-slim (FOSS-only)]($S3_CDN/v$VERSION/$(ls *_x86_64.iso) "Without proprietary software or drivers")
+- [aarch64/ARM64]($S3_CDN/v$VERSION/$(ls *_aarch64-nonfree.iso))
+- [aarch64/ARM64 + NVIDIA]($S3_CDN/v$VERSION/$(ls *_aarch64-nvidia.iso))
+- [aarch64/ARM64-slim (FOSS-Only)]($S3_CDN/v$VERSION/$(ls *_aarch64.iso) "Without proprietary software or drivers")
+- [RISCV64 (RVA23)]($S3_CDN/v$VERSION/$(ls *_riscv64-nonfree.iso))
+- [RISCV64 (RVA23)-slim (FOSS-only)]($S3_CDN/v$VERSION/$(ls *_riscv64.iso) "Without proprietary software or drivers")
+
+EOF
+    cat << 'EOF'
+# StartOS Checksums
+
+## SHA-256
+```
+EOF
+    sha256sum *.iso *.squashfs
+    cat << 'EOF'
+```
+
+## BLAKE-3
+```
+EOF
+    b3sum *.iso *.squashfs
+    cat << 'EOF'
+```
+
+# Start-Tunnel Checksums
+
+## SHA-256
+```
+EOF
+    sha256sum start-tunnel*.deb
+    cat << 'EOF'
+```
+
+## BLAKE-3
+```
+EOF
+    b3sum start-tunnel*.deb
+    cat << 'EOF'
+```
+
+# start-cli Checksums
+
+## SHA-256
+```
+EOF
+    release_files | grep '^start-cli_' | xargs sha256sum
+    cat << 'EOF'
+```
+
+## BLAKE-3
+```
+EOF
+    release_files | grep '^start-cli_' | xargs b3sum
+    cat << 'EOF'
+```
+EOF
+}
+
+cmd_full_release() {
+    cmd_download
+    cmd_register
+    cmd_upload
+    cmd_index
+    cmd_sign
+    cmd_notes
+}
+
+usage() {
+    cat << 'EOF'
+Usage: manage-release.sh <subcommand>
+
+Subcommands:
+  download      Download artifacts from GitHub Actions runs
+                Requires: RUN_ID, ST_RUN_ID, CLI_RUN_ID (any combination)
+  pull          Download an existing release from the GH tag and S3
+  register      Register the version in the Start9 registry
+  upload        Upload artifacts to GitHub Releases and S3
+  index         Add assets to the registry index
+  sign          Sign all artifacts with Start9 org key (+ personal key if available)
+                and upload signatures.tar.gz
+  cosign        Add personal GPG signature to an existing release's signatures
+                (requires 'pull' first so you can verify assets before signing)
+  notes         Print release notes with download links and checksums
+  full-release  Run: download → register → upload → index → sign → notes
+
+Environment variables:
+  VERSION     (required) Release version
+  RUN_ID      GitHub Actions run ID for OS images (download subcommand)
+  ST_RUN_ID   GitHub Actions run ID for start-tunnel (download subcommand)
+  CLI_RUN_ID  GitHub Actions run ID for start-cli (download subcommand)
+  GH_USER     Override GitHub username (default: autodetected via gh cli)
+  CLEAN       Set to 1 to wipe and recreate the release directory
+EOF
+}
+
+case "${1:-}" in
+    download) cmd_download ;;
+    pull)     cmd_pull ;;
+    register) cmd_register ;;
+    upload)   cmd_upload ;;
+    index)    cmd_index ;;
+    sign)     cmd_sign ;;
+    cosign)   cmd_cosign ;;
+    notes)    cmd_notes ;;
+    full-release) cmd_full_release ;;
+    *)            usage; exit 1 ;;
+esac

build/os-compat/buildenv.Dockerfile

@@ -0,0 +1,25 @@
+FROM debian:trixie
+
+RUN apt-get update && \
+    apt-get install -y \
+    ca-certificates \
+    curl \
+    gpg \
+    build-essential \
+    sed \
+    grep \
+    gawk \
+    jq \
+    gzip \
+    brotli \
+    squashfs-tools \
+    git \
+    rsync \
+    b3sum \
+    sudo \
+    nodejs
+
+RUN git config --global --add safe.directory /root/start-os
+
+RUN mkdir -p /root/start-os
+WORKDIR /root/start-os

build/os-compat/run-compat.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+pwd=$(pwd)
+
+cd "$(dirname "${BASH_SOURCE[0]}")/../.."
+
+set -e
+
+rel_pwd="${pwd#"$(pwd)"}"
+
+COMPAT_ARCH=$(uname -m)
+
+platform=linux/$COMPAT_ARCH
+
+case $COMPAT_ARCH in
+    x86_64)
+        platform=linux/amd64;;
+    aarch64)
+        platform=linux/arm64;;
+esac
+
+if [ "$FORCE_COMPAT" = 1 ] || ( [ "$REQUIRES" = "linux" ] && [ "$(uname -s)" != "Linux" ] ) || ( [ "$REQUIRES" = "debian" ] && ! which dpkg > /dev/null ); then
+    if tty -s; then
+        USE_TTY="-it"
+    fi
+
+    docker run $USE_TTY --platform=$platform -eARCH -eENVIRONMENT -ePLATFORM -eGIT_BRANCH_AS_HASH -ePROJECT -eDEPENDS -eCONFLICTS -w "/root/start-os${rel_pwd}" --rm -v "$(pwd):/root/start-os" start9/build-env $@
+else 
+    exec $@
+fi

build/raspberrypi/make-image.sh

@@ -1,87 +0,0 @@
-#!/bin/bash
-
-set -e
-
-function partition_for () {
-    if [[ "$1" =~ [0-9]+$ ]]; then
-        echo "$1p$2"
-    else
-        echo "$1$2"
-    fi
-}
-
-VERSION=$(cat VERSION.txt)
-ENVIRONMENT=$(cat ENVIRONMENT.txt)
-GIT_HASH=$(cat GIT_HASH.txt | head -c 7)
-DATE=$(date +%Y%m%d)
-
-ROOT_PART_END=7217792
-
-VERSION_FULL="$VERSION-$GIT_HASH"
-
-if [ -n "$ENVIRONMENT" ]; then
-  VERSION_FULL="$VERSION_FULL~$ENVIRONMENT"
-fi
-
-TARGET_NAME=startos-${VERSION_FULL}-${DATE}_raspberrypi.img
-TARGET_SIZE=$[($ROOT_PART_END+1)*512]
-
-rm -f $TARGET_NAME
-truncate -s $TARGET_SIZE $TARGET_NAME
-(
-    echo o
-    echo x
-    echo i
-    echo "0xcb15ae4d"
-    echo r
-    echo n
-    echo p
-    echo 1
-    echo 2048
-    echo 526335
-    echo t
-    echo c
-    echo n
-    echo p
-    echo 2
-    echo 526336
-    echo $ROOT_PART_END
-    echo a
-    echo 1
-    echo w
-) | fdisk $TARGET_NAME
-OUTPUT_DEVICE=$(sudo losetup --show -fP $TARGET_NAME)
-sudo mkfs.ext4 `partition_for ${OUTPUT_DEVICE} 2`
-sudo mkfs.vfat `partition_for ${OUTPUT_DEVICE} 1`
-
-TMPDIR=$(mktemp -d)
-
-sudo mount `partition_for ${OUTPUT_DEVICE} 2` $TMPDIR
-sudo mkdir $TMPDIR/boot
-sudo mount `partition_for ${OUTPUT_DEVICE} 1` $TMPDIR/boot
-sudo unsquashfs -f -d $TMPDIR startos.raspberrypi.squashfs
-REAL_GIT_HASH=$(cat $TMPDIR/usr/lib/startos/GIT_HASH.txt)
-REAL_VERSION=$(cat $TMPDIR/usr/lib/startos/VERSION.txt)
-REAL_ENVIRONMENT=$(cat $TMPDIR/usr/lib/startos/ENVIRONMENT.txt)
-sudo sed -i 's| boot=embassy| init=/usr/lib/startos/scripts/init_resize\.sh|' $TMPDIR/boot/cmdline.txt
-sudo cp ./build/raspberrypi/fstab $TMPDIR/etc/
-sudo cp ./build/raspberrypi/init_resize.sh $TMPDIR/usr/lib/startos/scripts/init_resize.sh
-sudo umount $TMPDIR/boot
-sudo umount $TMPDIR
-sudo losetup -d $OUTPUT_DEVICE
-
-if [ "$ALLOW_VERSION_MISMATCH" != 1 ]; then
-    if [ "$(cat GIT_HASH.txt)" != "$REAL_GIT_HASH" ]; then
-        >&2 echo "startos.raspberrypi.squashfs GIT_HASH.txt mismatch"
-        >&2 echo "expected $REAL_GIT_HASH (dpkg) found $(cat GIT_HASH.txt) (repo)"
-        exit 1
-    fi
-    if [ "$(cat VERSION.txt)" != "$REAL_VERSION" ]; then
-        >&2 echo "startos.raspberrypi.squashfs VERSION.txt mismatch"
-        exit 1
-    fi
-    if [ "$(cat ENVIRONMENT.txt)" != "$REAL_ENVIRONMENT" ]; then
-        >&2 echo "startos.raspberrypi.squashfs ENVIRONMENT.txt mismatch"
-        exit 1
-    fi
-fi

check-environment.sh

@@ -1,8 +0,0 @@
-#!/bin/bash
-
-if ! [ -f ./ENVIRONMENT.txt ] || [ "$(cat ./ENVIRONMENT.txt)" != "$ENVIRONMENT" ]; then
-    >&2 echo "Updating ENVIRONMENT.txt to \"$ENVIRONMENT\""
-    echo -n "$ENVIRONMENT" > ./ENVIRONMENT.txt
-fi
-
-echo -n ./ENVIRONMENT.txt

check-git-hash.sh

@@ -1,13 +0,0 @@
-#!/bin/bash
-
-if [ "$GIT_BRANCH_AS_HASH" != 1 ]; then
-    GIT_HASH="$(git describe --always --abbrev=40 --dirty=-modified)"
-else
-    GIT_HASH="@$(git rev-parse --abbrev-ref HEAD)"
-fi
-
-if ! [ -f ./GIT_HASH.txt ] || [ "$(cat ./GIT_HASH.txt)" != "$GIT_HASH" ]; then
-    echo -n "$GIT_HASH" > ./GIT_HASH.txt
-fi
-
-echo -n ./GIT_HASH.txt

check-version.sh

@@ -1,13 +0,0 @@
-#!/bin/bash
-
-FE_VERSION="$(cat web/package.json | grep '"version"' | sed 's/[ \t]*"version":[ \t]*"\([^"]*\)",/\1/')"
-
-# TODO: Validate other version sources - backend/Cargo.toml, backend/src/version/mod.rs
-
-VERSION=$FE_VERSION
-
-if ! [ -f ./VERSION.txt ] || [ "$(cat ./VERSION.txt)" != "$VERSION" ]; then
-    echo -n "$VERSION" > ./VERSION.txt
-fi
-
-echo -n ./VERSION.txt

compress-uis.sh

@@ -1,26 +0,0 @@
-#!/bin/bash
-
-cd "$(dirname "${BASH_SOURCE[0]}")"
-
-set -e
-
-rm -rf web/dist/static
-
-if ! [[ "$ENVIRONMENT" =~ (^|-)dev($|-) ]]; then
-    find web/dist/raw -type f -not -name '*.gz' -and -not -name '*.br' | xargs -n 1 -P 0 gzip -kf
-    find web/dist/raw -type f -not -name '*.gz' -and -not -name '*.br' | xargs -n 1 -P 0 brotli -kf
-
-    for file in $(find web/dist/raw -type f -not -name '*.gz' -and -not -name '*.br'); do
-        raw_size=$(du  $file | awk '{print $1 * 512}')
-        gz_size=$(du  $file.gz | awk '{print $1 * 512}')
-        br_size=$(du  $file.br | awk '{print $1 * 512}')
-        if [ $((gz_size * 100 / raw_size)) -gt 70 ]; then
-            rm $file.gz
-        fi
-        if [ $((br_size * 100 / raw_size)) -gt 70 ]; then
-            rm $file.br
-        fi
-    done
-fi
-
-cp -r web/dist/raw web/dist/static

container-runtime/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+bundle.js
+startInit.js
+service/
+service.js
+*.squashfs
+/tmp