SecAI OS

Bootable local-first AI OS with sealed runtime, model quarantine pipeline, airlock egress controls, encrypted vault, and private Tor-routed search.

Built on uBlue (Fedora Atomic / Silverblue). All AI compute -- inference and generation -- stays on-device. Network egress is denied by default. GPU auto-detected at first boot.

+-------------------+     +-------------------+     +-------------------+
|  A) Base OS       | --> |  B) Acquisition   | --> |  C) Quarantine    |
|  immutable image  |     |  dirty net /      |     |  7-stage pipeline |
|  signed updates   |     |  allowlist only   |     |  fully automatic  |
+-------------------+     +-------------------+     +--------+----------+
                                                             |
                          +-------------------+     +--------v----------+
                          |  E) Airlock       | <-- |  D) Runtime       |
                          |  sanitized egress |     |  sealed inference |
                          |  (optional)       |     |  no internet      |
                          +-------------------+     +-------------------+

Who This Is For

Privacy-conscious AI users who want LLM and image generation without cloud services
Security researchers evaluating model supply-chain risks
Air-gapped environments that need AI inference with no internet dependency
Organizations requiring auditable, policy-enforced AI workstations

What Makes It Different

Default-deny egress -- The runtime has no internet unless explicitly enabled via the airlock.
Supply-chain distrust -- Models are untrusted until they pass a 7-stage quarantine pipeline (source, format, integrity, provenance, static scan, behavioral test, diffusion scan).
Hands-off security -- All scanning, verification, and promotion happens automatically. Users never run security tools manually.
Deterministic policy -- Promotion to "trusted" is rule-based (signatures, hashes, scans, tests), not ad-hoc.
Short-lived workers -- No swap, tmpfs for temp data, inference workers restart between sessions.
25+ defense layers -- From UEFI Secure Boot and TPM2 to seccomp-BPF, Landlock, runtime attestation, continuous integrity monitoring, automated incident containment, and 3-level emergency wipe.

Quickstart

Download, verify, boot, run the setup wizard. See docs/install/quickstart.md for full details.

Method	Time	Best For
ISO (Recommended)	~30 min	Real PC, full security
OVA	~15 min	Try it first (VirtualBox/VMware)
QCOW2	~15 min	KVM / Proxmox
Rebase	~45 min	Existing Fedora Silverblue

After boot, the setup wizard guides you through profile selection, system verification, and model import.

Advanced / Operator Install

For production deployments with digest pinning and signing policy configuration:

# Review the bootstrap script, then run with a pinned digest
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
sudo bash /tmp/secai-bootstrap.sh --digest sha256:RELEASE_DIGEST
sudo systemctl reboot

See bare metal | virtual machine | development | recovery

Get Your First Model

Open http://127.0.0.1:8480, go to Models, and click Download on any model in the catalog. The 7-stage quarantine pipeline runs automatically. Once promoted, the model is ready to use.

Architecture

Services

Service	Port	Language	Purpose
Registry	8470	Go	Trusted artifact manifest, read-only model store
Tool Firewall	8475	Go	Policy-gated tool invocation gateway
Web UI	8480	Python	Chat, image/video generation, model management
Airlock	8490	Go	Sanitized egress proxy (disabled by default)
Inference Worker	8465	llama.cpp	LLM inference (CUDA / ROCm / Vulkan / Metal / CPU)
Diffusion Worker	8455	Python	Image and video generation
Agent	8476	Python	Policy-bound local autopilot (deny-by-default, capability tokens)
Quarantine	--	Python	7-stage verify, scan, and promote pipeline
GPU Integrity Watch	8495	Go	Continuous GPU runtime verification and anomaly detection
MCP Firewall	8496	Go	Model Context Protocol policy gateway (default-deny, taint tracking)
Policy Engine	8500	Go	Unified policy decision point (6 domains, decision evidence, OPA-upgradeable)
Runtime Attestor	8505	Go	TPM2 quote verification, HMAC-signed state bundles, startup gating
Integrity Monitor	8510	Go	Continuous baseline-verified file watcher (binaries, policies, models, trust material)
Incident Recorder	8515	Go	Security event capture, incident lifecycle, auto-containment
Search Mediator	8485	Python	Tor-routed web search with PII stripping
SearXNG	8888	Python	Self-hosted metasearch (privacy-respecting engines)
Tor	9050	C	Anonymous SOCKS5 proxy

