SecureOS

SecureOS is an experimental operating system targeting zero-trust by default behavior. The current bootable image is a trusted-application prototype, not a security boundary for untrusted code.

Current maturity and security boundary

The ordinary image provides a console, sessions, native application loading, and selected capability checks and consent prompts. Native applications currently execute in shared kernel memory through a fixed-address callback bridge and generally use the console/session identity. They do not have hardware-protected address spaces or a genuine application-to-kernel privilege boundary.

Run only code you trust in a disposable QEMU environment. Consent to launch an unsigned binary is not proof of isolation or per-application resource authority; the current checks cannot prevent native code from directly accessing shared memory. Do not rely on this prototype to contain hostile applications, arbitrary faults, or hung code.

Hardware isolation and independently enforced application authority remain open in SEC-01 (#772). The real in-guest edit/build/consent/run/reboot demo is also incomplete; its acceptance gate is DEMO-07 (#771). Boot smoke tests and host-model tests do not establish either capability, and a SKIP marker is incomplete evidence.

Quick Start

# Clone and run — that's it
git clone https://github.com/rwrife/SecureOS.git
cd SecureOS

# macOS / Linux
./start.sh

# Windows (PowerShell)
.\start.ps1

The start script automatically:

1. Checks for Docker and QEMU (installs them if missing, with your confirmation)
2. Builds the OS inside a Docker container
3. Boots SecureOS in QEMU

Options

Flag	Description
--graphics / -Graphics	Boot with VGA display window
--build-only / -BuildOnly	Build without booting
--setup-only / -SetupOnly	Install dependencies only
--clean / -Clean	Remove artifacts before building
--skip-setup / -SkipSetup	Skip dependency checks

Individual Scripts

For iterative development, use the scripts separately:

./scripts/build.sh [kernel|disk|all]    # Build (default: all)
./scripts/boot.sh [console|graphics]    # Boot (default: console)
./scripts/test.sh [test_name|--all]     # Run tests

Windows:

.\scripts\build.ps1 [kernel|disk|all]
.\scripts\boot.ps1 [console|graphics]
.\scripts\test.ps1 [test_name|--all]

Prerequisites

Only two tools are needed on your host machine:

• Docker — all compilation happens inside a container
• QEMU — runs the OS with hardware emulation

The setup scripts handle installation:

• macOS: ./scripts/setup-macos.sh
• Linux: ./scripts/setup-linux.sh
• Windows: .\scripts\setup-windows.ps1

Demo

After booting (via ./start.sh or ./scripts/boot.sh), interact with the OS:

secureos> help
secureos> apps
secureos> run filedemo
secureos> cat appdemo.txt
secureos> exit pass

For graphics mode with the VGA display:

./start.sh --graphics

Architecture

• kernel/ — Session management, native loading, capability checks, and hardware abstraction; isolation work is incomplete
• user/ — Application libraries, apps, and OS commands (not currently a protected user-mode boundary)
• build/ — Dockerfile, internal build scripts, QEMU configs
• scripts/ — Host-side entry points (setup, build, boot, test)
• manifests/ — Capability manifests for processes
• docs/ — Architecture decisions, ABI reference, test plans
  • docs/abi/ — canonical ABI reference (OS_ABI_VERSION = 0): syscall surface, IPC wire format, capability handle representation, launcher manifest schema, and the OS_ABI_VERSION policy. See docs/abi/README.md for the full index.
• plans/ — Planning documents for future work
• sdk/ — Public SDK scaffold (M6, BUILD_ROADMAP §5.6): sdk/include/os/abi.h re-exports OS_ABI_VERSION_* from user/include/secureos_abi.h, sdk/VERSION pins MAJOR.MINOR.PATCH. Slice 1 only; libos.a and the os-cc / os-pack / os-run wrappers arrive in later slices. See sdk/README.md.

Design Principles

These are architectural goals, not guarantees of the current prototype. See the security boundary above.

• Capability-native: All resource access goes through explicit capability gates
• Deny-by-default: Processes start with zero permissions
• User consent: Hardware/resource access requires interactive confirmation
• Deterministic builds: Pinned Docker toolchain ensures reproducibility
• Multi-architecture ready: HAL layer abstracts hardware (x86 target first)

Contributing

See CONTRIBUTING.md for full contributor guidance. For the M7 in-OS toolchain execution frontier, start with docs/development/pickup-guide-m7.md.

Distributing SecureOS images

Released SecureOS images that statically link TinyCC (LGPL-2.1) must ship with a compliance bundle produced by build/scripts/build_release_compliance_bundle.sh. The bundle's layout and obligations are documented in docs/legal/lgpl-compliance.md and verified by the release_compliance_bundle host test (SKIP-pinned until #408 Phase 3 lands TinyCC into the image).