SwiftOS Compatibility Guide

This guide describes what the current SwiftOS system is compatible with, what requires a port, and what is intentionally outside the current product contract. It is written for operators, application authors, and people evaluating whether an existing workload can run on SwiftOS.

For a concise model of SwiftOS concepts and terminology before evaluating compatibility, see CONCEPTS.md.

SwiftOS is a modern, static, capability-aware operating system. Compatibility is source-oriented: rebuild programs for the SwiftOS ABI, link statically, package them into the immutable base image or a read-only package overlay, and design runtime state around explicit capabilities and /tmp scratch storage.

Compatibility Snapshot

For exact build variables and QEMU profiles, see CONFIGURATION_REFERENCE.md. For install and boot profile selection, see INSTALLATION_GUIDE.md. For syscall details, see API_REFERENCE.md. For quick answers to common compatibility questions, see FAQ.md.

What Compatibility Means

SwiftOS does not try to run legacy binaries unchanged. A workload is considered compatible when it can be:

1. Built for aarch64-none-none-elf.
2. Linked statically.
3. Run through the SwiftOS syscall ABI.
4. Given explicit process capabilities and handles.
5. Installed into the base image or a read-only package overlay.
6. Written so durable state is not assumed to live in a mutable root filesystem.

This keeps the trusted core small and makes compatibility testable. It also means many Unix-like source programs can be ported, while Linux binary compatibility is not a goal.

Workload Compatibility Intake

Before starting a port, record the workload shape and the first proof you expect to run. This keeps compatibility discussions grounded in current SwiftOS behavior instead of assumptions from Linux, containers, or desktop operating systems.

Minimal intake record:

Workload:
  name:
  source:
  language/runtime:
  delivery path: base-image | package-overlay | package-store | signed-repository | ports recipe
  required capabilities: capFsRead | capTmpWrite | capNet | none
  installed files:
  runtime state:
  unsupported assumptions:
  first proof:
  current status: compatible | porting candidate | blocked by current limit

Hardware And Platform Compatibility

Supported Now

Not Supported Now

Example primary boot:

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

Example UEFI boot:

make disk base-image
make disk-run

Acceptance coverage: ./tests/boot_test.sh, ./tests/uefi_boot_test.sh, ./tests/smp_boot_test.sh.

Application Compatibility

Native Embedded Swift

Native SwiftOS user programs are the preferred application path.

Current contract:

• Use Embedded Swift.
• Do not import Foundation.
• Use the C bridge in userland/lib/swift_user.h.
• Export a C-callable main.
• Link statically with the SwiftOS userland startup objects.
• Stage the ELF into /bin through make base-image or into a package payload.

Minimal shape:

@_cdecl("main")
func main(_ argc: Int32,
          _ argv: UnsafeMutablePointer<UnsafeMutablePointer<CChar>?>?,
          _ envp: UnsafeMutablePointer<UnsafeMutablePointer<CChar>?>?) -> Int32 {
    swiftos_puts("hello from SwiftOS\n")
    return 0
}

See DEVELOPER_GUIDE.md for the full workflow.

C And newlib Source Ports

C programs can be ported at source level through:

• userland/lib/syscall.h for raw SwiftOS syscall helpers.
• userland/lib/crt0_newlib.S for newlib startup.
• userland/lib/newlib_syscalls.c for libc syscall glue.
• userland/compat/ for POSIX-like compatibility declarations and stubs.

Use this path for small C utilities and selected compatibility software. It is not glibc compatibility and not Linux syscall compatibility.

Build prerequisites:

make newlib
make busybox

Busybox Compatibility

Busybox is present as /bin/busybox and is used as the login shell. It is a bring-up and compatibility tool, not the long-term SwiftOS application model.

Useful current coverage:

/bin/busybox ash
/bin/busybox vi /tmp/note.txt

Acceptance coverage: ./tests/busybox_test.sh, ./tests/vi_test.sh.

Linux Binaries

Linux ELF binaries do not run on SwiftOS.

Reasons:

