Automate sandbox services and release helpers

Author: SecAI-Hub

.github/scripts/check-release-installers.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+#
+# Smoke-test release helper scripts without building large images.
+#
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+
+shell_scripts=(
+    scripts/release/secai-os-build-iso.sh
+    scripts/release/secai-os-build-usb.sh
+    scripts/release/secai-os-run-docker.sh
+)
+
+for script in "${shell_scripts[@]}"; do
+    echo "=== ${script} ==="
+    test -f "$script"
+    bash -n "$script"
+    bash "$script" --help >/dev/null
+done
+
+if command -v shellcheck >/dev/null 2>&1; then
+    shellcheck -s bash "${shell_scripts[@]}" .github/scripts/check-release-installers.sh
+fi
+
+bash scripts/release/secai-os-build-iso.sh \
+    --dry-run \
+    --tag v0.0.0 \
+    --output-dir /tmp/secai-os-iso-smoke >/dev/null
+
+bash scripts/release/secai-os-build-usb.sh \
+    --dry-run \
+    --tag v0.0.0 \
+    --output-dir /tmp/secai-os-usb-smoke >/dev/null
+
+bash scripts/release/secai-os-run-docker.sh \
+    --dry-run \
+    --tag v0.0.0 \
+    --install-dir /tmp/secai-os-docker-smoke \
+    --profile full-lab \
+    --with-inference >/dev/null
+
+pwsh_bin=""
+if command -v pwsh >/dev/null 2>&1; then
+    pwsh_bin="pwsh"
+elif command -v powershell >/dev/null 2>&1; then
+    pwsh_bin="powershell"
+fi
+
+if [[ -n "$pwsh_bin" ]]; then
+    # shellcheck disable=SC2016
+    "$pwsh_bin" -NoProfile -Command \
+        '$null = [scriptblock]::Create((Get-Content scripts/release/secai-os-run-docker.ps1 -Raw)); Write-Output "PowerShell parse OK"'
+    "$pwsh_bin" -NoProfile -File scripts/release/secai-os-run-docker.ps1 \
+        -DryRun \
+        -Tag v0.0.0 \
+        -InstallDir /tmp/secai-os-docker-ps-smoke \
+        -Profile full-lab \
+        -WithInference >/dev/null
+else
+    echo "WARN: PowerShell not available; skipped .ps1 parse smoke"
+fi
+
+echo "OK: release helper scripts passed smoke checks"

.github/workflows/ci.yml

@@ -134,6 +134,17 @@ jobs:
             files/scripts/first-boot-check.sh \
             files/scripts/verify-release.sh
 
+  release-helper-smoke:
+    name: Release Helper Script Smoke
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Validate release helper scripts
+        run: bash .github/scripts/check-release-installers.sh
+
   appsec-lint:
     name: Hadolint & Semgrep
     runs-on: ubuntu-latest
@@ -290,6 +301,11 @@ jobs:
               { echo "FAIL: release.yml missing '${keyword}'"; exit 1; }
             echo "OK: release.yml contains '${keyword}'"
           done
+          for helper in "secai-os-build-iso.sh" "secai-os-build-usb.sh" "secai-os-run-docker.sh" "secai-os-run-docker.ps1"; do
+            grep -q "${helper}" .github/workflows/release.yml || \
+              { echo "FAIL: release.yml missing release helper '${helper}'"; exit 1; }
+            echo "OK: release.yml publishes '${helper}'"
+          done
 
           # Verify build workflow has SBOM attestation
           test -f .github/workflows/build.yml || { echo "FAIL: build.yml missing"; exit 1; }

.github/workflows/release.yml

@@ -42,6 +42,7 @@ jobs:
             "Python Test & Lint"
             "Security Regression Tests"
             "Hadolint & Semgrep"
+            "Release Helper Script Smoke"
             "Dependency Vulnerability Audit"
             "Test Count Drift Check"
             "Documentation Validation"
@@ -400,6 +401,13 @@ jobs:
           path: dist/
           merge-multiple: true
 
