SwiftOS Operations Guide

This guide is for people who boot, test, validate, or operate a SwiftOS image. It describes the current checked-in system: QEMU virt on AArch64, serial console first, immutable base image, RAM scratch space, capability-scoped user sessions, native Swift tools, networking workflows, package payload overlays, A/B update stores, and AI inference, plus the C5a-C5f restartable driver-service/device-authority smoke.

Use this guide with:

• Getting Started for the first boot.
• Installation Guide for choosing and verifying direct, UEFI, graphical, and VirtualBox boot profiles.
• Deployment Guide for preparing validated deployment candidates and handoff evidence.
• Update And Rollback Guide for rebuilding immutable artifacts, validating candidates, and returning to a known-good image.
• Administration Guide for account, capability, base configuration, package, and service administration.
• User Guide for shell and userland behavior.
• Configuration Reference for build variables, boot defaults, QEMU profiles, and test knobs.
• Testing Guide for choosing focused gates, interpreting failures, and adding validation tests.
• Package Guide for .swpkg artifacts, payload overlays, package-store images, and package verification workflows.
• Networking Guide for virtio-net profiles, host forwarding, DNS, TCP/UDP, TLS, IPv6 smoke paths, and network test coverage.
• Service Guide for service lifecycle, readiness markers, ports, health checks, and service authoring rules.
• AI Hosting Guide for local inference, serving daemon, model bundles, health checks, and metrics.
• Observability Guide for boot health markers, structured log smoke paths, process snapshots, service metrics, and panic evidence.
• Troubleshooting when a build, boot, login, or network path fails.
• Support Guide for evidence collection and handoff checklists.
• Examples for copy-paste operational recipes.

Operating Model

SwiftOS is intentionally small and static.

The most important operational consequence is that a running guest has no persistent writable root. Rebuild the base image or attach a package payload to change installed software. Use /tmp only for runtime scratch.

Choose An Operational Workflow

Start from the operational task, then use the narrowest profile and proof that answers it. Keep the serial log whenever another person needs to reproduce the run.

Artifact Map

make clean removes build products but not downloaded toolchains. make newlib, make busybox, and make model are slower setup paths and are usually run only when their artifacts are missing or stale.

Boot Profiles

Direct Serial Boot

Use this for day-to-day kernel and userland work:

make build base-image build/virt.dtb
make run

The direct path loads build/kernel.elf, attaches build/base.img, and mirrors the guest console to the terminal.

UEFI Disk Boot

Use this when validating firmware handoff, the GPT image, or the primary boot path:

make disk base-image
make disk-run

The disk image contains the EFI System Partition and loader. The base filesystem is still attached as a separate read-only virtio-blk disk.

Graphical Smoke Boot

Use this only for framebuffer/input smoke checks:

make run-gfx

The product shell is still serial-first. The graphical path exists to verify the UEFI framebuffer and virtio input path, not to provide a desktop environment.

Network Boot

Networking requires a NIC in the QEMU command. The common validation profile forwards host TCP 8080 to guest TCP 8080 and host TCP/UDP 5555 to guest port 5555. For service-specific profiles and troubleshooting, see NETWORKING_GUIDE.md.

make build base-image build/virt.dtb

qemu-system-aarch64 -M virt -cpu cortex-a72 -m 256M -nographic \
  -global virtio-mmio.force-legacy=false \
  -device loader,file=build/virt.dtb,addr=0x4FF00000,force-raw=on \
  -drive file=build/base.img,format=raw,if=none,id=swosbase,readonly=on \
  -device virtio-blk-device,drive=swosbase \
  -netdev user,id=n0,hostfwd=tcp:127.0.0.1:8080-:8080,hostfwd=tcp:127.0.0.1:5555-:5555,hostfwd=udp:127.0.0.1:5555-:5555 \
  -device virtio-net-device,netdev=n0 \
  -kernel build/kernel.elf

Inside the guest, log in as root before running socket programs. The seeded root principal has capNet; user and guest do not.

Package Overlay Boot