• Syscall numbers and syscall semantics are SwiftOS-specific.
• There is no Linux dynamic loader.
• There is no glibc or musl userspace ABI contract.
• The security model is capabilities and handles, not Linux uid/capability inheritance.

Port the source instead. For new software, prefer native Embedded Swift.

Runtime Compatibility

The current AI-serving proof path is native Swift:

/bin/llm
/bin/llmd

/bin/llm keeps the small fp32 stories260K console inference path. /bin/llmd defaults to the signed verified Q8_0 stories15M bundle under /models/stories15M and can be started with explicit llmd [model.bin] [tokenizer.bin] paths for supported checkpoint formats without signed-bundle verification.

Acceptance coverage: ./tests/llm_run_test.sh, ./tests/llm_serve_test.sh.

Filesystem And Data Compatibility

SwiftOS has a two-tier filesystem:

Compatible applications should treat installed files as read-only and use /tmp for runtime scratch:

mkdir /tmp/app
echo ok >/tmp/app/status.txt
cat /tmp/app/status.txt

Not supported as current compatibility contracts:

• Persistent mutable root filesystem.
• ext2/ext4/FAT/UFS/ZFS mounting.
• journaling.
• fsck.
• POSIX ACLs.
• Extended attributes.
• User home directories with durable storage.

To change installed files, rebuild the base image:

make base-image

To add package overlay content, build and attach a payload image:

make package-fixture
make package-overlay-test

Networking Compatibility

Socket programs require:

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

For complete launch profiles, host forwarding, DNS, TCP/UDP, TLS, IPv6 smoke paths, and troubleshooting, see NETWORKING_GUIDE.md.

Current user-visible network tools:

Example host forwarding for HTTP-style services:

qemu-system-aarch64 ... \
  -netdev user,id=n0,hostfwd=tcp:127.0.0.1:8080-:8080 \
  -device virtio-net-device,netdev=n0

Then run one TCP 8080 service in the guest:

/bin/httpd
# or
/bin/llmd

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

TLS note: tlsget exercises the current TLS 1.3 client path, but production certificate verification is not complete. Do not treat it as a production trust decision.

Acceptance coverage: ./tests/httpd_test.sh, ./tests/llm_serve_test.sh, ./tests/tcp_echo_test.sh, ./tests/udp_echo_test.sh, ./tests/tcp_connect_test.sh, ./tests/dns_test.sh, ./tests/tls_test.sh, ./tests/ipv6_smoke_test.sh, ./tests/ipv6_tcp_echo_test.sh, and ./tests/ipv6_udp_echo_test.sh.

Security And Identity Compatibility

SwiftOS exposes POSIX-like names where useful, but kernel authorization is not Unix-root-centered.

Current identity source:

Seeded accounts:

File owner and mode metadata are visible through ls -l, chmod, and chown, but current access checks are capability-first. A port that assumes uid == 0 can override all filesystem and network policy must be adapted.

See SECURITY_GUIDE.md and CAPABILITIES.md.

Package And Distribution Compatibility

SwiftOS package compatibility is currently image-based, with a narrow local target-side install path, a signed static HTTP repository fixture, and a local static-host ports fixture for Lua, zlib, bzip2, zstd, xz, libarchive, ca-certificates, OpenSSL, pcre2, tzdata, nginx, and sqlite, plus a hosted-style HTTP repository URL smoke.

Supported now:

• Host .swpkg tool.
• Package manifests.
• Payload extraction.
• Read-only package payload image attachment at boot.
• Preseeded package-store image attachment at boot.
• Local target-side pkg install FILE into a writable package-store image.
• Target-side pkg list for active package-store records.
• Static signed HTTP repository fixture.
• Target-side pkg update URL, pkg search, pkg info, and pkg install NAME for packages present in a verified fixture catalog.
• Guest execution from attached package namespace, proven by /usr/bin/pkghello.
• Source-built Lua, zlib, bzip2, zstd, xz, libarchive, OpenSSL, pcre2, nginx, and sqlite packages plus the ca-certificates/tzdata data packages published into one seed repository.
• Static-hostable repository root under build/ports-static-host-root, proven by make package-static-host-repo-install-test.
• Host-side hosted URL verification for a deployed static root.
• Target-side HTTP repository URLs with DNS hostnames, proven by make package-static-host-dns-repo-install-test.

