# JefeOS Builder's Manual

For humans and coding agents building, moving, and running software on JefeOS.

## Start here

JefeOS is an early-1.x hobby operating system for x86_64 with two separately released kernels:

- **JefeOS 1.1.2 (C++)** is the primary target in this manual.
- **JefeRust 1.0.0** is a separate Rust kernel and VM. Do not assume post-1.0 C++ features exist there.

Choose a program path before you build:

| Path | Choose it when | Build/run contract |
|---|---|---|
| **Native JefeOS** | You want the first-class and smallest interface | Build an x86_64 ELF for the native `INT 0x80` ABI; run with `exec`. Start with [BUILD-FOR-JEFEOS.md](downloads/BUILD-FOR-JEFEOS.md) and the examples disk. |
| **Linux ABI (JSL-1)** | You have an x86_64 Linux program that fits the implemented compatibility surface | Prefer static musl first; run with `exec_linux`. This is syscall translation on the JefeOS kernel, not a Linux kernel or container runtime. |

**Safety boundary:** JefeOS has no installer and physical hardware is not a supported target. Boot it in a disposable VM. The ISO is the boot medium; any attached writable disk can be modified. Clone or back up a VHD before attaching it, never replace or edit a VHD while its VM is running, and do not place irreplaceable data on a disk JefeOS can write. Do **not** attach the JefeOS NTFS examples VHD as JefeRust's first disk; JefeRust may format an unrecognized first disk.

Primary downloads:

- [JefeOS 1.1.2 ISO](downloads/jefeos-1.1.2.iso) · [SHA-256](downloads/jefeos-1.1.2.iso.sha256)
- [Writable native examples VHD](downloads/jefeos-examples.vhd.zip) · [SHA-256](downloads/jefeos-examples.vhd.zip.sha256)
- [Native build guide](downloads/BUILD-FOR-JEFEOS.md)
- [JefeRust 1.0.0 ISO](downloads/jeferust-1.0.0.iso) · [SHA-256](downloads/jeferust-1.0.0.iso.sha256)

Baseline VM constraints: x86_64, 512 MiB RAM, BIOS/legacy boot, IDE storage, and E1000-compatible networking. Hyper-V requires a Generation 1 VM and Legacy Network Adapter. Native virtio block/network drivers are not available.

**Release versus development:** download links describe the immutable 1.1.2 C++ release and 1.0.0 Rust release. Material labeled **development** describes the moving repository default branch and must not be attributed to the downloadable ISO without exact-commit release evidence.

---

## Boot and VM recipes

### QEMU

```bash
qemu-system-x86_64 -cdrom jefeos-1.1.2.iso -m 512M -serial stdio \
  -netdev user,id=net0,hostfwd=tcp:127.0.0.1:2222-:22 -device e1000,netdev=net0
```

To attach a **clone** of the examples disk:

```bash
qemu-system-x86_64 -cdrom jefeos-1.1.2.iso -m 512M -serial stdio \
  -netdev user,id=net0,hostfwd=tcp:127.0.0.1:2222-:22 -device e1000,netdev=net0 \
  -drive file=jefeos-examples.vhd,format=raw,if=ide
```

### VirtualBox

Create an **Other/Unknown (64-bit)** VM with 512 MiB RAM and no primary hard disk. Attach the ISO as optical media. For networking choose NAT and **Intel PRO/1000 MT Desktop (82540EM)**. Attach only a disposable or cloned VHD.

### Hyper-V

Create a **Generation 1** VM with 512 MiB RAM and no VHD, attach the ISO, remove the synthetic NIC, and add a **Legacy Network Adapter** on the Default Switch. A minimal PowerShell setup:

```powershell
# Run from an elevated PowerShell prompt.
$vm = "JefeOS"
New-VM -Name $vm -Generation 1 -MemoryStartupBytes 512MB -SwitchName "Default Switch" -NoVHD
Set-VMDvdDrive -VMName $vm -Path (Resolve-Path .\jefeos-1.1.2.iso)
Get-VMNetworkAdapter -VMName $vm | Remove-VMNetworkAdapter
Add-VMNetworkAdapter -VMName $vm -IsLegacy $true -SwitchName "Default Switch"
Set-VMBios -VMName $vm -StartupOrder @("CD","IDE","LegacyNetworkAdapter","Floppy")
Start-VM -Name $vm
```