7-Stage Quarantine Pipeline

Every model passes through the same fully automatic pipeline:

Stage	Name	What It Does
1	Source Policy	Verifies origin against allowlist
2	Format Gate	Validates headers, rejects unsafe formats (pickle, .pt, .bin)
3	Integrity Check	SHA-256 hash pinning verification
4	Provenance	Cosign signature verification
5	Static Scan	ModelScan + entropy analysis + gguf-guard (weight-level anomaly detection)
6	Behavioral Test	22 adversarial prompts across 10 attack categories (LLM only)
7	Diffusion Scan	Config integrity, symlink detection (diffusion only)

Security Model

Defense Layers

Layer	Mechanism
Boot	Immutable OS (rpm-ostree), cosign-verified updates, greenboot auto-rollback
Secure Boot	UEFI Secure Boot + MOK signing, TPM2 vault key sealing (PCR 0,2,4,7)
Kernel	IOMMU forced, ASLR, slab_nomerge, init_on_alloc/free, lockdown=confidentiality
Memory	Swap/zswap disabled, core dumps discarded, mlock for secrets, TEE detection
Network	nftables default-deny egress, DNS rate-limited, traffic analysis countermeasures
Filesystem	Encrypted vault (LUKS2/AES-256/Argon2id), restrictive permissions, fs-verity
Models	7-stage quarantine pipeline with gguf-guard deep integrity scanning
Tools	Default-deny policy, path allowlisting, traversal protection, rate limiting
Egress	Airlock disabled by default, PII/credential scanning, destination allowlist
Search	Tor-routed, privacy-preserving query obfuscation (decoy queries, k-anonymity), injection detection
Audit	Hash-chained tamper-evident logs with periodic verification
Auth	Scrypt passphrase hashing, rate-limited login, session management
Vault	Auto-lock after 30 min idle, TPM2-sealed keys
Services	Systemd sandboxing: ProtectSystem, PrivateNetwork, seccomp-bpf, Landlock
Agent	Deny-by-default policy engine, HMAC-signed capability tokens, hard budgets, loopback-only IPC
Policy Engine	Unified decision point (6 domains), structured evidence, OPA/Rego-upgradeable
Attestation	TPM2 quote verification, HMAC-signed runtime state bundles, startup gating
Integrity	Continuous baseline-verified file watcher (30s scans), signed baselines, auto-degradation
Incident Response	9 incident classes, auto-containment (freeze agent, disable airlock, vault relock, quarantine model)
GPU	Vendor-specific DeviceAllow, PrivateNetwork, driver fingerprinting, device allowlist
HSM/Keys	Pluggable keystore (software/TPM2/PKCS#11), key rotation, PCR-sealed key hierarchy
Clipboard	VM clipboard agents disabled, auto-clear every 60s
Tripwire	Canary files in sensitive dirs, inotify real-time monitoring
Emergency	3-level panic (lock / wipe keys / full wipe) with passphrase gates
Updates	Cosign-verified rpm-ostree, staged workflow, greenboot auto-rollback
Supply Chain	Per-service CycloneDX SBOMs, SLSA3 provenance attestation, cosign-signed checksums

See docs/threat-model.md for threat classes, residual risks, and security invariants. See docs/security-status.md for implementation status of all 54 milestones.

Verify Image Signatures

cosign verify --key cosign.pub ghcr.io/secai-hub/secai_os:latest

Releases & Packages

Container Image (OCI)

Every push to main builds a signed OCI image via BlueBuild:

ghcr.io/secai-hub/secai_os:latest     # rolling latest
ghcr.io/secai-hub/secai_os:42          # Fedora 42 base

Install with digest pinning (recommended for production):

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

The image is cosign-signed. Verify before pulling:

cosign verify --key cosign.pub ghcr.io/secai-hub/secai_os:latest

Tagged Releases

Tagged releases (v*) are built by the Release workflow and include:

Artifact	Description
`<service>-linux-amd64`	Static Go binary (x86_64)
`<service>-linux-arm64`	Static Go binary (ARM64)
`<service>-sbom.cdx.json`	Per-service CycloneDX SBOM
`SHA256SUMS`	Checksums for all release artifacts
`SHA256SUMS.sig`	Cosign signature over checksums
`IMAGE_DIGEST`	OCI image digest for this release
`IMAGE_REF_PINNED`	Fully qualified digest-pinned image reference
`RELEASE_MANIFEST.json`	Machine-readable release manifest (binaries, SBOMs, provenance, build metadata)

Go services shipped as release binaries: airlock, registry, tool-firewall, gpu-integrity-watch, mcp-firewall, policy-engine, runtime-attestor, integrity-monitor, incident-recorder.

Python services (ui, agent, quarantine, diffusion-worker, search-mediator) are baked into the OCI image and do not ship as standalone binaries.

Verify a Release

# Download and verify checksums
curl -sSfL https://github.com/SecAI-Hub/SecAI_OS/releases/download/v0.1.0/SHA256SUMS -o SHA256SUMS
curl -sSfL https://github.com/SecAI-Hub/SecAI_OS/releases/download/v0.1.0/SHA256SUMS.sig -o SHA256SUMS.sig
cosign verify-blob --key cosign.pub --signature SHA256SUMS.sig SHA256SUMS
sha256sum -c SHA256SUMS

# Or use the Makefile (clones repo, runs full verification)
make verify-release

See docs/sample-release-bundle.md for the full artifact structure and docs/release-policy.md for release channels (stable/candidate/dev).

Diffusion Runtime (On-Demand)

The ~2–5 GB diffusion runtime (PyTorch, diffusers, transformers) is not included in the base image. It is acquired on-demand when a user first visits the Generate page:

Backend auto-detected (CUDA / ROCm / CPU)
Wheels downloaded from PyTorch/PyPI with full hash verification against committed manifests
Installed into an isolated venv, smoke tested, and enabled

Trust anchors: diffusion-runtime-manifest.yaml + per-backend lockfiles (diffusion-{cpu,cuda,rocm}.lock). Air-gapped installs supported via --from-local.

Hardware Support

GPU is auto-detected at first boot. No manual configuration needed.

Vendor	GPUs	Backend	LLM	Diffusion
NVIDIA	RTX 5090/5080/4090/4080/3090/3080	CUDA	Full offload	Full offload
AMD	RX 7900 XTX/XT, RX 7800/7700, RDNA/CDNA	ROCm (HIP)	Full offload	Full offload
Intel	Arc A770/A750/A580, Arc B-series	XPU (oneAPI)	Via Vulkan	Via IPEX
Apple	M4/M3/M2/M1 (Pro/Max/Ultra)	Metal / MPS	Full offload	MPS acceleration
CPU	x86_64 (AVX2/AVX-512), ARM64 (NEON)	CPU	Optimized	Functional

Minimum: 16 GB RAM, 8 GB VRAM, 64 GB storage. See docs/compatibility-matrix.md for detailed specs.

Configuration

All config lives in /etc/secure-ai/ (baked into the image, read-only at runtime):

File	Purpose
`config/appliance.yaml`	Mode, paths, inference/diffusion settings, service binds
`policy/policy.yaml`	Tool firewall, airlock, quarantine stages, search settings
`policy/agent.yaml`	Agent mode: operating modes, budgets, workspace scopes, allow/deny matrix
`policy/models.lock.yaml`	Pinned model hashes (supply-chain verification)
`policy/sources.allowlist.yaml`	Trusted model sources

See docs/policy-schema.md for full schema reference. See examples/sample-policy.yaml for annotated example.

Verification & Audit

Workflow Files

Security Documentation

CI Verification Evidence

All CI jobs are defined in .github/workflows/ci.yml. View the latest CI run.

Job	Workflow Link	What It Proves
`go-build-and-test`	View job	413 Go tests across 9 services with `-race` (build, test, vet)
`python-test`	View job	998 Python tests (unit/integration + adversarial/acceptance), ruff lint, bandit security scan (enforced on HIGH/HIGH), mypy type checking
`security-regression`	View job	Adversarial test suite: prompt injection, policy bypass, containment, recovery
`supply-chain-verify`	View job	SBOM generation via Syft, cosign availability, provenance keywords in release/build workflows
`test-count-check`	View job	Prevents documented test counts from drifting below actual (source of truth: test-counts.json)
`dependency-audit`	View job	Enforced Go vulnerability scanning (govulncheck) + Python dependency audit (pip-audit) with waiver mechanism
`shellcheck`	View job	Static analysis of all shell scripts (first-boot, build, verify-release, etc.)
`policy-validate`	View job	YAML schema validation for all policy and recipe files
`check-pins`	View job	Verifies all GitHub Actions are pinned to specific commit SHAs (not tags)
`docs-validation`	View job	Broken link detection, required docs presence, test-counts.json format validation

Documentation

Document	Description
Architecture	System design, zones, data flow, service dependencies
Threat Model	Threat classes, invariants, residual risks
API Reference	HTTP API for all services
Policy Schema	Full policy.yaml schema reference
Security Status	Implementation status of all 54 milestones
Test Matrix	Test coverage: 1,411 tests across Go and Python (see test-counts.json)
Compatibility Matrix	GPU, VM, and hardware support
Security Test Matrix	Security feature test coverage
FAQ	Common questions
Glossary	Key terms and concepts
Non-Goals	What SecAI OS does NOT try to do
Why is this safe?	Plain-language security explanation
Telemetry Policy	No-telemetry guarantee

Component Docs

Component	Description
Registry	Trusted artifact manifest and model store
Tool Firewall	Policy-gated tool invocation
Airlock	Sanitized egress proxy
Quarantine	7-stage scanning pipeline
Agent	Policy-bound local autopilot with verified supervisor
Search Mediator	Tor-routed web search
GPU Integrity Watch	Continuous GPU runtime verification
MCP Firewall	Model Context Protocol policy gateway
Policy Engine	Unified policy decision point
Runtime Attestor	TPM2 attestation and startup gating
Integrity Monitor	Continuous file integrity verification
Incident Recorder	Security event capture and auto-containment
M5 Control Matrix	M5 acceptance criteria, enforcement paths, operator verification
Supply Chain Provenance	Provenance pipeline, SBOM coverage, key material
Audit Quick Path	External auditor step-by-step verification guide
Recovery Runbook	Operator procedures for degradation, containment, and recovery
Sample Release Bundle	Release artifact structure and verification commands
Production Operations	First-boot checks, upgrades, key rotation, monitoring, capacity
Production Readiness Checklist	Formal release gate checklist for production deployments
SLOs	Service level objectives: availability, latency, correctness targets
Release Policy	Release channels (stable/candidate/dev), versioning, upgrade paths
Support Lifecycle	Hardware matrix, driver versions, support windows, deprecation policy

Install Guides

Guide	Description
Quickstart	Choose your path: ISO, OVA, QCOW2, or rebase
Bare Metal	Fresh install on dedicated hardware
Virtual Machine	VirtualBox, VMware, KVM/QEMU
Development	Local dev without OS rebase

Examples

Example	Description
Import a GGUF Model	Safe model import walkthrough
Quarantine Promotion	Full pipeline walkthrough
Run Fully Offline	Air-gapped operation
Enable Web Search	Tor-routed search setup
Vault Management	Lock, unlock, keepalive
Recover from Failed Update	Rollback and recovery
VM vs Bare Metal	Comparison and tradeoffs
Add Model Source	Allowlist a new source

Machine-Readable

Resource	Description
OpenAPI Spec	OpenAPI 3.0 for all HTTP APIs
Policy Schema	JSON Schema for policy.yaml
Appliance Schema	JSON Schema for appliance.yaml
Service Diagram	Mermaid dependency diagram
llms.txt	LLM-friendly project summary
llms-full.txt	Extended LLM-friendly reference

Using the Appliance

Web Interface

Open http://127.0.0.1:8480:

Chat -- LLM interaction with optional Tor-routed web search
Models -- Browse catalog, one-click download, import, verify hashes
Generate -- Text-to-image, image-to-image, text-to-video with diffusion models
Security -- Service health, Secure Boot/TPM2 status, audit chain, emergency panic
Updates -- Staged update workflow (check / stage / apply / rollback)
Settings -- Vault lock/unlock, passphrase change, session management

Emergency Panic

sudo securectl panic 1                          # Lock (reversible)
sudo securectl panic 2 --confirm "passphrase"   # Wipe keys
sudo securectl panic 3 --confirm "passphrase"   # Full wipe (DATA UNRECOVERABLE)

Also available via Web UI (Security page) and API (POST /api/emergency/panic).

Vault Management

curl http://127.0.0.1:8480/api/vault/status         # Check status
curl -X POST http://127.0.0.1:8480/api/vault/lock    # Lock
curl -X POST http://127.0.0.1:8480/api/vault/unlock \ # Unlock
  -H 'Content-Type: application/json' \
  -d '{"passphrase": "your-passphrase"}'

Web Search (Tor-Routed, Optional)

# Enable in policy, then start the search stack
sudo systemctl start secure-ai-tor secure-ai-searxng secure-ai-search-mediator

Privacy: Tor-routed, PII stripped, injection detection, privacy-preserving query obfuscation (decoy queries, k-anonymity), audit logged. See examples/enable-web-search.md.

Running Tests

# Go tests (413 total across 9 services)
for svc in airlock registry tool-firewall gpu-integrity-watch mcp-firewall \
           policy-engine runtime-attestor integrity-monitor incident-recorder; do
  (cd services/$svc && go test -v -race ./...)
done

# Python tests (923 total)
pip install pytest flask requests pyyaml
python -m pytest tests/ -v

# Shell script linting
shellcheck files/system/usr/libexec/secure-ai/*.sh files/scripts/*.sh

See docs/test-matrix.md for full breakdown.

Roadmap

All 54 project milestones (click to expand)

Project Structure

recipes/                    BlueBuild recipe (image definition)
files/
  system/
    etc/secure-ai/          Policy and config files baked into image
    etc/nftables/            Firewall rules (default-deny egress)
    usr/lib/systemd/         Systemd service units (sandboxed)
    usr/libexec/             Helper scripts (firstboot, vault, securectl, canary)
services/
  registry/                 Go -- Trusted Registry (:8470)
  tool-firewall/            Go -- Policy-gated tool gateway (:8475)
  airlock/                  Go -- Online egress proxy (:8490)
  gpu-integrity-watch/      Go -- GPU runtime verification (:8495)
  mcp-firewall/             Go -- MCP policy gateway (:8496)
  policy-engine/            Go -- Unified policy decisions (:8500)
  runtime-attestor/         Go -- TPM2 attestation + startup gating (:8505)
  integrity-monitor/        Go -- Continuous file integrity watcher (:8510)
  incident-recorder/        Go -- Incident capture + containment (:8515)
  agent/                    Python/Flask -- Verified supervisor autopilot (:8476)
  quarantine/               Python -- 7-stage verification + scanning pipeline
  diffusion-worker/         Python -- Image/video generation (:8455)
  search-mediator/          Python -- Tor-routed web search (:8485)
  ui/                       Python/Flask -- Web UI (:8480)
  common/                   Python -- Shared utilities (audit, auth, mlock)
tests/                      998 Python tests, 413 Go tests (1,411 total)
docs/                       Architecture, API, threat model, install guides
schemas/                    OpenAPI spec, JSON Schema for config files
examples/                   Task-oriented walkthroughs
.github/workflows/          CI (test/lint), build (image), release (SLSA3/SBOM)

Contributing

See CONTRIBUTING.md for local dev setup, coding standards, and PR rules.

Security

See SECURITY.md for vulnerability reporting and threat boundaries.

Telemetry

SecAI OS does not collect telemetry. No usage analytics, crash reports, or phone-home. See docs/telemetry-policy.md.

License

Apache License 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 111 Commits
.github		.github
docs		docs
examples		examples
files		files
modules		modules
recipes		recipes
schemas		schemas
scripts		scripts
services		services
tests		tests
vendor/wheels		vendor/wheels
.gitignore		.gitignore
.upstreams.lock.yaml		.upstreams.lock.yaml
CITATION.cff		CITATION.cff
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
cosign.pub		cosign.pub
llms-full.txt		llms-full.txt
llms.txt		llms.txt
requirements-ci.txt		requirements-ci.txt

Folders and files

Latest commit

History

Repository files navigation

SecAI OS

Who This Is For

What Makes It Different

Quickstart

Advanced / Operator Install

Get Your First Model

Architecture

Services

7-Stage Quarantine Pipeline

Security Model

Defense Layers

Verify Image Signatures

Releases & Packages

Container Image (OCI)

Tagged Releases

Verify a Release

Diffusion Runtime (On-Demand)

Hardware Support

Configuration

Verification & Audit

Workflow Files

Security Documentation

CI Verification Evidence

Documentation

Component Docs

Install Guides

Examples

Machine-Readable

Using the Appliance

Web Interface

Emergency Panic

Vault Management

Web Search (Tor-Routed, Optional)

Running Tests

Roadmap

Project Structure

Contributing

Security

Telemetry

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages