# AsterOS: an operator's overview AsterOS is a small experimental operating system for QEMU, with a graphical desktop, a Unix-like command shell, a two-pane file manager and an optional persistent archive. It is intended as a research toy and a place to explore OS behaviour. Its desktop and commands are usable today, while its application and administration facilities remain deliberately small. This overview describes the documented running system after the Explorer milestone. The proposed change to daily WORMFS numbering is still a plan; the current implementation continues numbering across days. AsterOS runs its own 32-bit x86 kernel. It does not run Linux, a browser or a JavaScript engine inside the guest. The interface combines familiar title bars and desktop colour schemes with Plan 9 Rio-inspired window operations and case-sensitive Unix-style paths. It does not claim POSIX compatibility. | Area | Available today | | --- | --- | | Desktop | Fixed 1920 × 1080 display, mouse input, overlapping windows and shared themes | | Applications | Terminal windows and graphical Explorer windows | | Windows | Up to eight live windows in total, including hidden ones | | Working storage | A shared 512 MiB RAM filesystem, reset on reboot | | Persistent storage | Optional WORMFS archive image with immutable captures | | File recovery | Browse archived trees and copy individual regular files into RAMFS using Explorer | | Execution | Built-in commands and applications, with no independent background jobs | | Networking | Not implemented | From the project directory on the host, start the system with: ```sh make run ACCEL=kvm ``` Use `make run` if KVM is unavailable. KVM can make desktop interaction much smoother; the default is QEMU's software CPU emulation. The launcher configures 1 GiB of guest RAM and QEMU Standard VGA. Host dependencies and fullscreen options are documented in the [README](README.md#launch). The guest starts with one focused terminal in `/ram`. Click a window to focus and raise it. QEMU normally releases captured keyboard/mouse input with Ctrl+Alt+G. The guest commands `shutdown` and `reboot` exit the VM and restart the guest respectively. Reboot discards the working RAM files and recreates the initial desktop; an attached archive retains its committed captures. Window management is mostly mouse-driven. Press and hold the right mouse button over the desktop or window content, move onto a menu entry, and release to choose it. Some entries then ask you to select a window or sweep a rectangle. | Operation | How to use it | | --- | --- | | Focus | Left-click a window; clicking empty desktop clears keyboard focus | | Move | Left-drag its title bar; right-dragging a border is another shortcut | | Resize | Left-drag any edge or corner; the pointer indicates the resize direction | | New terminal | Choose New, then right-drag a rectangle for the new window | | Menu Move / Resize | Choose the operation, target a window, then position its outline or draw its new rectangle | | Hide | Choose Hide and target a window; its state remains available | | Restore | Choose the hidden window's entry from the right-button menu | | Close | Choose Delete and target a window; this closes the window/session and leaves shared files intact | | Cancel a gesture | Press Escape or the middle mouse button, then release held buttons | New terminals inherit the focused client's directory; for Explorer, that means its active pane. Without focus, they start in `/ram`. Each terminal has its own working directory, editable command, insertion cursor and 16-entry history. Hiding a terminal retains that state. Terminal windows can be resized down to 576 × 320 pixels; Explorer's minimum is 960 × 480. There is no taskbar, desktop icon launcher or set of minimise/maximise/close buttons in the title bars. Several windows can remain open and usable together, but they are not separate scheduled processes. AsterOS handles input and application work through one shared dispatcher. A long copy, archive operation, large file printout or other lengthy command can hold up all windows. Input buffering is limited, so typing ahead during a long operation can lose input. KVM improves execution speed; it does not introduce background execution. The filesystem namespace separates working files from archives and controls: | Path | Purpose | Persistence and access | | --- | --- | --- | | `/` | Virtual root listing the mountpoints | Read-only | | `/ram` | Ordinary working files and directories | Writable; lost when the guest restarts | | `/worm` | Date-grouped committed captures | Read-only browsing; persistent with an attached archive image | | `/dev` | Static control-device namespace | Contains `/dev/worm`; these are not ordinary stored files | There is no conventional writable persistent system disk. Saving a file into `/ram` does not automatically send it to WORMFS. Attaching an archive also does not restore its contents into the working filesystem at boot. RAMFS has two separate capacity limits: 512 MiB of shared file data and 64 total entries, counting files, directories and its own root. A directory uses an entry even when empty. File data is allocated in 4 KiB blocks, so a small file can occupy more allocated space than its byte length. `mem` reports usage and limits. The archive's directory view does not use those 64 RAMFS entries. Names are case-sensitive printable ASCII, with a 31-byte component-name limit. Complete paths are limited to 4096 bytes. `/ram/Documents` and `/ram/documents` are different paths. Absolute paths start at `/`; relative paths start at the current directory. `.` and `..` work across mount boundaries. Bare `cd` returns to `/ram`. Directories being used by terminals or Explorer panes, including hidden windows, are protected against removal; nonempty directories cannot be deleted. The shell provides a small set of built-in commands rather than a full Unix utilities environment: | Purpose | Commands | | --- | --- | | Discover commands and inspect the session | `help`, `version`, `history`, `clear` | | Navigate and inspect files | `pwd`, `cd`, `ls`, `cat`, `stat` | | Create or change working files | `mkdir`, `touch`, `write`, `append`, `fill`, `rm` | | Inspect RAM usage | `mem` | | Open the file manager | `explorer` | | Archive and inspect archive status | `worm snapshot`, `worm put PATH`, `worm status` | | Change desktop colours | `theme`, `theme list`, `theme set NAME`, `theme load PATH`, `theme reset` | | Control the guest | `reboot`, `shutdown` | For example: ```text mkdir /ram/Documents/demo cd /ram/Documents/demo write notes.txt "First version of my notes" append notes.txt "Another line" cat notes.txt stat notes.txt ``` `write` replaces text and adds a newline; `append` adds text followed by a newline. `touch` creates an empty file without replacing existing contents. `fill` creates a specified number of repeated bytes. There is no text editor application yet. Binary file copying is available through Explorer; a general shell `cp` or `mv` command is not included. The shell does not provide pipes, redirection, scripts or external executable loading. Quote paths and text containing spaces with single or double quotes; backslash escape sequences are not implemented. Command lines are limited to 16384 bytes and 16 arguments. Keyboard input supports printable ASCII with a UK/Irish layout, Shift and Caps Lock. There is no clipboard or Ctrl-shortcut handling in the current shell, and no interactive output scrollback control. Arrow keys, Home/End, Backspace and Delete edit commands; Up/Down recall history. Tab completes at the cursor, including in the middle of a path. A unique match completes, multiple matches expand their common prefix, and another Tab lists matches in pages. Further Tabs advance pages; Escape returns to editing. Completion covers mounts, RAM files and archive trees. Page Up/Down reads long prompt/draft text. Terminal F2 opens the full title in a reader; middle-clicking a title does the same without moving its window. Hidden-menu entries also support full-label reading and scrolling. Explorer opens from the shell: ```text explorer explorer /ram/Documents explorer /ram/Documents /ram explorer /worm /ram/Documents ``` With no paths, both panes inherit the terminal's directory. One path opens it in both panes; two paths set them independently. Each pane retains its own location, selection and scrolling. Tab changes the active pane. Click a row to select it, then click the selected row again to open it; Enter also opens it. Opening a regular file displays information rather than launching an editor. Arrows, Home/End, Page Up/Down and the scrollbars navigate the listing; Backspace goes to the parent directory. | Explorer key | Action | | --- | --- | | F2 | Edit the active path; Enter validates it and Escape cancels | | F3 | Show file information and the full path | | F4 | Rename a file or an empty directory | | F5 | Copy a regular file to the opposite RAMFS pane | | F6 | Move a RAMFS file to the opposite RAMFS pane | | F7 | Create a directory | | F8 | Confirm deletion of a file or empty directory | | F9 | Open a terminal in the active pane's directory | | F10 | Close Explorer | The same actions have clickable text buttons. Explorer browses `/`, `/ram`, `/dev` and WORMFS captures. It can copy regular archived files into RAMFS; archive contents remain immutable. Device entries provide information only. There is no recursive directory copy/move, multi-selection, drag-and-drop or recycle bin. Copy, move and rename refuse existing destination names. Explorer and the terminals share live files. A filesystem change refreshes Explorer's listings on the next GUI update and may clear its selection. Pending dialogs retain their displayed paths and check them again when you confirm. If another terminal deleted the source, the operation reports a missing-file error. If it deleted and recreated an eligible file at the same path, the operation acts on the replacement. This applies to Delete as well as Copy: the dialog does not preserve an original file's identity or contents. A failed copy publishes no partial destination. WORMFS provides explicit persistence through an optional separate raw disk image. Create a fresh image on the host, then attach it at launch: ```sh python3 -B tools/worm_image.py format /path/to/new-archive.img --size 64MiB make run ACCEL=kvm WORM_DISK=/path/to/new-archive.img ``` The formatter refuses an existing output path. Supported image capacities are 2 MiB through 8 GiB. Without an image, the desktop and RAMFS still work; `/worm` remains an empty reserved mountpoint and `/dev/worm` reports unavailable. Inside the guest, save one file or the complete working tree: ```text write /ram/Documents/notes.txt "Version to keep" worm put /ram/Documents/notes.txt worm snapshot worm status ``` `put` saves a regular RAMFS file together with its ancestor directory layout. `snapshot` saves the whole RAMFS, including empty directories. Neither captures terminal drafts, histories or window positions. Both commands print the committed capture's path. Use that printed path to browse with `ls`, `cd`, `cat` and `stat`, or open it in Explorer with `/ram` in the opposite pane to copy files back. The captured tree omits the `/ram` prefix: a saved `/ram/Documents/notes.txt` appears as `Documents/notes.txt` beneath the capture root. The equivalent control interface is available through a device node: ```text write /dev/worm snapshot write /dev/worm "put /ram/Documents/notes.txt" cat /dev/worm ``` An archive submission waits for its final disk flush before reporting success. This assumes the virtual disk and host storage honour flush requests. Dates are UTC; an invalid clock uses `undated`. In the current implementation, paths use `/worm/DATE/snapshots/NNNNNNNNNN`, with ten-digit numbers that increase across the entire archive, including across date changes. A durably reserved failed attempt consumes its number, so gaps are expected; a rejected command that never started an attempt consumes none. The new [daily-numbering plan](WORMFS_PLAN.md#daily-numbering-and-capture-identity) changes that to seven-digit numbers starting at 0000001 for each date, while continuing to skip failed reservations within that date. It is not implemented yet. The planned format replacement keeps version 1 and uses fresh images, with no migration or backward-compatibility support. A version number is not a long-term archive compatibility promise in this research OS. WORMFS stores immutable content and shares unchanged data between captures. It is append-only: guest commands cannot edit or delete archived captures, and consumed space is not reclaimed. There is no separate sealing step. Each reboot's first subsequent write reserves a fresh 1 MiB segment; unused space at the end of older reserved segments remains consumed. Consequently, space use depends on reboot/write patterns as well as file contents. Current limits are 65,536 indexed content objects and 4,096 committed captures. A write, flush or verification fault stops archive writing for that boot; recovery requires reboot and a new scan. Independently validated older captures can remain readable. If the final commit flush fails, the outcome can be uncertain: recovery may find that capture completed under its original number. Hashes detect damaged data; they do not reconstruct missing bytes. WORMFS's write-once rules are enforced by AsterOS software, not by tamper-proof host storage. There is no whole-snapshot restore or automatic boot recovery of RAMFS. With the guest stopped, the host can inspect an archive: ```sh python3 -B tools/worm_image.py inspect /path/to/new-archive.img ``` The inspector is read-only; build the project first so its native inspector is available. This command inspects archive integrity and metadata rather than loading files into RAMFS. One theme applies across the desktop, terminals and Explorer. Available presets are `asteros`, `windows98`, `windowsxp`, `plan9`, `classicx11`, `unixworkstation`, and the `plan9-alt`, `classicx11-alt` and `unixworkstation-alt` variants. Historical names describe colour palettes; they do not replace the desktop's window-management behaviour. ```text theme list theme set windowsxp theme set plan9-alt theme colours theme reset ``` Windows 98 and XP use black terminal backgrounds with white text. The `-alt` variants apply the same terminal treatment to their corresponding light-terminal presets. Explorer has separate theme fields for its lists, paths, selections and dialogs. Custom theme files use readable names such as `teal` or `soft white`; `theme load PATH` accepts a file from RAMFS or an archive. Invalid files leave the current theme unchanged. Theme changes and RAMFS theme files are volatile; reboot restores the default theme. `/dev/theme` is not implemented. For administration, this is a trusted single-user environment. There are no user accounts, per-file permissions, separate application protection domains, network services, package manager or loadable external applications. The shell, desktop and file manager share kernel privileges. A serious software error can halt the entire guest; reboot is the recovery path, with the usual loss of unarchived RAM files. Supported operation targets QEMU rather than physical hardware. Graphics are drawn in software, with no GPU-accelerated 3D stack. The documented future work is separate from the running feature set: | Feature | Status | | --- | --- | | Daily WORMFS numbers with unchanged format version | Planned amendment; fresh-image requirement | | Saved window layouts and working directories, including Explorer panes | Feature idea; no workspace save/restore implementation | | `/dev/theme` | Proposed control device; current theme commands already work | | Windows-style `C:\` presentation for `/ram/c` in Explorer | Future presentation feature; canonical Unix paths remain current behaviour | | Whole-capture restore and optional `rootfs.tar` loading | Future work; no automatic root filesystem import | The [README](README.md) is the main command and launch reference. The [Explorer implementation record](EXPLORER_IMPLEMENTATION.md) and [WORMFS implementation record](WORMFS_IMPLEMENTATION.md) describe documented native/headless validation and its limits. [Feature ideas](FEATURE_LIST.md) and the [WORMFS plan](WORMFS_PLAN.md) record future behaviour. Older milestone plans retain historical limits and scopes; this overview follows the current README and later implementation records when those differ.