swift-os is a full-fledged, modern operating system written in Embedded
Swift for aarch64
. Its flagship profile is application & AI hosting; embedded/appliance deployment is a co-primary profile; desktop use is not excluded. The design value is efficient, reliable minimalism — a small trusted core, capability-based isolation, fast deterministic boot, immutable signed images, and testable correctness, achieved by removing legacy rather than emulating it.
The project is not a Linux clone and not a legacy Unix compatibility exercise. The same minimalist core serves all three profiles; they differ mainly in which optional services and devices are present, not in the kernel.
The bring-up phase is complete and the system runs a native Swift userland with networking. Development is now in Phase 1: hardening the system for the product profile (capability/handle model, SMP, restartable userland services — see docs/RISK_REMEDIATION_ROADMAP.md).
What exists today, in the order it was built:
Phase 0 — bring-up (historical, M0–M8): the kernel boots at EL1 on QEMUvirt
; UART, exceptions, GIC timer interrupts, the MMU, and preemptive EL0 scheduling are up; each process has its own address space; fork/exec/waitpid work; a VFS exposes a read-only base FS plus a writable tmpfs; static ELF64 programs load and execute from the VFS. The bring-up userland was a statically linked busyboxsh
(a legacy tool used to prove the syscall surface); thenative Swift userland is now the direction(see below).make test
covers host-side unit checks and QEMU boot assertions. -
M9 — HAL + device tree: the kernel reads its own DTB at boot and populates a globalPlatform
struct; UART/GIC/RAM addresses come from the device tree instead of being hardcoded. -
M10 (a/b/c) — UEFI boot from GPT disk: a minimal AArch64 PE32+ EFI (BOOTAA64.EFI
) callsExitBootServices
and hands off to the Swift kernel.make disk
producesbuild/swift-os.img
, a sparse GPT image with an EFI System Partition.make disk-run
boots it under QEMU+AAVMF (edk2) with no-kernel
. The direct-kernel
path is kept as a fallback and both are tested bymake test
. -
M10.5 — VirtualBox ARM prep: the EFI emits diagnostics before handoff; a procedure for manually testing on VirtualBox ARM is indocs/VIRTUALBOX.md
. -
M11 (a–d) — virtio-blk + packed read-only base FS from disk: a deterministic signed packed base image format (SWOSBASE v3
); a host packer (tools/basepack.swift
); a polled virtio 1.0 block driver; the VFS mounts the packed image at boot and serves/bin
,/etc
, and other base files directly from disk. The kernel no longer embeds any userland binary; the image shrank from ~1.4 MiB to ~208 KiB. Everymake run
/make test
invocation attachesbuild/base.img
as a virtio-blk device. -
M12 (a–d) — capability/principal security + console-login as init: a typedProcessSecurityContext
(principal, session, capability mask — not Unix uid==0); a base-image identity store/etc/swos/passwd
with SHA-256-hashed passwords;console-login
authenticates a principal, callsSYS_LOGIN
, andexecve
s the shell with the adopted context; when a session ends, init loops back to a fresh login prompt. -
M13 (a–c) + follow-ups — VFS capability enforcement, file ownership, shell redirection:vfsOpen
checks the caller's capability mask at open time (capFsRead
,capTmpWrite
); tmpfs namespace mutations (mkdir
/rm
/mv
) requirecapTmpWrite
; vnodes carry an owner (principal) and mode written at creation or packed from the base image;ls -l
shows permission strings, owner names, sizes, and real timestamps (PL031 RTC);fcntl
(F_DUPFD_CLOEXEC
,F_GETFD
/F_SETFD
,F_GETFL
) and close-on-exec semantics make shell I/O redirection (echo > file
,>>
, pipe-into-redirect) work correctly. -
Native Swift userland coreutils: a growing set of pure-Embedded-Swift EL0 utilities over theuserland/lib/swift_user.*
bridge, all packed into the base image:ls
(with-l
),cat
,echo
,pwd
,ps
,top
,id
,mkdir
,rmdir
,rm
,mv
,chmod
,chown
,head
,touch
,wc
,date
,calc
(an interactive expression REPL that exercises SwiftString
/Array
/Dictionary
/ARC),kv
(an in-memory key-value REPL), andconsole-login
. The userland free-capable allocator (K&R free-list oversbrk
) backs ARC for these apps. -
Network stack (N-series, in-kernel, sans-IO core): a TCP/IP/UDP/ARP/ICMP/ DNS stack in Embedded Swift. The protocol core (kernel/net/
) is pure Swift (no MMIO/heap-per-packet), compiled into both the kernel and host unit tests. The virtio-net driver (kernel/drivers/virtio_net.swift
) provides the DMA path. Capability-gated socket syscalls (socket
/bind
/sendto
/recvfrom
/listen
/accept
/connect
/resolve
) are exposed to EL0. Userland tools:/bin/udpecho
,/bin/tcpecho
,/bin/tcpget
,/bin/nslookup
,/bin/httpd
(a concurrent poll()-driven static-file HTTP server with MIME types and directory listings), and/bin/llmd
(TinyStories inference over HTTP). A ChaCha20-Poly1305 AEAD module (kernel/crypto/
) is built and tested as TLS groundwork. DNS queries resolve against slirp's nameserver by default. -
Restartable driver-service and device-discovery smoke: the C5a-C5f path stages/bin/drvsvcdemo
and/bin/drvinputd
. The supervisor starts an input-driver service, exchanges endpoint IPC messages, discovers and claimsvirtio-input.0
when QEMU exposes a keyboard device, falls back topseudo-input.0
in headless boots, surfaces virtio-mmio base/length as discovery metadata, proves future hardware-authority bits stay clear, keeps the current device grant metadata-only, transfers an opaque device handle, proves the grant moves, stays busy while the service owns it, is reclaimed after exit, and recovers withC5a OK: restartable driver service recovered over IPC
,C5b OK: opaque device handle transferred and released
,C5c OK: virtio-input device grant discovered and matched
,C5d OK: virtio input discovery metadata surfaced
,C5e OK: device authority withheld until explicit handoff
, andC5f OK: device grant rights stayed metadata-only
. The aggregate acceptance gate ismake c5-test
; real MMIO, IRQ, DMA, and virtio-input queue ownership are still roadmap work. -
Threading runtime:thread_create
/futex
(FUTEX_WAIT/FUTEX_WAKE) syscalls; EL0 threads share one address space; a futex-based mutex test proves correct concurrent increment across preemption. -
Process teardown reclaims frames:address_space_destroy
walks and frees all user-half page tables and leaf frames on process exit/exec/reap; a boot- time reclaim test asserts zero leak across fork+exec+spawn round-trips. -
Package and ports fixtures:.swpkg
packages, writable package-store images, signed static repository catalogs, and target-sidepkg install NAME
are covered by executable fixtures. The current ports path also cross-builds static AArch64 Lua, zlib, bzip2, zstd, xz, libarchive, OpenSSL, pcre2, nginx, and sqlite on the host, packages the pinned ca-certificates and tzdata bundles as data, publishes all twelve into one signed seed repository, emits a static-hostable repository root that can be served to QEMU, and proves install from a DNS-resolved hosted-style repository URL.
The design is intentionally narrow:
Lightweight by design. Every always-on subsystem must justify its memory cost, CPU cost, boot-time cost, and security surface.Simple enough to trust. Prefer explicit, testable mechanisms over clever machinery.Secure by construction. Separate address spaces, capability-based handles, small privileged code. Kernel authorization is principal/capability, not uid==0.Correctness proven by tests. Each milestone must build, boot, satisfy its acceptance criterion, and ship executable checks.Modern over legacy. Rebuild tools against the swift-os ABI instead of importing Linux compatibility or old platform assumptions.
See docs/PHILOSOPHY.md for the full project stance.
The public documentation starts at docs/DOCUMENTATION.md. That map now includes role-based paths for first-time operators, deployment owners, administrators, application developers, package maintainers, service operators, AI hosting operators, support engineers, and security reviewers.
Getting Started: build, boot, log in, run commands, and attach QEMU networking.Concepts: core SwiftOS terms, images, filesystem, identity, packages, services, testing, and roadmap boundaries.Installation Guide: choose and verify direct QEMU, UEFI/GPT, graphical smoke, and VirtualBox ARM boot profiles.Deployment Guide: prepare, validate, hand off, and roll back application, AI, package, and appliance deployment candidates.Release Notes: shipped features, verification gates, known limits, and upgrade notes for the current checked-in snapshot.Update And Rollback Guide: rebuild immutable artifacts, update boot profiles, verify candidates, and roll back safely.Update Store: A/B update-store image layout, target commands, and rollback behavior.User Guide: accounts, capabilities, filesystem, process tools, networking tools, and current system limits.Administration Guide: maintain accounts, capability masks, base configuration, package images, and services.Command Reference: command syntax, examples, limits, and acceptance coverage for the current base image and package overlay.Host Tool Reference: host-side package, repository, ports catalog, static-host, hosted URL, base-image, and model-bundle tools.Configuration Reference: build variables, boot profiles, QEMU/test knobs, artifacts, and seeded guest defaults.Testing Guide: choose focused gates, run the full suite, interpret failures, and add host or QEMU acceptance tests.Operations Guide: boot profiles, package overlays, network workflows, AI operation, logging evidence, and verification gates.Networking Guide: virtio-net boot profiles, host forwarding, DNS, TCP/UDP, TLS, IPv6 smoke paths, and network tests.Service Guide: run, observe, test, and design SwiftOS services such ashttpd
,llmd
, echo tools, and the C5a-C5f driver-service smoke.AI Hosting Guide: run local TinyStories inference, serve completions over HTTP, and operate verified model bundles.Performance And Sizing Guide: measure resource usage, throughput guards, service metrics, and current sizing limits.Observability Guide: read boot health, structured log markers, process snapshots, service metrics, and panic evidence.Logging Reference: understand kernel log lines, ring buffers, export samples, filtering, and log authority.Troubleshooting: build, boot, login, filesystem, network, package overlay, LLM, and QEMU test failure diagnosis.Support Guide: evidence collection, support bundles, severity levels, report templates, and handoff checklists.FAQ: common product, install, compatibility, package, networking, AI, and support questions.Examples: copy-paste workflows for common SwiftOS tasks.Compatibility Guide: supported platforms, application paths, porting constraints, packages, and non-goals.Security Guide: current login flow, capability bits, handle rights, confinement, immutable images, and security limits.Base Image: immutable packed filesystem contents, build inputs, and base-image verification.Developer Guide: write native Embedded Swift programs, port C/newlib programs, and stage binaries into the base image.Porting Guide: evaluate and port source-built applications to the SwiftOS ABI, filesystem, package, and test model.Application Cookbook: copy-paste recipes for SwiftOS commands, C utilities, package overlays, and tests.Package Guide: build, inspect, boot, test, and troubleshoot.swpkg
, repository, package-store, ports, static-host, and hosted URL artifacts.Package Management: package-system design, current implementation status, and roadmap boundaries.Package Build Automation Guide: package recipe, seed package fixtures, CI smoke-test, and repository publishing workflow for maintainers.Package Ecosystem Goal: end-state package ecosystem goals and current package roadmap.Package Manager Implementation Plan: historical package-manager implementation plan.Package Manager Session Prompts: reusable package-manager session and milestone prompts.SWPKG Format:.swpkg
container layout, manifest, payload, and verification rules.Package Store Format: package-store image, activation record, and local install layout.Static Package Repository: signed static HTTP catalog layout and repository install flow.API Reference: API recipe index, syscall table, structure layouts, handle rights, native Swift bridge, and compatibility API notes.Server Software Catalog: prioritized server packages, current package limits, and porting prerequisites.Ports Seed Catalog: seed ports catalog and recipe validation rules.SMP Mutable State Audit: machine-checked SMP mutable-state inventory.Next Session: current handoff notes for the next engineering session.
EL0 userland native Swift coreutils + network tools; future Swift apps, Node.js, JVM (busybox: legacy bring-up)
---------- syscall boundary: swift-os POSIX-like ABI, not Linux ABI
EL1 kernel Embedded Swift: runtime, mm, sched, vfs, drivers, net, security, tty
arch/aarch64 boot (UEFI + direct -kernel fallback), exception vectors, context switch
Key architectural decisions:
Target:aarch64
, QEMUvirt
(primary), QEMU+AAVMF UEFI (primary boot path), VirtualBox ARM (best-effort).make run
defaults to one CPU; SMP hardening has dedicated-smp N
tests and readiness gates.Boot: UEFI (BOOTAA64.EFI
on an ESP in a GPT disk image) is the primary path; direct-kernel
is kept as a fallback.Hardware discovery: a boot-time DTB reader populates a globalPlatform
; driver and PMM initialization read from it instead of hardcoded constants.Kernel language: Embedded Swift, freestanding, no Foundation, no full standard library.Isolation: real MMU-based process isolation, one address space per process.Filesystem: two-tier. A signed packed read-only base image (SWOSBASE v3
) served off a virtio-blk device; a RAM tmpfs for writable scratch. No journaling; data loss on reboot is by design.Security: capability/principal model./etc/swos/passwd
is the identity source;/etc/passwd
is a generated compatibility view for busybox/newlib only.ABI: a small swift-os syscall surface, POSIX-like where useful, explicitly not the Linux syscall ABI.Linking: static userland only; no dynamic .Network: in-kernel, virtio-net, sans-IO pure-Swift protocol core; capability-gated socket ABI.
See docs/ARCHITECTURE.md for subsystem boundaries, driver strategy, long-horizon runtime constraints, and explicit non-goals.
boot/
efi/ UEFI (AArch64 PE32+): .c, efi.h, kernel_blob.S
kernel/
arch/aarch64/ boot.S, exception vectors, context switch, linker script, FDT reader, platform
crypto/ ChaCha20-Poly1305 AEAD (TLS groundwork)
drivers/ PL011 UART, GICv2, virtio-blk, virtio-net, virtio-input, framebuffer
mm/ physical page allocator (PMM), virtual memory / address space management
net/ sans-IO Ethernet/ARP/IPv4/ICMP/UDP/TCP/DNS core; socket layer
runtime/ freestanding runtime support for Embedded Swift
sched/ preemptive process/thread scheduler, futex
security/ process security context, principal/capability model
signal/ signal delivery, pending mask
syscall/ syscall dispatch
timer/ ARM generic timer, PL031 RTC
tty/ line discipline, termios, canonical/raw mode
user/ ELF , process/thread lifecycle, exec
vfs/ VFS (disk-backed base + tmpfs), fcntl, capability enforcement
userland/
lib/ swift_user bridge (svc ABI, allocator, atomic ops, putchar),
crt0, newlib syscall stubs, compat headers
compat/ POSIX/Linux shim headers and stubs for busybox/newlib cross-build
busybox/ busybox 1.38.0 build config
*.swift native Swift EL0 utilities: ls cat echo pwd ps top id mkdir rmdir
rm mv chmod chown head touch wc date calc kv nslookup udpecho
tcpecho tcpget httpd console-login threadsdemo …
hello.c original bring-up C program (kept for reference)
base/ host seed tree for the packed base image (etc, www, …)
tools/
basepack.swift host-side packed base image packer
scripts/ build-busybox.sh, build-newlib.sh, make-disk.sh, …
tests/ host unit tests (Swift) + QEMU boot assertion scripts (bash)
docs/ philosophy, architecture, package ecosystem, hardware/toolchain notes
The default tool paths are pinned for the current macOS Apple Silicon bring-up
environment in docs/NOTES.md. They can be overridden from
make
if your local installation differs.
Prerequisites (run once):
make newlib # cross-build newlib 4.6.0 into ./sysroot
make busybox # cross-build busybox 1.38.0
Then:
make tools-check
make build
make run # direct -kernel boot with base.img attached
UEFI boot (primary path):
make disk # build BOOTAA64.EFI + GPT disk image (build/swift-os.img)
make disk-run # boot under QEMU+AAVMF from the GPT disk
Other useful targets:
make test # full test suite: host unit tests + QEMU boot assertions
make uefi-run # UEFI boot from a QEMU virtual FAT directory (quick, no GPT)
make debug # boot QEMU d with a gdbstub on :1234
make gdb # attach aarch64-elf-gdb to the d kernel
make base-image # pack build/base.img from base/ + staged userland ELFs
make clean
make run
starts:
qemu-system-aarch64 -M virt -cpu cortex-a72 -m 256M -nographic \
-global virtio-mmio.force-legacy=false \
-device ,file=<dtb>,addr=...,force-raw=on \
-drive file=build/base.img,...,readonly=on \
-device virtio-blk-device,drive=swosbase \
-kernel build/kernel.elf
make disk-run
starts:
qemu-system-aarch64 -M virt,acpi=off -cpu cortex-a72 -m 256M -nographic \
-bios <AAVMF_CODE> \
-drive file=build/swift-os.img,format=raw,if=virtio \
<base.img as second virtio-blk>
Exit QEMU serial with Ctrl-A X
.
The current pinned target is:
aarch64-none-none-elf
The kernel is built with a swift.org Embedded Swift toolchain, LLVM clang
,
ld.lld
, llvm-objcopy
, and QEMU. Exact versions and the rationale for the current flags live in docs/NOTES.md; do not guess or cargo-cult Embedded Swift flags across toolchain versions.
Work is organized in phases. Each milestone must remain buildable, bootable, tested, and reviewable before moving on.
The bring-up arc proved the kernel and syscall surface end to end. busybox was the bring-up userland (a legacy tool); the native Swift userland is now the direction.
M0: boot skeleton and UART output.**Done.**M1: runtime hooks, exception vectors, heap, page allocator.**Done.**M2: GIC and timer interrupts.**Done.**M3: virtual memory and MMU.**Done.**M4: processes, scheduling, EL0 trap path.**Done.**M5: syscall entry and VFS skeleton.**Done.**M6: libc subset, ELF64 , spawn.**Done.**M7: TTY, termios, signals.**Done.**M8: static busyboxsh
withls
,cat
, andecho
.**Done.**M9: HAL + runtime hardware discovery from DTB.**Done.**M10 (a/b/c): UEFI boot from a GPT disk image under QEMU+AAVMF.**Done.**M10.5: VirtualBox ARM validation prep.**Done (prep only; manual run needed).**M11 (a–d): virtio-blk driver, packedSWOSBASE
format + host packer, base FS served read-only from disk, disk-first executable lookup, embedded kernel blob removed.**Done.**M12 (a–d): capability/principal security core, identity store, console-login as init, SHA-256 password hashing.**Done.**M13 (a–c): VFS capability enforcement at open time, tmpfs mutation gating, file ownership +ls -l
.**Done.**Post-M13 follow-ups: shell I/O redirection +fcntl
; native Swift userland coreutils (ls cat echo pwd ps top id mkdir rmdir rm mv chmod chown head touch wc date calc kv …
); busyboxvi
; PL031 RTC + per-file mtime; free-capable allocator for Swift ARC; threading (thread_create
+futex
); process teardown frame reclaim.**Done.**N-series (networking): virtio-net driver, sans-IO Ethernet/ARP/IPv4/ICMP/ UDP/TCP/DNS core, capability-gated socket syscalls,/bin/udpecho
,/bin/tcpecho
,/bin/tcpget
,/bin/httpd
(concurrent poll-driven static-file HTTP server),/bin/nslookup
, DNS resolver, TCP robustness + ephemeral-port allocator, ChaCha20-Poly1305 AEAD (TLS groundwork).Done.
The dedicated plan lives in docs/RISK_REMEDIATION_ROADMAP.md
. It completes the
capability/handle model (C-arc), treats SMP as a required deliverable (S0–S5
series), moves drivers and the network stack toward the documented restartable
userland service model, and makes global kernel state concurrent-safe. Each
sub-milestone follows the strict rule: builds, boots (including -smp N
), has tests, is committed, then review. SMP and "restartable services" are tracked work, not non-goals; C5a-C5f now prove the supervisor/service IPC shape, virtio-input discovery metadata, fallback pseudo-device discovery, surfaced virtio-mmio metadata, opaque device-handle transfer, withheld hardware authority, and metadata-only grant rights before real device handoff lands.
Toward a complete hosting/embedded OS: richer observability and metrics; production update channels beyond the checked A/B validation paths; kernel-slot health confirmation; the native Swift application runtime plus Node.js and JVM hosting; the embedded footprint profile (small static image, deterministic boot, fewer services); TLS 1.3 record layer and handshake; Cells (kernel-native capability-based isolated execution domains); and a hot-update-friendly kernel structure. Recorded, not implemented early.
These boundaries are deliberate. They are how the OS stays minimal — it removes legacy surface rather than carrying it. They are not constraints on the hosting/embedded/desktop profiles, which the same core already serves; they constrain how it serves them.
- Linux ABI compatibility;
- dynamic linking;
- amd64/x86-64 support;
- full Cells isolation (the architecture is designed for it; the implementation
is future work — see
docs/ARCHITECTURE.md
anddocs/CAPABILITIES.md
); - Docker/OCI compatibility;
- journaling or persistent writable filesystem guarantees;
- broad loadable kernel-module ABI;
- GPU/NPU acceleration;
- graphics as the primarydisplay path (a basic VT100 framebuffer console + virtio-input keyboard exist for QEMU graphical mode; desktop use is not excluded, but a rich display stack is Phase 2 work, not a current target).
(See the risk remediation roadmap for the current status of SMP and restartable driver services — they are no longer blanket non-goals.)
SMP is no longer a blanket non-goal. It is the subject of the active S0–S5 series in
docs/RISK_REMEDIATION_ROADMAP.md
. Until that arc lands the practical system remains
single-core (and make run
/ tests default to 1 CPU). The plan also covers completing the handle-based capability model and moving toward restartable userland driver services.
Networking is not a non-goal: a TCP/UDP/ARP/ICMP/DNS stack and a set of userland network tools are present and tested. The long-term target (userland network service reachable only via capability-gated IPC, after the C-arc + basic SMP) is recorded in the risk remediation roadmap. What remains future work today is TLS in userland, high-pps optimizations, and the actual service-ization.
These boundaries are not accidental omissions. They keep the kernel surface small enough to measure, test, and trust.
swift-os is licensed under the Apache License, Version 2.0 — see LICENSE and
. New source files we author carry an
NOTICE
// SPDX-License-Identifier: Apache-2.0
header.Bundled third-party components keep their own licenses and are not covered by
the Apache license above: userland/busybox
(GPL-2.0-only) and libc/newlib
(BSD-style / permissive). See NOTICE
for details.