SwiftOS Configuration Reference

This reference documents the build, boot, test, and guest defaults used by the current checked-in SwiftOS system. It is the place to look when you need the exact Make variables, generated artifacts, QEMU profiles, seeded accounts, runtime paths, or acceptance-test knobs.

Use this with:

• GETTING_STARTED.md for the first boot.
• INSTALLATION_GUIDE.md for choosing and verifying direct, UEFI, graphical, and VirtualBox boot profiles.
• OPERATIONS_GUIDE.md for operator workflows.
• PACKAGE_GUIDE.md for package artifact and package-store workflows.
• COMMAND_REFERENCE.md for in-guest command syntax.
• DEVELOPER_GUIDE.md for adding userland programs.

Defaults At A Glance

The target is static and intentionally small. There is no Linux syscall ABI and no dynamic loader. Writable guest state is split by lifetime: ephemeral /tmp (tmpfs) and the persistent /data tier (datafs, on a dedicated virtio-blk disk). There is still no general-purpose persistent writable root filesystem — the base image stays immutable. To decide where a given setting belongs, see SETTINGS_GUIDE.md.

Choose A Configuration Change

Use this table before editing Make variables, QEMU commands, or guest seed files. It names the configuration source, the rebuild step, and the proof that the change took effect.

Toolchain Variables

The top-level Makefile is the source of truth for host tool defaults. Every variable below can be overridden on the make command line.

Examples:

make SWIFTC=/path/to/swiftc build
make QEMU=/path/to/qemu-system-aarch64 run
make AAVMF_CODE=/path/to/edk2-aarch64-code.fd disk-run

Check resolved tools:

make tools-check

Embedded Swift flags are toolchain-version-specific. Confirm the current Makefile and NOTES.md before changing them.

Image Build Variables

Board Selection

BOARD selects the target board configuration.

Examples:

make BOARD=qemu build
make BOARD=virtualbox disk

Changing BOARD changes the link/load base and board compile defines. The Makefile tracks the active board in build/.board and removes board-dependent artifacts when the value changes. Board-independent, slow artifacts such as busybox, the packed base image, and the newlib sysroot are kept.

Build Targets

make clean intentionally removes generated artifacts, not downloaded toolchains. Re-run make model, make newlib, or make busybox when those inputs are missing or stale.

Build Artifacts

Direct QEMU Profile

The default direct boot profile is:

-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
-kernel build/kernel.elf

Important details:

• force-legacy=false selects the modern virtio-mmio transport used by the drivers.
• The DTB is loaded into guest RAM at 0x4FF00000.
• The base image is read-only and identified as swosbase.
• make run does not attach a NIC by default.

Network QEMU Profile

Attach virtio-net when running socket programs. This common profile forwards host TCP 8080 to guest TCP 8080, and host TCP/UDP 5555 to guest port 5555:

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

Guest defaults:

The seeded root principal has capNet; user and guest do not. /bin/httpd and /bin/llmd both bind guest TCP port 8080, so run one at a time or use separate boots.

UEFI And Graphical Profiles

UEFI boot uses AAVMF and an EFI System Partition containing \EFI\BOOT\BOOTAA64.EFI.

Virtual-FAT UEFI boot:

make uefi-run

GPT disk UEFI boot:

make disk-run

Graphical smoke boot:

make run-gfx

The graphical profile adds:

• ramfb for an EFI GOP framebuffer.
• virtio-keyboard-device for input smoke coverage.
• -display cocoa on macOS hosts.
• -serial stdio so serial logs remain visible.

The current product shell remains serial-first.

Guest Defaults

Accounts

The seeded identity source is base/etc/swos/passwd.

The compatibility files base/etc/passwd and base/etc/group are generated or maintained for POSIX-like tools. Kernel authorization uses SwiftOS principals, capabilities, and handle rights.

SSH Preflight Files

The default base image includes development SSH material for the checked QEMU preflights:

Replace this material when building a deploy-specific artifact. The checked-in SSHD host-key seed and SSH client trust anchor are deterministic test material, not per-instance production identity or deploy-specific trust policy. Generate deploy-specific SSHD material, then stage it into the base image:

build/sshkey seed --out support/keys/ssh_host_ed25519_seed
build/sshkey seed --out support/keys/ssh_kex_seed
make SSHD_HOST_SEED_FILE=support/keys/ssh_host_ed25519_seed \
  SSHD_KEX_SEED_FILE=support/keys/ssh_kex_seed \
  SSHD_AUTHORIZED_KEYS_FILE=support/keys/authorized_keys \
  base-image
build/sshkey known-host \
  --host HOST \
  --seed-file support/keys/ssh_host_ed25519_seed

SSHD_HOST_SEED_FILE becomes /etc/ssh/ssh_host_ed25519_seed; SSHD_KEX_SEED_FILE becomes /etc/ssh/ssh_kex_seed; SSHD_AUTHORIZED_KEYS_FILE becomes /etc/ssh/authorized_keys; NET_IPV6_CONFIG_FILE becomes /etc/swos/net-ipv6; SWOS_SERVICES_FILE becomes /etc/swos/services when a custom service manifest is supplied.