### OpenStack

JefeOS 1.1.2 has been validated as a Nova-managed guest using a Glance ISO and an ISO 9660 `config-2` config drive. Keep image properties conservative: BIOS boot, IDE storage, and E1000 networking. DHCP network data, hostname, and authorized SSH keys are consumed; arbitrary static-network data is not.

After boot, use `help` to explore. Graphics exist only as an experimental kernel demo; they are not the recommended builder path.

---

## Connect and automate

The **1.1.2 release lab image** generates an ephemeral SSH identity and exposes demo credentials (`jefe` / `jefe`). Keep it on loopback/NAT only; never bridge or expose that demo SSH service to an untrusted network. The QEMU recipe forwards host loopback port 2222 to the guest.

On the first interactive connection, verify the presented host fingerprint through the trusted local VM console/boot evidence, then pin that exact fingerprint for automation:

```powershell
plink -P 2222 -ssh -batch -pw jefe -hostkey "SHA256:<verified-fingerprint>" jefe@127.0.0.1 "help"
```

`ssh-keyscan` can discover a key but does **not** prove that key is trustworthy. The repository's `restore-network.ps1` is maintainer infrastructure, not the public trust bootstrap.

The **development tree** instead expects provisioned persistent trusted identity and fails closed by disabling password authentication if trusted identity is unavailable. Treat each remote command as a one-shot automation transaction. Send one shell command at a time and parse its text output.

For file transfer, use SFTP/SCP only after confirming a writable NTFS volume is mounted. Upload to that mounted volume, not to an assumed path on the read-only boot ISO. Never mutate the host-side VHD while the guest owns it.

JefeRust's COM1 named pipe is output-only; use it for boot evidence and SSH for commands.

---

## Shell

The built-in shell supports pipes and redirection:

```text
ps | grep shell
echo hello > /tmp/hello.txt
cat /tmp/hello.txt
```

It does **not** implement `&&`, `||`, or `;` command chaining, and there is no general Ctrl+C foreground job-control path. Run automation commands separately.

Useful groups:

- Files: `ls`, `cd`, `pwd`, `mkdir`, `rm`, `cp`, `mv`, `ln`, `touch`, `cat`, `stat`, `chmod`, `chown`, `df`, `du`
- Text: `grep`, `head`, `tail`, `wc`, `cut`, `sort`, `uniq`, `tee`, `tr`, `hexdump`
- Process/system: `ps`, `tasks`, `jobs`, `kill`, `id`, `whoami`, `sleep`, `time`, `sysinfo`, `uptime`, `free`, `cpus`
- Network: `ping`, `dns`, `dhcp`, `ifconfig`, `netstat`, `curl`, `ssh`, `sftp`, `ntp`, `nts`, `wsconnect`
- Programs: `exec <native-elf>`, `exec_linux <linux-elf>`, `exec_linux -bg <linux-elf> [args]`, `lcompat`

Use detached mode for long-lived Linux services:

```text
exec_linux -bg /programs/server
jobs
```

---

## Filesystems

Paths are root-anchored and use forward slashes.

| Surface | State |
|---|---|
| `/run` | Volatile tmpfs; cleared at reboot |
| `/tmp` | Persistent only when backed by the mounted NTFS data disk; it is not tmpfs |
| NTFS data volume | Read/write, including non-resident growth and directory-index growth |
| FAT32 | Read-only |

NTFS name lookup follows JefeOS's case-sensitive POSIX behavior even though on-disk collation remains compatible with Windows tooling. AHCI transfer code exists, but ATA PIO remains the canonical mounted block backend.

JefeFS belongs to JefeRust, not the C++ filesystem surface described above. Do not attach the JefeOS NTFS examples disk as JefeRust's first disk. Treat filesystem work as crash-sensitive: keep a pristine VHD, operate on a clone, shut the VM down before host-side mounting, and run host filesystem checks against disposable images.

---

## Native programs

