Skip to content

quickstart.md

Latest commit

 

History

History
177 lines (120 loc) · 6.28 KB

quickstart.md

File metadata and controls

177 lines (120 loc) · 6.28 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
VM Build ~45 min Moderate Local evaluation in VirtualBox/VMware/KVM
Development ~10 min Easy Service development only (no OS features)

Note on ISO/OVA/QCOW2: The release pipeline builds a signed bootable ISO, but it exceeds GitHub's 2 GB release asset limit. Pre-built VM images (OVA/QCOW2) require build infrastructure not yet provisioned. For now, the bootstrap path below is the primary install method. 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
ISO Release workflow artifact (90-day retention) Built in CI; too large (~4 GB) for GitHub Releases
ISO signature GitHub Releases .iso.sig file for verification
QCOW2 / OVA scripts/vm/build-qcow2.sh / build-ova.sh Build locally; CI build requires self-hosted KVM runner

The ISO is produced by every tagged release and is available as a workflow artifact with 90-day retention. Its cosign signature (.iso.sig) is published to GitHub Releases for verification. For permanent ISO hosting, an external storage solution is needed.

Next Steps