Set SSHD_DEPLOY_EVIDENCE_DIR=PATH when running tests/sshd_deploy_preflight_test.sh to save a Hetzner-style handoff bundle with public deploy evidence, artifact hashes, and the serial log. Private deploy host-key, KEX, and login key material is intentionally omitted.

Filesystem

To change installed base files, edit base/ or staged userland sources, then rebuild build/base.img.

To change package payload files, rebuild the package fixture or the relevant .swpkg package.

Console

/bin/swos-init runs as the first user process when present in the base image. It reads /etc/swos/services, starts allowlisted boot services such as sshd or sshd6, and then replaces itself with /bin/console-login unless an opt-in supervised service token keeps it running as a restart loop. If swos-init is missing, the kernel falls back to /bin/console-login directly.

After successful authentication, console-login starts the configured shell. When the shell exits, init/login starts again for the next session.

The default shell is busybox ash, staged as /bin/busybox.

Package Overlay Configuration

The package fixture builds:

Build and verify it:

make package-fixture

Boot with the payload attached:

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

Package overlays are read-only. The current target-side install path is the narrow local .swpkg flow backed by a writable package-store image:

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

Repository install with name-based dependency resolution works for signed fixtures. Remove, upgrade, rollback, public hosting, and version-constraint solving remain future package-manager work.

For the package-store boot profile and current package limits, see PACKAGE_GUIDE.md.

Test Harness Knobs

Most acceptance tests accept a small set of environment overrides.

Network tests choose high host ports automatically when their override is not set. Use overrides when running multiple trees on one host or when a firewall allows only a specific range.

Examples:

QEMU=/opt/qemu/bin/qemu-system-aarch64 ./tests/boot_test.sh
TIMEOUT=180 ./tests/smp_boot_test.sh
HTTPD_HOST_PORT=18080 ./tests/httpd_test.sh
LLMD_HOST_PORT=18081 ./tests/llm_serve_test.sh
SMP_CPUS=4 UEFI_BOOT=disk ./tests/uefi_boot_test.sh
SMP_CPUS=4 SMP_DTB=build/virt-smp4.dtb ./tests/driver_service_test.sh

Common Configuration Changes

Use A Different Swift Toolchain

make TOOLCHAIN=/path/to/swift-toolchain build

Then run:

make tools-check
make build

If Embedded Swift flags changed between toolchains, update the Makefile and document the decision in NOTES.md.

Change Guest Base Files

1. Edit files under base/.
2. Rebuild the base image:

make base-image

3. Boot or test with the rebuilt build/base.img.

Add A Native /bin Program

Follow DEVELOPER_GUIDE.md. The short version is:

1. Add the userland source.
2. Add a build rule and ELF variable in the Makefile.
3. Stage the resulting ELF in the $(BASE_IMG) rule.
4. Add an acceptance test.
5. Update COMMAND_REFERENCE.md.

Change Seeded Accounts

1. Edit base/etc/swos/passwd.
2. Keep compatibility views aligned when relevant.
3. Rebuild build/base.img.
4. Run login and capability tests:

./tests/console_login_test.sh
./tests/cap_enforce_test.sh

Change Network Ports

For manual QEMU runs, edit the hostfwd= entries in the QEMU command. For tests, prefer the port override variables listed above.

After changing socket behavior, run the relevant acceptance tests:

./tests/httpd_test.sh
./tests/tcp_echo_test.sh
./tests/udp_echo_test.sh
./tests/tcp_connect_test.sh
./tests/dns_test.sh
./tests/llm_serve_test.sh

Change Package Fixture Contents

1. Edit fixtures/pkghello/manifest.json or the staged package root rule.
2. Rebuild:

make package-fixture

3. Verify in QEMU:

make package-overlay-test

Verification Matrix

When in doubt, run make test. It is the broad acceptance gate for this repository revision.

Not Configurable Yet

These are intentional current limits:

• No Linux ABI mode.
• No dynamic loader.
• No general-purpose persistent writable root filesystem. The base image stays immutable; persistent state goes on the narrow /data tier (datafs), which has no journaling and relies on honest fsync plus application journaling for crash-safety. See SETTINGS_GUIDE.md.
• No public hosted package channel, package upgrade, remove, rollback, or version-constraint solver. Local pkg install FILE and signed pkg repo set/pkg update [URL]/ pkg install NAME work for signed fixtures when a writable package-store image is attached, including name-based dependency resolution, streamed repository package installs, and rejection paths for expired or incompatible catalogs and package hash mismatches.
• No production certificate store for tlsget.
• No default graphical desktop shell.

Track product hardening in RISK_REMEDIATION_ROADMAP.md.

Edit this page on GitHub