Skip to content

quickstart.md

Latest commit

 

History

History
319 lines (230 loc) · 13 KB

quickstart.md

File metadata and controls

319 lines (230 loc) · 13 KB
Raw

Quickstart

Get SecAI OS running in the fewest steps possible. Choose the path that fits your situation.

Choose Your Install Path

Method Time Difficulty Best For
Bootstrap (Recommended) ~30 min Easy Real PC or VM, full security
Portable USB ~10 min Easy Run directly from removable media without installing first
VM Build ~45 min Moderate Local evaluation in VirtualBox/VMware/KVM
Sandbox Stack ~10 min Easy Evaluate the control plane on an existing workstation
Development ~10 min Easy Service development only (no OS features)

Note on release media: The release pipeline builds both an installer ISO and a portable USB image (*-usb.raw.xz). It does not distribute pre-built VM images: an encrypted VM needs user-specific boot credentials, which must not be shared in a public artifact. Build QCOW2/OVA images locally instead. The bootstrap path remains the recommended production install, while the portable USB artifact is appropriate for direct evaluation from removable media. See Artifact Availability for details.

Path A: Bootstrap Install (Real PC or VM)

This is the intended appliance path. It installs Fedora Silverblue, then rebases to SecAI OS with signature verification. Secure Boot and TPM2 assurance remain hardware-dependent and must be confirmed by the setup checks and the release qualification evidence.

1. Install Fedora Silverblue

Download Fedora Silverblue 44 and install it on your hardware or in a VM. Enable LUKS disk encryption in Anaconda: SecAI OS refuses to generate persistent service credentials unless /var/lib/secure-ai/credentials is demonstrably backed by dm-crypt/LUKS. A minimal install is otherwise fine—SecAI OS replaces the desktop. Reserve an unmounted partition/logical volume (or a second device) for the separately lockable data vault; automatic full-disk allocation leaves no valid vault target.

2. Run the bootstrap script

The bootstrap script configures cosign signature verification before the first image pull — no unverified data is ever fetched.

# Download and review the script (always review before running as root)
curl -sSfL https://raw.githubusercontent.com/SecAI-Hub/SecAI_OS/main/files/scripts/secai-bootstrap.sh \
  -o /tmp/secai-bootstrap.sh
less /tmp/secai-bootstrap.sh

# Use the release channel and exact digest from the signed release bundle
sudo bash /tmp/secai-bootstrap.sh \
  --tag release-vMAJOR.MINOR.PATCH \
  --digest sha256:RELEASE_DIGEST

Digest pinning is mandatory, including for evaluation.

3. Reboot

sudo systemctl reboot

4. Complete the encrypted-vault setup at the local console

sudo /usr/libexec/secure-ai/secai-setup-wizard.sh

The image may report setup_required before this ceremony. That is an explicitly constrained installation state—not production readiness. The wizard requires an unused dedicated partition and asks for an exact, destructive confirmation before creating LUKS2 storage.

5. Open the UI

After the console wizard and its readiness check succeed, open a browser to:

http://127.0.0.1:8480

What you should see: The unprivileged SecAI OS onboarding flow. It asks you to create the local UI credential, choose a privacy profile, and import your first model. It cannot create, unlock, or administer the LUKS vault.

Path B: Run From a Portable USB

This path is for evaluation directly from removable media without first installing to the internal disk.

1. Download the portable USB image

Get the latest secai-os-*-usb.raw.xz workflow artifact from the Release workflow.

2. Verify the checksum

Download SHA256SUMS from the matching release bundle or workflow output and confirm that the hash for secai-os-*-usb.raw.xz matches your download.

3. Write it to the USB drive

Windows (recommended):

  • Prefer USBImager. It can write *.raw.xz images directly.
  • Select the downloaded secai-os-*-usb.raw.xz file.
  • Select the USB drive.
  • Click Write.

Windows (Rufus fallback):

  • Set Boot selection to Disk or ISO image.
  • Click SELECT and choose the portable USB image.
  • If Rufus does not accept *.raw.xz, extract it to *.raw first with 7-Zip and select the extracted file.
  • Do not choose MS-DOS, FreeDOS, or Non bootable.
  • If Rufus offers DD vs ISO write modes, choose DD.

Linux / macOS:

# Linux
xz -dk secai-os-<version>-x86_64-usb.raw.xz
sudo dd if=secai-os-<version>-x86_64-usb.raw of=/dev/sdX bs=16M status=progress oflag=sync

# macOS
xz -dk secai-os-<version>-x86_64-usb.raw.xz
sudo dd if=secai-os-<version>-x86_64-usb.raw of=/dev/rdiskN bs=16m
sync

Replace /dev/sdX or /dev/rdiskN with the actual removable device.

4. Boot from the USB

  • Use the firmware's explicit UEFI USB boot entry.
  • Disable Legacy/CSM mode.
  • If the USB still does not appear bootable, try one test with Secure Boot temporarily disabled to distinguish firmware policy issues from a bad write.

What you should see: The system should boot directly from the USB image rather than showing the installer-only ISO menu.

Path C: Build a VM Image Locally

If you want a self-contained VM image without installing Fedora first, you can build one from the OCI image using the included scripts. This requires a Linux host with KVM/QEMU.

1. Clone the repo and build

git clone https://github.com/SecAI-Hub/SecAI_OS.git
cd SecAI_OS

# Create the QCOW2 disk and a signed-first kickstart.
# The script prints the virt-install command to complete the install.
bash scripts/vm/build-qcow2.sh \
  --image-ref ghcr.io/secai-hub/secai_os@sha256:RELEASE_DIGEST

