SwiftOS Concepts

This guide explains the core ideas behind the current SwiftOS system. It is for readers who want the mental model before diving into command syntax, API layouts, package formats, or kernel design notes.

SwiftOS is a small AArch64 operating system written in Embedded Swift. Its current product shape is application and AI hosting, with embedded/appliance deployment as a co-primary profile. It is intentionally not a Linux clone: software is rebuilt from source, images are immutable, authority is explicit, and tests are part of the public contract.

Use this guide with:

• Getting Started for the first boot.
• User Guide for interactive operation.
• Administration Guide for accounts and image administration.
• Developer Guide for writing native programs.
• Porting Guide for adapting source-built software.
• API Reference for exact ABI details.
• Architecture for the long-form design record.

Quick Concept Map

Use this map when a term is familiar enough to recognize but not yet clear enough to operate.

Product Shape

SwiftOS is currently:

The current system is useful for development, validation, compatibility work, and early product hardening. It is not yet a general desktop or production hosting environment.

Boot And Execution Levels

SwiftOS uses AArch64 exception levels:

The normal boot targets are:

The direct path normally uses:

build/kernel.elf
build/base.img
build/virt.dtb

The UEFI path normally uses:

build/swift-os.img
build/base.img

See Installation Guide for exact commands.

Images And Artifacts

SwiftOS separates boot artifacts from installed software artifacts.

An update today means rebuilding one or more artifacts on the host, booting the candidate, validating it, and keeping rollback artifacts available. See Update And Rollback Guide.

Filesystem Model

SwiftOS uses a two-tier filesystem:

This design keeps boot deterministic and avoids in-place mutation of system files. To change durable system content, edit host-side inputs and rebuild the base image:

make base-image

Inside the guest:

cat /etc/motd
echo ok >/tmp/check.txt
cat /tmp/check.txt

Writes to /etc, /bin, /www, and /models should fail in the current system.

Identity And Authority

SwiftOS does not use Unix uid 0 as the primary authority model. A process has a security context:

principal
session
capability mask
cell tag

The current checked-in image has three seeded accounts:

Check the current identity:

id

The capability mask controls coarse authority such as filesystem reads, tmpfs writes, process inspection, and networking. File descriptors and IPC endpoints also carry per-handle rights, so authority is not only a global bitmask.

For the operational model, see User Guide. For administration, see Administration Guide. For exact ABI structures, see API Reference.

Handles And Capabilities

A handle is a small process-local descriptor that names a kernel object and carries rights. Handles are used for files, pipes, tty, sockets, and IPC endpoints.

The current important ideas are:

• A process may have a capability bit such as capFsRead or capNet.
• An opened handle may still be read-only, write-only, or transfer-limited.
• spawn starts a child with stdio only by default.
• spawn_handles passes an explicit, attenuated handle set.
• IPC transfer moves a handle to the receiver on success.
• confine(path) narrows filesystem visibility and cannot widen it again.

This is the practical bridge from today's capability-aware system to the long-term object-capability model described in Capabilities.

Programs And APIs

SwiftOS user programs are static EL0 binaries. There are three main application paths:

Native Swift programs use the bridge in:

userland/lib/swift_user.h

Raw C programs use:

userland/lib/syscall.h

The syscall ABI is SwiftOS-specific. Linux syscall numbers, Linux static binaries, dynamic loaders, and shared-library plugin models are not part of the current system.

See Developer Guide, Application Cookbook, Porting Guide, and API Reference.

Packages

Packages are the path for optional software that should not be baked into the base /bin set.

Current package concepts:

Package behavior is still evolving. Use Package Guide for the current runbook and Package Management for the longer direction.

Networking And Services

Networking requires both:

1. A QEMU virtio-net device.
2. A process with capNet.

Current networking includes UDP, TCP, DNS, IPv6 smoke paths, a static HTTP server, echo tools, a TCP client, and a TLS smoke client path.

Common service examples:

Services currently run in the foreground from the serial shell and inherit the current login principal. There is no production service supervisor yet.

See Networking Guide and Service Guide.

AI Hosting

SwiftOS includes a TinyStories inference path to prove application and AI hosting primitives:

The serving path loads verified model bundle generations from /models. The checked-in image intentionally includes a corrupt newest generation and a valid older generation so tests prove rejection and fallback.

See AI Hosting Guide.

Observability And Evidence

The primary evidence source today is serial output plus test logs. The kernel also has structured log-ring groundwork and process/resource reporting.

Useful guest commands:

id
ps
top -b -n 1

Useful host checks:

./tests/boot_test.sh
./tests/httpd_test.sh
./tests/llm_serve_test.sh

See Observability Guide, Testing Guide, and Support Guide.

Current Versus Roadmap

SwiftOS documentation separates current behavior from roadmap goals.

Current behavior includes:

• QEMU virt boot.
• UEFI/GPT disk boot.
• Serial console login.
• Static user programs.
• Immutable base image and /tmp.
• Capability-gated filesystem and networking operations.
• Read-only package payloads and package-store activation paths.
• TinyStories local and HTTP serving inference paths.
• A broad host and QEMU test suite.

Roadmap work includes:

• Stronger object-capability boundaries.
• More restartable userland services.
• Broader SMP hardening.
• Signed A/B OS image updates with rollback.
• Richer package repositories and persistent package management.
• Stronger production account and secret handling.
• Native Swift application runtime growth, then Node.js and JVM support.

Use Release Notes for the checked-in product state and Risk Remediation Roadmap for active hardening work.

Glossary

Edit this page on GitHub