Not supported now:

• Target-side remove/upgrade transactions.
• Public hosted package repositories and channel policy.
• Version-constraint solving beyond the current name-based fixture dependency path.
• RPM, DEB, APK, Homebrew, Nix, or OCI image compatibility.

Example:

make package-fixture
make package-overlay-test
make package-store-test
make package-local-install-test
make package-repo-install-test
make package-static-host-repo-install-test
make ports-hosted-url-verify-test
make package-static-host-dns-repo-install-test

For the complete package runbook, see PACKAGE_GUIDE.md. See PACKAGE_MANAGEMENT.md, SWPKG_FORMAT.md, PKGSTORE_FORMAT.md, and PKGREPO_FORMAT.md for design and format details.

For a practical source-port workflow, see PORTING_GUIDE.md.

Porting Decision Tree

Use this checklist before porting a program.

Porting Workflow

1. Start with the current docs map:

   less docs/DOCUMENTATION.md
   

2. Confirm the target build works:

   make tools-check
   make build
   

3. Choose the application path:

   • Native Embedded Swift: DEVELOPER_GUIDE.md.
   • C/newlib source port: DEVELOPER_GUIDE.md.
   • Raw syscall C: API_REFERENCE.md.

4. Decide where files live:

   • Installed files: base image or package overlay.
   • Runtime scratch: /tmp.
   • Durable storage: not a current guest contract.

5. Decide capabilities:

   • File reads: capFsRead.
   • tmpfs writes: capTmpWrite.
   • networking: capNet.
   • process inspection: capProcessInspect.

6. Add an acceptance test that boots QEMU when the behavior depends on kernel, VFS, networking, process, or capability behavior.

7. Update user-facing docs and command references when the port becomes a shipped interface.

Common Compatibility Questions

Can I run a Linux static binary?

No. Static linking removes the dynamic loader dependency, but the binary still uses the Linux syscall ABI. Rebuild the program for SwiftOS.

Can I use /tmp like a normal writable filesystem?

Use it for scratch state only. It is RAM-backed and lost on reboot.

Can a fully capable root process write /etc?

No. The base image is read-only by design. Change /etc by rebuilding the base image.

Can I run an HTTP service?

Yes, with a virtio-net boot profile and capNet. Current examples are /bin/httpd and /bin/llmd.

Can I run userland drivers?

Not real hardware drivers yet. C5a-C5f prove the supervisor, endpoint IPC, opaque device handle, discovered virtio-input manifest shape, surfaced virtio-mmio metadata, withheld hardware-authority envelope, and metadata-only grant rights with /bin/drvsvcdemo and /bin/drvinputd, but real MMIO, IRQ, DMA, and virtio-input queue ownership are still roadmap work.

Can I use TLS for production trust decisions?

Not yet. tlsget proves the TLS runtime path, but certificate verification is not complete.

Can I run Node.js or the JVM?

Not today. They are long-horizon goals. Keep ports from depending on choices that would block those runtimes later, but do not document them as current features.

Can I use Docker containers?

No. Future Cells are planned as SwiftOS-native isolated execution domains, not Docker or Linux namespace compatibility.

Verification

Use the narrowest test that proves the compatibility path you changed.

For broad release confidence, run:

make test

Related Documents

• GETTING_STARTED.md: first boot.
• USER_GUIDE.md: using the running guest.
• COMMAND_REFERENCE.md: command syntax and examples.
• CONFIGURATION_REFERENCE.md: host and QEMU knobs.
• DEVELOPER_GUIDE.md: writing and porting applications.
• API_REFERENCE.md: syscall and bridge ABI.
• SECURITY_GUIDE.md: capability and handle model.
• PACKAGE_MANAGEMENT.md: package ecosystem state.

Edit this page on GitHub