+      - name: Stage release helper scripts
+        run: |
+          install -m 0755 scripts/release/secai-os-build-iso.sh dist/secai-os-build-iso.sh
+          install -m 0755 scripts/release/secai-os-build-usb.sh dist/secai-os-build-usb.sh
+          install -m 0755 scripts/release/secai-os-run-docker.sh dist/secai-os-run-docker.sh
+          install -m 0644 scripts/release/secai-os-run-docker.ps1 dist/secai-os-run-docker.ps1
+
       - name: Record release image digest
         run: |
           IMAGE_REF="ghcr.io/${{ github.repository }}"
@@ -451,6 +459,16 @@ jobs:
               '. + [$name]')
           done
 
+          # Collect release helper scripts
+          RELEASE_SCRIPTS_JSON="[]"
+          for helper in secai-os-build-iso.sh secai-os-build-usb.sh secai-os-run-docker.sh secai-os-run-docker.ps1; do
+            [ -f "$helper" ] || continue
+            HASH=$(sha256sum "$helper" | awk '{print $1}')
+            RELEASE_SCRIPTS_JSON=$(echo "$RELEASE_SCRIPTS_JSON" | jq \
+              --arg name "$helper" --arg sha256 "$HASH" \
+              '. + [{"name": $name, "sha256": $sha256}]')
+          done
+
           # Read image digest
           IMAGE_DIGEST="unknown"
           if [ -f IMAGE_DIGEST ]; then
@@ -471,6 +489,7 @@ jobs:
             --argjson binaries "$BINARIES_JSON" \
             --argjson sboms "$SBOMS_JSON" \
             --argjson vex "$VEX_JSON" \
+            --argjson release_scripts "$RELEASE_SCRIPTS_JSON" \
             --arg provenance_type "https://slsa.dev/provenance/v1" \
             --arg checksum_file "SHA256SUMS" \
             --arg signature_file "SHA256SUMS.sig" \
@@ -489,6 +508,7 @@ jobs:
               binaries: $binaries,
               sboms: $sboms,
               vex: $vex,
