Skip to content

quickstart.md

Latest commit

 

History

History
180 lines (123 loc) · 6.8 KB

quickstart.md

File metadata and controls

180 lines (123 loc) · 6.8 KB

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
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). Pre-built VM images (OVA/QCOW2) still require build infrastructure not yet provisioned. The bootstrap path remains the recommended production install, but the portable USB artifact is the right choice when you want to boot and evaluate directly from removable media. See Artifact Availability for details.

Path A: Bootstrap Install (Real PC or VM)

This is the recommended path. It installs Fedora Silverblue, then rebases to SecAI OS with full signature verification. You get the complete security stack: Secure Boot, TPM2, encrypted vault, and all 25+ defense layers.

1. Install Fedora Silverblue

Download Fedora Silverblue 42 and install it on your hardware or in a VM. A minimal install is fine — SecAI OS replaces the desktop.

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

# Run the bootstrap
sudo bash /tmp/secai-bootstrap.sh

For production, pin to an exact image digest from the latest release:

sudo bash /tmp/secai-bootstrap.sh --digest sha256:RELEASE_DIGEST

3. Reboot

sudo systemctl reboot

4. Open the UI

After reboot, open a browser to:

http://127.0.0.1:8480

What you should see: The SecAI OS setup wizard. It asks you to choose a privacy profile, verifies system health, and walks you through importing your first AI model.

Path B: 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

# Build QCOW2 (requires: virt-install, qemu-img, libvirt)
bash scripts/vm/build-qcow2.sh

# Optionally convert to OVA for VirtualBox/VMware
bash scripts/vm/build-ova.sh

The build scripts pull the signed OCI image and create a bootable disk with root + encrypted vault partitions. Credentials are randomly generated and printed at build time.

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 fedora42 \
  --network default \
  --noautoconsole

# Or import the OVA into VirtualBox/VMware

3. Access the UI

virsh domifaddr secai-os
# Open http://<vm-ip>:8480 in your browser

Security note: VM installs cannot use TPM2 vault key sealing and the host hypervisor has visibility into guest memory. VMs are suitable for evaluation, not sensitive workloads. See support-lifecycle.md for the full support matrix.

Path C: 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

Regardless of install path, the setup wizard guides you through:

  1. Choose your privacy level — Maximum Privacy (default), Web-Assisted Research, or Full Lab
  2. System check — verifies core services are running
  3. Import a model — upload a .gguf model file (it passes through the 7-stage quarantine pipeline automatically)
  4. Start chatting — once the model is promoted, you're ready

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:latest

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 Build locally; CI build requires self-hosted KVM runner

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