Package payload overlays are current functionality. They are read-only VFS overlays attached at boot. For the complete package runbook, including package-store activation, local pkg install FILE, and signed repository install, see PACKAGE_GUIDE.md.

Build the sample package and boot with the payload image:

make package-fixture

qemu-system-aarch64 -M virt -cpu cortex-a72 -m 256M -nographic -no-reboot \
  -global virtio-mmio.force-legacy=false \
  -device loader,file=build/virt.dtb,addr=0x4FF00000,force-raw=on \
  -drive file=build/base.img,format=raw,if=none,id=swosbase,readonly=on \
  -device virtio-blk-device,drive=swosbase \
  -drive file=build/pkghello-payload.img,format=raw,if=none,id=swospkg0,readonly=on \
  -device virtio-blk-device,drive=swospkg0 \
  -kernel build/kernel.elf

Inside the guest:

/usr/bin/pkghello

Expected output:

pkghello: hello from package overlay

For package format details, see SWPKG_FORMAT.md, PKGSTORE_FORMAT.md, and PACKAGE_MANAGEMENT.md.

Package Store Boot

Package-store boot activation is current functionality. Build the sample store and boot with it attached:

make package-store-fixture

qemu-system-aarch64 -M virt -cpu cortex-a72 -m 256M -nographic -no-reboot \
  -global virtio-mmio.force-legacy=false \
  -device loader,file=build/virt.dtb,addr=0x4FF00000,force-raw=on \
  -drive file=build/base.img,format=raw,if=none,id=swosbase,readonly=on \
  -device virtio-blk-device,drive=swosbase \
  -drive file=build/pkgstore-pkghello.img,format=raw,if=none,id=swpkgstore \
  -device virtio-blk-device,drive=swpkgstore \
  -kernel build/kernel.elf

Inside the guest, /usr/bin/pkghello should produce the same output as the direct overlay path. Acceptance coverage: make package-store-test.

Local Package Install

Local target-side install is current functionality. It installs a local .swpkg into a writable package-store image and live-mounts the payload.

Build and test the fixture:

make package-local-install-fixture
make package-local-install-test

Inside the tested guest flow:

pkg list
pkg install /packages/pkghello.swpkg
pkg list
/usr/bin/pkghello

Signed Repository Install

Signed static HTTP repository install is current functionality. It verifies catalog.signed, resolves dependency names, downloads content-addressed .swpkg files, verifies SHA-256, then reuses the local package-store install path.

Build and test the fixture:

make package-repo-fixture
make package-local-install-fixture
make package-repo-install-test

Inside the tested guest flow:

pkg update http://10.0.2.2:<port>/good/aarch64/current
pkg search pkghello
pkg info pkghello
pkg install pkghello
/usr/bin/pkghello

Version-constraint solving, remove, upgrade, rollback, and public hosted channels are not implemented yet. Repository installs stream package payloads directly into the package store.

Update Store Operations

SwiftOS has two checked A/B update paths: SWOSBOOT base-image slots and UEFI ESP kernel slots. They are validation-grade operator paths, not an online package manager or a production update service. The OS can stage and activate already signed artifacts; it does not sign new operating-system images at runtime.

Base-Image A/B Store

The SWOSBOOT store is a dedicated writable virtio-blk disk. Each slot contains a complete signed SWOSBASE image, and normal base-image signature/hash validation still decides whether a slot can mount.

Inside the guest as root, the current target-side flow is:

swos-update
swos-activate

After rebooting into the trial slot:

swos-confirm

If the trial slot is not confirmed within the checked attempt window, the store rolls back to the fallback slot. Acceptance coverage: ./tests/ab_stage_test.sh, ./tests/ab_activate_test.sh, ./tests/ab_confirm_test.sh, ./tests/ab_rollback_test.sh, and ./tests/ab_flush_test.sh.

Kernel-Image ESP Slots

The UEFI disk carries signed kernel slot manifests and kernel slot files on the ESP. The running OS can reach the ESP, copy the active kernel image over the inactive slot, and select that inactive slot in loader-managed kernel-state.