Native x86_64 ELFs use the JefeOS `INT 0x80` syscall ABI and are the preferred path for new, tightly scoped tools.

1. Read [BUILD-FOR-JEFEOS.md](downloads/BUILD-FOR-JEFEOS.md).
2. Start from a program in the writable [examples disk](downloads/jefeos-examples.vhd.zip) or a source example in `userspace/programs`.
3. Build against the native ABI and link as described in the build guide.
4. Copy the ELF to a writable NTFS volume.
5. Run it with:

```text
exec /programs/yourprog
```

The native process model centers on asynchronous `sys_spawn`. A fork implementation also exists, but it eagerly copies the full present address space, has no copy-on-write, and fails closed when SMP is enabled.

The 1.1.2 user/kernel boundary enforces SMAP/uaccess discipline: user buffers must be mapped, invalid access returns `EFAULT` or a documented short copy, and kernel code uses `copy_from_user`/`copy_to_user` rather than directly dereferencing user pointers.

Do not invent syscall numbers. The reservation map in `kernel/src/syscall.cpp` is authoritative and moves as interfaces land.

---

## Linux programs and ABI

JSL-1 runs x86_64 Linux ELFs by translating the Linux `SYSCALL` ABI into JefeOS kernel operations. It does not boot a Linux kernel.

- The generated Linux syscall surface contains **160 entries**. Presence in that generated surface is not a promise that every semantic corner matches Linux.
- Tier 1 static musl, Tier 2 static glibc, Tier 3 dynamic linking, and Tier 4 busybox/Alpine-rootfs under `chroot` are green.
- Tier 5 is multi-part and still partial: real OpenRC `sysinit → boot → default` and `apk info` are complete; the remaining release proof is the interactive `getty → /bin/login` console path.
- `fork()` is eager-copy, UP-only, and has no COW. It is usable for current fork/exec paths but can be expensive for large address spaces.

Prefer a static musl binary first:

```text
exec_linux /programs/hello-linux
lcompat
```

For a long-running Linux program:

```text
exec_linux -bg /programs/hello-server --port 8080
```

Unimplemented calls return failure and are reported in diagnostic output. Confirmed gaps include `clone3`, `io_uring`, `aio_*`, `inotify`, and `vmsplice`. `pidfd_open` and `pidfd_send_signal` are routed, while `pidfd_getfd` and `waitid(P_PIDFD)` remain absent. `sendfile`, `splice`, and `tee` are implemented. The surface moves quickly, so inspect the current table before relying on a remembered list.

POSIX coverage is tracked separately from Linux ABI compatibility. The often-quoted ~83% figure is a May estimate and is awaiting a refreshed measurement, so do not use it as a current release headline.

---

## Networking

The C++ kernel includes Ethernet, ARP, IPv4, ICMP, DHCP, DNS, UDP, TCP client/server, IPv6 link-local/NDP, NTP/NTS, TLS 1.3, HTTPS, SSH client/server, SFTP, and WebSocket-over-TLS support. E1000 is the normal QEMU/VirtualBox NIC; Hyper-V uses its emulated Legacy adapter.

```text
ifconfig
ping 8.8.8.8
dns example.com
curl https://example.com/
netstat
```

TLS trust differs by kernel:

- **JefeOS C++:** hostname validation, supported-invalid signatures, and Finished verification fail closed, but `strict_chain_verify` and `strict_sig_verify` are **off by default**. Do not treat a default connection as strict public-PKI validation or send sensitive credentials based on that validation.
- **JefeRust:** TLS is strict by default and requires the chain to terminate at a pinned trust anchor, including CertificateVerify processing.

The kernel HTTP server supports GET/HEAD, serves its jailed static surface, and exposes `GET /api/status` for a small runtime snapshot. Most detailed operational state remains text from shell commands over SSH.

---

## Worked example: static Linux hello

This path is deliberately small and reproducible.

On a Linux build host:

```c
// hello.c
#include <unistd.h>
int main(void) {
    static const char msg[] = "hello from JefeOS via JSL-1\n";
    return write(1, msg, sizeof(msg) - 1) < 0;
}
```

