SwiftOS Support Guide

This guide describes how to collect evidence, classify a problem, and report a SwiftOS issue in a way that another maintainer or operator can reproduce. It is the support companion to TROUBLESHOOTING.md and OBSERVABILITY_GUIDE.md: use Troubleshooting to diagnose a known failure, Observability to understand available signals, and this guide when you need to hand off a clear report.

SwiftOS is early product software. A useful support report should distinguish current design limits from regressions, include the exact repository revision, and attach the serial or test output that proves the failure. For choosing and reading focused gates, see TESTING_GUIDE.md.

For common product and support questions before opening a report, see FAQ.md.

Support Scope

Current supported support targets:

Current non-support targets:

• Linux binary compatibility.
• Docker or OCI compatibility.
• Persistent writable root filesystem behavior.
• Production TLS trust decisions from tlsget.
• General x86-64, Raspberry Pi, or PC hardware boot.
• Target-side package remove, upgrade, rollback, and version-constraint solving transactions.
• Public hosted package channels outside the checked local fixtures.

For the full compatibility matrix, see COMPATIBILITY_GUIDE.md.

First Response Checklist

Run these commands before opening a report unless the failure prevents them:

git status --short --branch
git log -1 --oneline
make tools-check
make build

Then run the narrowest acceptance test that proves the failing path:

If the narrow test passes, record that too. It narrows the problem and prevents the next person from retesting the wrong layer.

Choose A Support Bundle

Pick the smallest bundle that proves the failing path. Every bundle should include git-status.txt, git-head.txt, tools-check.txt, the exact command that failed, and the first failing line.

Example support bundle for a networking issue:

mkdir -p support
git status --short --branch >support/git-status.txt
git log -1 --oneline >support/git-head.txt
make tools-check >support/tools-check.txt 2>&1
./tests/httpd_test.sh >support/httpd-test.txt 2>&1

If the issue was reproduced manually, add the host client output:

curl -v http://127.0.0.1:8080/ >support/curl-httpd.txt 2>&1

Minimum Report Template

Use this template for bugs, regressions, and failed validation runs.

Title:
  Short symptom, command, and area.

Revision:
  git log -1 --oneline
  git status --short --branch

Host tools:
  make tools-check

What I ran:
  exact make command, test script, or QEMU command

Expected:
  what the guide or acceptance test says should happen

Actual:
  exact failure line, exit code, panic line, timeout, or wrong output

Evidence attached:
  serial log or test output
  relevant host command output
  guest command transcript, if manual

Reproducibility:
  always / intermittent / once
  number of reruns

Local changes:
  unrelated dirty files, config overrides, environment variables, or patches

Do not summarize away the first failing line. Include the exact line and the nearby context.

Collect A Support Bundle

For a general build or boot issue, collect:

mkdir -p support
git status --short --branch >support/git-status.txt
git log -1 --oneline >support/git-head.txt
make tools-check >support/tools-check.txt 2>&1
make build >support/build.txt 2>&1
./tests/boot_test.sh >support/boot-test.txt 2>&1

If the failing path is networked, collect the specific network test too:

./tests/httpd_test.sh >support/httpd-test.txt 2>&1
./tests/llm_serve_test.sh >support/llm-serve-test.txt 2>&1

If the failing path is UEFI:

make disk base-image >support/disk-build.txt 2>&1
UEFI_BOOT=disk ./tests/uefi_boot_test.sh >support/uefi-boot-test.txt 2>&1

If the failure is intermittent, run the same narrow test three times and record all outputs separately:

for n in 1 2 3; do
  ./tests/boot_test.sh >"support/boot-test-$n.txt" 2>&1 || break
done

Do not include generated build directories unless a maintainer asks for a specific artifact. Text logs are the first-line support artifact.

Serial Log Capture

Most product evidence comes from the serial console. For a manual direct boot, capture QEMU output:

make build base-image build/virt.dtb

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 \
  -kernel build/kernel.elf >support/serial.log 2>&1

Exit QEMU serial with Ctrl-A X.

For network services, include the host client output and the serial log:

curl -v http://127.0.0.1:8080/ >support/curl-httpd.txt 2>&1
curl -v http://127.0.0.1:8080/health >support/curl-llmd-health.txt 2>&1

Important Log Markers

These markers help locate the failing subsystem.

When reporting a panic, include the first panic line and at least 80 lines before and after it if available.

Severity Levels

Use the lowest severity that still captures the user impact. If in doubt, pick S2 and include the evidence.

Known Design Limits To Mention

Avoid filing these as regressions unless the behavior changed from a documented acceptance path.

Area-Specific Evidence

Build And Toolchain

Attach:

make tools-check
make build

If the failure mentions newlib or busybox:

test -f sysroot/aarch64-elf/include/stdio.h
test -f build/busybox.elf

Boot And Firmware

Attach:

./tests/boot_test.sh
UEFI_BOOT=disk ./tests/uefi_boot_test.sh

For firmware issues, include:

make -n disk-run

Filesystem

Attach:

./tests/vfs_disk_test.sh
./tests/disk_exec_test.sh
./tests/swift_fileops_test.sh

Mention whether the path is in the read-only base image, /tmp, or a package overlay.

Accounts And Capabilities

Attach:

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

From an interactive guest, include:

id

Networking

Attach the exact QEMU network command and the narrow test:

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

If host ports were overridden, record the environment variable:

HTTPD_HOST_PORT=18080 ./tests/httpd_test.sh
LLMD_HOST_PORT=18081 ./tests/llm_serve_test.sh

AI Hosting

Attach:

make model
./tests/llm_run_test.sh
./tests/llm_serve_test.sh

For /bin/llmd, include:

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

Package Overlays And Stores

Attach:

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
make c5-device-authority-test

Mention whether the guest saw /usr/bin/pkghello, whether pkg list reported pkghello-1.0.0_1, and whether the repository flow printed pkg: catalog updated. For the static-host ports fixture, mention whether pkg install lua and pkg install zlib succeeded, whether Lua printed 42, whether the minigzip round trip printed static-host-ok, and whether the hosted-URL path used an IP literal or DNS hostname.

SMP Readiness

Attach:

make s1-test
SMP_CPUS=4 ./tests/smp_boot_test.sh

If the issue is CPU-count-specific, record the SMP_CPUS value and whether a custom SMP_DTB was used.

Redaction And Privacy

Current seeded credentials are public test credentials and may appear in logs:

Before sharing logs from a custom image, redact:

• private package repository URLs;
• non-public model prompts or generated output;
• locally added passwords or keys;
• host paths that should not be disclosed;
• future package signing keys or tokens.

Do not redact the actual failure marker, command line, or revision. Those are usually required for diagnosis.

Support Handoff Checklist

Before handing the issue to another person, confirm:

1. The report names the exact command or workflow.
2. The current git log -1 --oneline is included.
3. Dirty local files are listed with git status --short --branch.
4. make tools-check output is included for build or QEMU issues.
5. A narrow acceptance test was run, or the report explains why it could not be run.
6. The serial log or test output includes the first failing line.
7. The report says whether the failure repeats.
8. Known design limits were checked against COMPATIBILITY_GUIDE.md.

Related Documents

• TROUBLESHOOTING.md: common failures and fixes.
• OPERATIONS_GUIDE.md: normal operating workflows.
• COMMAND_REFERENCE.md: command syntax and acceptance coverage.
• CONFIGURATION_REFERENCE.md: build variables, QEMU profiles, and test knobs.
• COMPATIBILITY_GUIDE.md: supported and unsupported compatibility paths.
• LOGGING.md: logging reference, current limits, and roadmap.

Edit this page on GitHub