Inside the guest as root:

swos-kstage
swos-kactivate

Then reboot through the UEFI disk profile. The loader verifies the signed manifest's slot hashes, reads the selected slot from kernel-state, and checks the selected kernel image before handoff. Acceptance coverage: ./tests/uefi_kernel_ab_test.sh, ./tests/uefi_kstage_test.sh, ./tests/uefi_kactivate_test.sh, ./tests/uefi_kattempt_test.sh, ./tests/uefi_kconfirm_test.sh, and ./tests/uefi_krollback_test.sh.

For the complete operator runbook and rollback boundaries, see Update And Rollback Guide. For on-disk format and trust details, see Update Store.

Access And Accounts

The default identity store is base/etc/swos/passwd.

Check a session:

id

The current capability model is deliberately explicit. Do not interpret principal 1 as Unix uid 0; the kernel authorizes operations through capability bits and handle rights.

Filesystem Operations

The base image is immutable. Use it for software and defaults:

ls -l /
ls -l /bin
cat /etc/motd
cat /www/index.html

Use /tmp for writable runtime state:

mkdir /tmp/runbook
echo checked >/tmp/runbook/status.txt
cat /tmp/runbook/status.txt
rm /tmp/runbook/status.txt
rmdir /tmp/runbook

Operational rules:

1. A reboot clears /tmp.
2. A base-image change requires rebuilding build/base.img.
3. A package change requires building and attaching a package payload image.
4. A/B update state lives on a dedicated store or ESP, not in the root filesystem namespace.
5. File ownership and modes are visible with ls -l, but the current security boundary is still capability-first.

Process And Resource Monitoring

Use ps for a static process list:

ps

Use top for resource snapshots:

top -b -n 2 -d 1

The summary includes uptime, task counts, aggregate CPU busy/idle, discovered CPU count, per-CPU busy percentages, memory totals, kernel footprint, and a process table. In SMP investigations, capture the CPUs: line together with the SMP_CPUS value used to boot QEMU.

Interactive top repaints the serial terminal and exits on q:

top

For automated logs, prefer top -b. It avoids cursor control and raw terminal mode.

Acceptance coverage: tests/top_test.sh and make smp-cpu-utilization-test.

Networking Operations

All socket tools require a NIC and capNet. See NETWORKING_GUIDE.md for the full network runbook and SERVICE_GUIDE.md for the service catalog, readiness markers, health checks, and service design contract.

HTTP

Inside the guest:

/bin/httpd

From the host:

curl http://127.0.0.1:8080/
curl http://127.0.0.1:8080/hello.txt
curl http://127.0.0.1:8080/sub/
curl -i http://127.0.0.1:8080/nope

/bin/httpd serves /www, returns MIME types for common suffixes, generates directory listings when no index.html exists, and returns 404 for misses.

TCP Echo

Inside the guest:

/bin/tcpecho

From the host:

printf 'hello tcp\n' | nc -w8 127.0.0.1 5555

/bin/tcpecho is a one-shot server. Start it again for another connection.

UDP Echo

Inside the guest:

/bin/udpecho

From the host:

printf 'hello udp' | nc -u -w2 127.0.0.1 5555

/bin/udpecho is also one-shot.

Guest-Initiated TCP

Start a host listener:

printf 'srv-reply\n' | nc -l 5555

Inside the guest:

/bin/tcpget 10.0.2.2 5555

10.0.2.2 is QEMU slirp's host alias.

DNS

With QEMU user networking attached:

/bin/nslookup example.com

The default resolver is QEMU slirp's DNS address (10.0.2.3). Tests may pass an explicit DNS responder address and port.

AI Hosting

SwiftOS has two native Swift TinyStories inference entry points:

For the complete AI runbook, bundle format, HTTP API, and support checklist, see AI_HOSTING_GUIDE.md.