# After the QCOW2 install completes, optionally convert to OVA for VirtualBox/VMware.
bash scripts/vm/build-ova.sh

The QCOW2 builder verifies the exact digest with cosign, installs the SecAI signing policy in the kickstart before the first image pull, and rebases with ostree-image-signed:docker://. It creates an encrypted host-state partition plus a separate unused vault partition. For a local build, randomly generated temporary login/host-state credentials are written to output/secai-first-boot-secrets.txt with mode 0600; they are never printed to build logs. Change them immediately, then run the console wizard against /dev/sda5 to create the independent data vault and choose its passphrase. After both temporary credentials are rotated, delete the local kickstart and first-boot secrets files.

2. Start the VM

# KVM/QEMU
virt-install \
  --name secai-os \
  --memory 16384 \
  --vcpus 4 \
  --disk path=output/secai-os.qcow2,format=qcow2 \
  --import \
  --os-variant fedora44 \
  --network default \
  --noautoconsole

# Or import the OVA into VirtualBox/VMware

3. Access the UI

virsh domifaddr secai-os
ssh -L 8480:127.0.0.1:8480 secai@<vm-ip>
# Keep the SSH session open, then browse to http://127.0.0.1:8480

The appliance UI remains loopback-only inside the guest. Do not add a public 8480 listener or firewall exception; use an authenticated SSH local forward.

Security note: VM installs cannot claim bare-metal TPM assurance and the host hypervisor has visibility into guest memory. SecAI OS intentionally does not publish generic VM media; use a local, user-specific build and rotate its temporary credentials before handling sensitive data. See support-lifecycle.md for the full support matrix.

Path D: Sandbox Stack

Run the compose-based sandbox bundle when you want the SecAI UI, registry, quarantine pipeline, tool firewall, airlock, policy engine, and agent on an existing workstation without rebasing the host OS.

See sandbox.md for the full instructions.

Common flags:

  • --with-search / -WithSearch enables the Tor + SearXNG search sidecars and turns on search.enabled in the sandbox runtime policy.
  • --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 requires Docker Server 28+ with Compose v2, or rootful Podman Server 5.3+ with compose support on native Linux. The launcher starts a host-local, HMAC-authenticated controller so the UI can apply profile changes without mounting the container-engine socket. Docker Desktop uses loopback; rootful native-Linux engines use a verified RFC 1918 bridge gateway. Native Podman uses only the project-scoped secai-sandbox_ingress bridge, never the default podman network or a LAN listener. A digest-pinned, no-mount, no-secret, capability-free anchor materializes that bridge only until the UI ingress is healthy; safe stop recovery can briefly recreate it if every stack container was stopped out of band. Rootless Docker, rootless Podman, and non-Linux Podman remotes fail closed because their default routing cannot reach the protected host listener. The selected engine is pinned until a successful stop, and every enabled service must become healthy (or running when it has no health check).

Sandbox launchers serialize start, stop, and UI profile operations with an owner-only operation lock. They deliberately do not auto-delete an apparently stale lock because its owner or engine child may be running in another process namespace. Follow the manual verification guidance in sandbox.md rather than deleting the runtime directory.

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.

Path E: Development Mode

Run individual services locally for development without rebasing your OS. No security features (sandboxing, firewall, vault) are active.

See dev.md for setup instructions.

After Boot: First-Time Setup

For native OS and VM installs, first run the local-console wizard:

  1. Verify deployment identity and signed transport
  2. Create and verify the LUKS2 encrypted vault
  3. Optionally enroll TPM2 with a retained passphrase recovery slot
  4. Run the production readiness check

Then use the web onboarding flow to choose a privacy profile, import a model through quarantine, and start chatting. The Docker development/sandbox paths do not provide a LUKS vault and must not claim native-appliance assurance.

Verify Your Install (Optional)

After running the bootstrap, you can verify the image signature:

cosign verify --key cosign.pub \
  ghcr.io/secai-hub/secai_os@sha256:RELEASE_DIGEST

To verify release artifacts (Go binaries, SBOMs, checksums):

Linux / macOS:

curl -sSfL https://github.com/SecAI-Hub/SecAI_OS/releases/latest/download/SHA256SUMS -o SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

Windows (PowerShell):

Invoke-WebRequest -Uri "https://github.com/SecAI-Hub/SecAI_OS/releases/latest/download/SHA256SUMS" -OutFile SHA256SUMS
Get-Content SHA256SUMS

For advanced verification (cosign detached signatures, SLSA3 provenance attestation), see sample-release-bundle.md or run:

make verify-release

Artifact Availability

Artifact Where Status
OCI image ghcr.io/secai-hub/secai_os:latest Always available, cosign-signed
Go binaries + SBOMs GitHub Releases Always available
Installer ISO Release workflow artifact (90-day retention) Built in CI; intended for install-to-disk
ISO signature GitHub Releases .iso.sig file for verification
Portable USB image Release workflow artifact (90-day retention) Built in CI as secai-os-*-usb.raw.xz; flash directly to removable media
Portable USB signature GitHub Releases .raw.xz.sig file for verification
QCOW2 / OVA scripts/vm/build-qcow2.sh / build-ova.sh locally Local-only, user-specific encrypted build; never a release artifact

The installer ISO and portable USB image are produced by every tagged release and are available as workflow artifacts with 90-day retention. Their cosign signatures are published to GitHub Releases for verification. For permanent hosting, an external storage solution is still needed.

Next Steps