```bash
musl-gcc -static -O2 -s -o hello-linux hello.c
file hello-linux
```

Copy `hello-linux` to a writable NTFS-backed path through SFTP, then run:

```text
exec_linux /programs/hello-linux
```

Expected output:

```text
hello from JefeOS via JSL-1
```

If it fails, confirm the file is an x86_64 ELF, verify its path and permissions with `stat`, run `lcompat`, and inspect serial diagnostics for an unimplemented syscall number. Once this basic path works, decide whether the program should remain Linux-compatible or be ported to the smaller native ABI.

---

## Limits and safety notes

- VM-first, no installer, and no supported physical-hardware path.
- Writable disks are real state. Clone first; do not attach the same writable image to two running VMs.
- Single-core is the normal configuration. SMP is not a supported default.
- Shell chaining and general Ctrl+C job control are absent.
- DHCP addresses and the guest SSH host key can change across boots.
- Hyper-V Gen 1 needs a Legacy NIC.
- FAT32 is read-only; AHCI is not the mounted backend; native virtio block/network is absent.
- JSL-1 is broad but incomplete. Tier 5 and several Linux-specific syscall families remain partial or absent.
- `fork()` has no COW and is UP-only.
- The C++ TLS client does not enable strict chain/signature enforcement by default; do not send sensitive credentials based on its default validation.
- Graphics and the in-kernel window manager are experimental. Do not make the graphics command part of a normal quickstart or automation flow.
- No stable public Xylem application API or production-safe cross-vessel workload contract exists.

---

## Capability reference

| Area | Available now | Important boundary |
|---|---|---|
| Boot | Limine, BIOS/legacy VM paths | No installer; modern bare metal unsupported |
| Memory/process | 4-level paging, per-process page tables, preemption, native spawn, eager-copy fork | Normal operation is UP; fork has no COW |
| Native ABI | x86_64 ELF, `INT 0x80`, libc and native examples | Use the build guide; syscall map is source of truth |
| Linux ABI | 160-entry generated surface; Tiers 1–4 green | Tier 5 multi-part; semantics are not full Linux |
| Storage | C++: NTFS read/write, tmpfs, FAT32 read | JefeFS is Rust; clone disks; ATA PIO is C++ mounted backend |
| Network | TCP/IP, DNS/DHCP, SSH/SFTP, HTTPS/TLS, NTP/NTS, WebSockets | C++ strict public-PKI enforcement off by default |
| Automation | SSH exec, SFTP, text status, `/api/status` | One command per shell transaction is safest |
| Graphics | Experimental framebuffer/window-manager code | Not a supported desktop or builder entry point |
| JefeRust | Separate 1.0.0 kernel and ISO | Post-1.0 C++ capabilities require separate parity proof |
| Xylem | 1.1.2: both-kernel membership; C++ Service/reconcile and stateless singleton demo | Development authority install is newer; fencing, Rust parity, migration, state remain open |

---

## Xylem

Xylem is the native-clustering direction, not a prerequisite for ordinary programs.

Landed in the **1.1.2 release**:

- SWIM-style membership and failure detection on both kernels, proven C++↔C++ and C++↔Rust.
- On C++, a first-class `Service`, level-triggered local reconcile loop, restart policy, and crash-loop guard.
- On C++, deterministic-primary `ClusterSingleton` placement with a stateless cross-vessel demo, self-test, and harness.

Added on the **development branch**, not the 1.1.2 ISO:

- On C++, the authority-install half: signed placement grants, durable epoch floors, fail-closed admission, and deadline demotion.

Not landed as a production contract:

- JefeRust service/reconcile/placement parity.
- Authenticated gossip or production CP quorum consensus.
- Resource-side epoch fencing and the complete two-boot/two-vessel recovery proof.
- `desired_replicas > 1`, service addressing, fleet-wide observability, migration, or state transfer.

The current cross-vessel proof starts a compiled-in stateless copy on the surviving C++ vessel. It does not migrate a running process, prove panic recovery for a production workload, or make stateful split-brain safe. Build ordinary software against the native or JSL-1 interfaces above; treat Xylem-facing APIs as internal and evolving.