The local inference command and the server intentionally use different default bundles: /bin/llm loads the small fp32 stories260K checkpoint and tok512 tokenizer, while /bin/llmd serves the larger Q8_0 stories15M checkpoint through a verified bundle rooted at /models/stories15M.

Prepare model artifacts:

make model
make base-image

Local Completion

Inside the guest:

/bin/llm
/bin/llm "Once upon a time" 32

Under QEMU TCG this is intentionally slow compared with native execution. Treat it as a correctness and isolation proof, not a performance target.

TCP Model Serving

Boot with virtio-net and host TCP 8080 forwarded to guest TCP 8080. Inside the guest:

/bin/llmd

By default, this resolves /models/stories15M, tries numeric generations newest-first, verifies each generation's manifest.toml, model.bin, and tokenizer.bin, and serves the newest generation whose size and SHA-256 checks pass. The checked-in image includes a deliberately corrupt generation 2 and a valid generation 1 to prove fallback behavior.

To test another supported checkpoint/tokenizer pair without signed-bundle verification, pass both paths explicitly:

/bin/llmd /models/stories260K.bin /models/tok512.bin

From the host:

curl http://127.0.0.1:8080/health
curl -X POST --data "Once upon a time" http://127.0.0.1:8080/completion
curl http://127.0.0.1:8080/metrics

/bin/llmd reports llmd: trust root loaded (/etc/swos/model-signing.pub), llmd: generation 2 rejected (model size/sha256 mismatch) for the intentionally corrupt validation generation, then llmd: bundle stories15M generation 1 verified (ed25519+sha256), llmd: model int8 Q8_0 GS=32, and llmd: serving on 8080 when it is ready. GET /health reports the model shape, such as ok model dim=288 for the default serving bundle. POST /completion uses the request body as the prompt and streams generated text until the HTTP/1.0 connection closes. /metrics reports request count, total generated tokens, last time-to-first-token in milliseconds, and last token rate.

/bin/llmd and /bin/httpd both bind guest TCP port 8080, so run one of them at a time.

Logging And Evidence

Today the strongest operational evidence is the serial log plus test output. Capture serial by running QEMU directly and redirecting stdout:

qemu-system-aarch64 ... >swiftos-serial.log 2>&1

Useful markers:

The kernel has a structured in-memory log ring and sink indirection groundwork; userland log export remains gated by future capability work. See OBSERVABILITY_GUIDE.md for practical signal reading and LOGGING.md for the logging reference.

Verification Matrix

Run the narrowest test that proves the path you touched:

Some QEMU tests drive an interactive serial boot and then attach host clients. If a single smoke test times out on a busy host, rerun that exact test before claiming a product failure; if it repeats, keep the serial log.

Shutdown And Reset

There is no persistent writable guest state to flush. Exit the shell to return to login:

exit

Stop QEMU from the host terminal with Ctrl-C, or from the QEMU monitor sequence Ctrl-A then X when using -nographic.

Operational Limits

Current limits that matter during operation:

• No persistent writable filesystem.
• No remove, upgrade, rollback, public hosted package channel, version-constraint solver yet. Local pkg install FILE and signed pkg repo set/pkg update [URL]/ pkg install NAME exist for .swpkg fixtures, including name-based dependency resolution and streamed repository package installs into the package store.
• No dynamic linker or Linux ABI.
• No graphical desktop shell.
• No production password policy or password rotation workflow.
• No general service manager; most services are started manually from the shell. /bin/swos-init can start a small boot allowlist such as sshd, and has opt-in SSHD restart tokens. C5 proves a focused driver-service restart/device-grant/metadata path, not a general daemon manager.
• SMP hardening can boot and test multiple scheduler CPUs, including the S5f run-any placement gate, but production load balancing and CPU policy remain active hardening work.
• IPv6 support exists in the stack and smoke tests, but Darwin/QEMU hostfwd behavior can limit end-to-end host tests.
• Real virtio drivers and networking are still in the kernel; the roadmap moves more services out of the trusted core.

Document new operational behavior in this guide when it becomes part of the checked-in system.

Edit this page on GitHub