SwiftOS Documentation
This page is the public documentation map for SwiftOS, the operating system implemented in Embedded Swift and shipped as a small, static, capability-aware AArch64 system image.
SwiftOS documentation is split by audience. Start with the guide that matches what you are trying to do, then use the reference documents for exact ABI and format details.
Role-Based Paths
Use these paths when you are new to the repository or handing documentation to a specific audience.
| Role | Read first | Then prove |
|---|---|---|
| First-time operator | Getting Started, User Guide, Command Reference | ./tests/boot_test.sh, then the command-specific test |
| Release or deployment owner | Installation Guide, Deployment Guide, Update And Rollback Guide | Candidate manifest, serial log, rollback artifact, and the matching validation matrix |
| System administrator | Administration Guide, Security Guide, Support Guide | Account or capability evidence bundle plus ./tests/console_login_test.sh |
| Application developer | Developer Guide, Application Cookbook, API Reference | Focused QEMU test, command-reference entry, and application handoff record |
| Package or port maintainer | Package Guide, Package Build Automation Guide, Porting Guide | Package fixture, repository install smoke, and ports seed verification |
| Network or service operator | Networking Guide, Service Guide, Observability Guide | Readiness marker, host client output, and the focused network/service test |
| AI hosting operator | AI Hosting Guide, Performance And Sizing Guide, Release Notes | /health, /completion, /metrics, and ./tests/llm_serve_test.sh |
| Support engineer | Troubleshooting, Support Guide, Logging Reference | Support bundle, first failure marker, and exact reproduction command |
| Security reviewer | Security Guide, Capabilities, Architecture | Capability/handle test evidence and current-roadmap gap list |
Start Here
| Need | Document |
|---|---|
| Build, boot, log in, run commands, and use QEMU | Getting Started |
| Learn the core SwiftOS concepts and terminology | Concepts |
| Understand the design philosophy and tradeoffs | Philosophy |
| Choose and verify a direct, UEFI, graphical, or VirtualBox boot profile | Installation Guide |
| Run the best-effort VirtualBox ARM validation path | VirtualBox Guide |
| Prepare, validate, hand off, and roll back deployment candidates | Deployment Guide |
| Review shipped features, verification gates, and known limits | Release Notes |
| Rebuild, update, validate, and roll back immutable SwiftOS artifacts | Update And Rollback Guide |
| Use the installed system from the serial console | User Guide |
| Administer accounts, capabilities, base configuration, packages, and services | Administration Guide |
| Look up command syntax, examples, limits, and acceptance coverage | Command Reference |
| Look up host-side package, repository, ports, static-host, hosted URL, image, and model tools | Host Tool Reference |
Decide where a setting lives and how to change it when /etc is read-only |
Settings Guide |
| Find build, boot, test, QEMU, board, and guest defaults | Configuration Reference |
| Choose, run, interpret, and add validation tests | Testing Guide |
| Operate boot profiles, networking workflows, driver-service smoke, package overlays, and verification gates | Operations Guide |
| Run and verify virtio-net, host forwarding, DNS, TCP, UDP, TLS, and IPv6 paths | Networking Guide |
| Run, observe, test, and design SwiftOS services and the C5 driver-service/device-authority smoke | Service Guide |
| Host TinyStories inference with model bundles, health checks, and metrics | AI Hosting Guide |
| Measure resource usage, throughput guards, service metrics, and sizing limits | Performance And Sizing Guide |
| Read boot health, service metrics, process snapshots, and log evidence | Observability Guide |
| Understand kernel log lines, ring buffers, export samples, and log authority | Logging Reference |
| Diagnose build, boot, login, filesystem, network, package, and test failures | Troubleshooting |
| Collect logs, evidence, severity, and report details for support handoff | Support Guide |
| Answer common product, install, compatibility, package, networking, AI, and support questions | FAQ |
| Follow copy-paste workflows for common tasks | Examples |
| Check hardware, application, package, runtime, and network compatibility | Compatibility Guide |
| Understand current login, capabilities, handle rights, and security limits | Security Guide |
| Write native SwiftOS user programs | Developer Guide |
| Evaluate and port source-built applications to SwiftOS | Porting Guide |
| Follow copy-paste application build and test recipes | Application Cookbook |
| Find API recipes, call the EL0 syscall ABI, or use the Swift bridge directly | API Reference |
| Understand the system architecture and non-goals | Architecture |
| Understand handles, capabilities, and the isolation roadmap | Capabilities |
| Read the recorded per-process namespace generalization (record-only design note) | Namespace Design |
| Read the recorded SwiftCube orchestrator design (record-only design note) | SwiftCube Design |
| Understand the immutable base image | Base Image |
| Understand the A/B update-store image, target commands, and rollback flow | Update Store |
| Build, inspect, boot, test, and troubleshoot package, repository, ports, and static-host artifacts | Package Guide |
| Understand package format and package-manager direction | Package Management |
| Design package recipes, seed package fixtures, CI smoke tests, static-host, and hosted URL publishing | Package Build Automation Guide |
Read the .swpkg package container format |
SWPKG Format |
| Read the package-store image and activation-record format | Package Store Format |
| Read the signed static HTTP package repository format | Static Package Repository |
| Plan server package priorities and porting prerequisites | Server Software Catalog |
| Review the current hardening roadmap | Risk Remediation Roadmap |
| Review detailed milestone history | Notes |
Package Documentation Map
Use this map when a package task or package failure report is too specific for the top-level role paths. The package documents are split on purpose: operator workflows, maintainer automation, byte formats, activation state, and signed repository metadata each have a different proof path.
| Question | Start With | Reference Detail | Proof |
|---|---|---|---|
| Which package install workflow works today? | Package Guide | Command Reference for target-side pkg syntax |
Matching package test from the guide's workflow table |
| How do I build, review, or publish checked package fixtures? | Package Build Automation Guide | Ports Seed Catalog for checked recipes | make ports-recipe-test, package-specific fixture target, or seed/static-host test |
Why does a .swpkg fail verification? |
SWPKG Format | Host Tool Reference for build/swpkg commands |
make swpkg package-fixture and tests/swpkg_tool_test.swift |
Why did package content not mount under /usr? |
Package Store Format | Troubleshooting for boot and fixture symptoms | make package-store-test or make package-local-install-test |
Why did pkg update or hosted install fail? |
Static Package Repository | Host Tool Reference for build/pkgrepo and hosted URL verifier syntax |
make package-repo-install-test, make ports-hosted-url-verify-test, or DNS static-host test |
| What is planned but not implemented yet? | Package Management | Package Ecosystem Goal and package roadmap prompts | Roadmap milestone acceptance criteria, not current user commands |
Maintainer Planning And Audit Artifacts
These files are useful for maintainers and reviewers. They are not the primary user path, but they are part of the checked-in documentation set and should stay discoverable.
| Need | Document |
|---|---|
| Track the package ecosystem end state and current package roadmap | Package Ecosystem Goal |
| Read the historical package-manager implementation plan | Package Manager Implementation Plan |
| Reuse package-manager session prompts and milestone prompts | Package Manager Session Prompts |
| Review the current seed ports catalog and recipe validation rules | Ports Seed Catalog |
| Review the machine-checked SMP mutable-state inventory | SMP Mutable State Audit |
| Reproduce the bare-metal Hetzner Cloud ARM VM bring-up | Hetzner Deployment |
| Pick up the latest handoff notes for the next engineering session | Next Session |
Documentation Contract
The consumer-facing documents describe the current checked-in system, not only the long-term design. When the design and implementation differ, these documents call out the current behavior and point to the roadmap for future work.
Normative API details live in:
userland/lib/syscall.hfor syscall numbers, low-level wrappers, mmap constants, and handle-right constants.userland/lib/swift_user.hfor the native Embedded Swift bridge.userland/lib/fs.h,userland/lib/termios.h, anduserland/compat/*for C and newlib-facing source layouts.kernel/syscall/syscall.swiftfor the kernel dispatcher.kernel/vfs/handle.swiftfor handle kinds, rights, and explicit spawn inheritance structures.
The API reference mirrors those sources so application authors can work from one document, but the headers remain the build-time contract.
Installation and boot profile procedures live in
INSTALLATION_GUIDE.md, deployment candidate runbooks
live in DEPLOYMENT_GUIDE.md, administrative procedures
live in ADMINISTRATION_GUIDE.md, operational
procedures live in OPERATIONS_GUIDE.md, update and
rollback runbooks live in UPDATE_GUIDE.md, networking
runbooks live in NETWORKING_GUIDE.md, service lifecycle
rules live in SERVICE_GUIDE.md, observability procedures
live in OBSERVABILITY_GUIDE.md, and the logging
reference lives in LOGGING.md. Package authoring procedures live
in PACKAGE_BUILD_AUTOMATION.md. Keep them aligned
with the acceptance tests under tests/; a command in the installation,
deployment, operations, networking, service, observability, logging, or package
automation guide should either be a normal manual workflow or have a nearby test
that proves the same path.
Product State
SwiftOS is past bring-up and can boot under QEMU, authenticate users, run a
native Swift userland, serve files from a read-only base image, allocate tmpfs
scratch space, run a small TCP/IP stack, and execute user programs through its
own POSIX-like syscall surface. Package fixtures cover local .swpkg
installation, signed static repository installation, Lua, zlib, bzip2, zstd,
ca-certificates, pcre2, tzdata, nginx, and sqlite port repository fixtures, and a
static-hostable seed repository layout that can be served to QEMU through a
direct or DNS-resolved hosted-style repository URL.
Current product-shaping work is tracked in RISK_REMEDIATION_ROADMAP.md. The most important theme is turning the proven bring-up system into a stronger application-hosting platform: tighter handle authority, SMP hardening, userland service boundaries, and restartable services.
Terminology
- SwiftOS / swift-os: The operating system. The repository and many files use
swift-os; product-facing prose may useSwiftOS. - EL0: User mode on AArch64.
- EL1: Kernel mode on AArch64.
- Base image: The immutable read-only filesystem image packed from
base/plus staged/binprograms. - tmpfs: Writable RAM scratch storage. Data is intentionally lost on reboot.
- Handle: A small per-process descriptor naming a kernel object and carrying rights.
- Capability: Coarse process authority such as filesystem read, tmpfs write, spawning, inspection, or networking.
- Native Swift userland: Programs compiled with Embedded Swift against
userland/lib/swift_user.*. - newlib compat userland: C or ported programs linked statically through the newlib bottom end and compatibility shims.
Versioning Policy
There is no stable external ABI version number yet. Treat the current syscall numbers and structure layouts as the ABI for this repository revision. When the ABI is changed, update the headers, the API reference, tests, and the relevant milestone notes in the same commit.
For package metadata, the documented ABI fields are in PACKAGE_MANAGEMENT.md and SWPKG_FORMAT.md. Package-store image fields are documented in PKGSTORE_FORMAT.md.
Contributing Documentation
When adding public docs:
- Prefer examples that are executable on the current system.
- Link to the source header or implementation that defines the contract.
- Separate current behavior from future roadmap language.
- Keep all docs in English.
- Run
make docs-testfor Markdown fence, local-link/anchor, API table, Swift bridge, documentation map, command-reference, host tool reference, and port recipe reference integrity. - Run at least the relevant build or test target before committing.
- For operational docs, name the acceptance test that proves each workflow when such a test exists.