+              release_scripts: $release_scripts,
               provenance: {
                 type: $provenance_type,
                 attested: true
@@ -577,6 +597,10 @@ jobs:
             dist/IMAGE_DIGEST
             dist/IMAGE_REF_PINNED
             dist/RELEASE_MANIFEST.json
+            dist/secai-os-build-iso.sh
+            dist/secai-os-build-usb.sh
+            dist/secai-os-run-docker.sh
+            dist/secai-os-run-docker.ps1
             dist/secai-os-*.iso.sig
             dist/secai-os-*-usb.raw.xz.sig
             dist/secai-os-*.qcow2.sig

Makefile

@@ -16,7 +16,8 @@ GO_SERVICES := airlock registry tool-firewall gpu-integrity-watch mcp-firewall \
                policy-engine runtime-attestor integrity-monitor incident-recorder
 
 SCRIPTS_LIBEXEC := $(wildcard files/system/usr/libexec/secure-ai/*.sh)
-SCRIPTS_FILES   := $(wildcard files/scripts/*.sh) $(wildcard .github/scripts/*.sh)
+SCRIPTS_FILES   := $(wildcard files/scripts/*.sh) $(wildcard .github/scripts/*.sh) \
+                   $(wildcard scripts/release/*.sh)
 
 # ---------------------------------------------------------------------------
 # Targets

deploy/sandbox/.env.example

@@ -4,6 +4,10 @@
 # UI is the only service published to the host by default.
 SECAI_UI_PORT=8480
 
+# Host-side sandbox controller used by the UI for profile/service automation.
+# It binds to 127.0.0.1 and accepts only token-authenticated allowlisted actions.
+SECAI_CONTROL_PORT=8498
+
 # Optional profiles:
 #   scripts/sandbox/start.* --with-inference
 #   scripts/sandbox/start.* --with-diffusion

deploy/sandbox/compose.yaml

@@ -307,6 +307,8 @@ services:
       SECURE_AI_DEPLOYMENT_MODE: sandbox
       SECURE_AI_DEPLOYMENT_PROVIDER: compose
       SECURE_AI_ASSURANCE_TIER: evaluation
+      SANDBOX_CONTROL_URL: http://host.docker.internal:${SECAI_CONTROL_PORT:-8498}
+      SANDBOX_CONTROL_TOKEN_PATH: /run/secrets/sandbox-control-token
       GUNICORN_WORKERS: 1
       GUNICORN_THREADS: 4
       GUNICORN_TIMEOUT: 60
@@ -316,10 +318,14 @@ services:
       - secai-state:/var/lib/secure-ai
       - secai-run:/run/secure-ai
       - ./runtime/config:/etc/secure-ai/config:ro
+      - ./runtime/model-catalog.yaml:/etc/secure-ai/model-catalog.yaml:ro
       - ./runtime/service-token:/run/secrets/service-token:ro
+      - ./runtime/control-token:/run/secrets/sandbox-control-token:ro
     tmpfs:
       - /tmp:rw,noexec,nosuid,nodev,size=64m
       - /run/secure-ai-ui:rw,noexec,nosuid,nodev,mode=0770,uid=65534,gid=65534,size=16m
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     ports:
       - "${SECAI_UI_PORT:-8480}:8480"
     healthcheck:

docs/api.md

@@ -107,7 +107,7 @@ Proxy an outbound request through the Airlock.
   }
   ```
 - **Error:** `429 Too Many Requests` -- rate limit exceeded
-- **Error:** `503 Service Unavailable` -- Airlock is disabled
+- **Error:** `503 Service Unavailable` -- Airlock policy is disabled in the current runtime profile
 
 ---
 

docs/install/quickstart.md

@@ -180,6 +180,11 @@ Common flags:
 - `--with-airlock` / `-WithAirlock` turns on airlock-mediated outbound downloads in the sandbox runtime policy.
 - `--with-inference` / `-WithInference` and `--with-diffusion` / `-WithDiffusion` enable the heavier model-serving profiles.
 
+The sandbox launcher now starts a loopback-only, token-authenticated host
+controller so the UI can apply these same profile changes from Settings and
+service-specific buttons without mounting the Docker socket into the UI
+container.
+
 > **Security note:** This is a lower-assurance path than the full OS or VM image. The host kernel and container runtime can inspect container memory, mounted files, and network activity. Use it for evaluation and workflow testing, not sensitive workloads.
 
 ---

docs/install/sandbox.md

@@ -57,8 +57,10 @@ The helper script will:
 
 1. Create `deploy/sandbox/.env` from the template if needed.
 2. Generate a per-stack service token in `deploy/sandbox/runtime/service-token`.
-3. Render a runtime policy/config overlay for the selected profiles.
-4. Build, harden, and wait for the sandbox services to become healthy.
+3. Generate a separate host-control token in `deploy/sandbox/runtime/control-token`.
+4. Start a loopback-only host controller used by the UI for profile/service automation.
+5. Render a runtime policy/config overlay for the selected profiles.
+6. Build, harden, and wait for the sandbox services to become healthy.
 
 Then open:
 
@@ -70,6 +72,13 @@ http://127.0.0.1:8480
 
 The default stack starts the control plane only. Inference and diffusion are opt-in because they are heavier and usually need user-supplied model paths or extra runtime dependencies.
 
+When the stack is started through `secai-sandbox.cmd` or `scripts/sandbox/start.*`,
+the UI can start these profiles for you from **Settings**, **Chat**, **Models**, or
+**Generate**. The UI does not receive the Docker socket; it calls a host-side
+controller on `127.0.0.1:${SECAI_CONTROL_PORT:-8498}` with a random bearer token
+mounted read-only into the UI container. The controller only accepts allowlisted
+profile actions.
+
 **Enable local LLM inference**
 
 1. Edit `deploy/sandbox/.env`.
@@ -128,6 +137,12 @@ example:
 bash scripts/sandbox/start.sh --with-search --with-airlock --with-inference
 ```
 
+On Windows, the convenience launcher also supports restart options:
+
+```powershell
+.\secai-sandbox.cmd restart --with-search --with-inference
+```
+
 ## Stop The Stack
 
 **Windows (one-command launcher from the repo root)**

docs/release-artifacts.json

@@ -51,6 +51,15 @@
       "image_digest": {
         "files": ["IMAGE_DIGEST"],
         "description": "OCI image digest for this release"
+      },
+      "release_scripts": {
+        "files": [
+          "secai-os-build-iso.sh",
+          "secai-os-build-usb.sh",
+          "secai-os-run-docker.sh",
+          "secai-os-run-docker.ps1"
+        ],
+        "description": "Standalone helper scripts for building ISO/USB media and launching the Docker sandbox from a release"
       }
     },
     "optional": {