universalisos/docs/T8-3.1_FLEET_TOOLING.md

T8-3.1: uos-fork / uos-manage Fleet Tooling

Track: T8-3.1
Status: IN PROGRESS
Date: 2026-07-12

---

Overview

uos-fork and uos-manage are fleet management tools for UniversalisOS. They enable:

• uos-fork: Create new guest instances from a template
• uos-manage: Monitor, control, and audit running guests

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Host (Linux/macOS)                                         │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  uos-fork                                           │   │
│  │  - Create guest from template                       │   │
│  │  - Configure Stage-2 MM                             │   │
│  │  - Assign partition ID                              │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  uos-manage                                         │   │
│  │  - List running guests                              │   │
│  │  - Monitor resource usage                           │   │
│  │  - Run isolation audits                             │   │
│  │  - Start/stop/restart guests                        │   │
│  └─────────────────────────────────────────────────────┘   │
│                          │                                  │
│                          ▼                                  │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  UniversalisOS Hypervisor                           │   │
│  │  - Guest 0: musl personality                        │   │
│  │  - Guest 1: Android (AOSP)                          │   │
│  │  - Guest 2: Android (LineageOS)                     │   │
│  │  - Guest 3: Android (GrapheneOS)                    │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

---

uos-fork

Purpose

Create a new guest instance from a template. Similar to fork() but for guests.

Usage

# Fork a new Android guest from template
uos-fork --template android-aosp --name my-android-1

# Fork with custom memory size
uos-fork --template android-aosp --name my-android-2 --memory 2G

# Fork with custom partition ID
uos-fork --template android-aosp --name my-android-3 --partition 5

Options

Option	Description	Default
--template	Guest template (android-aosp, android-lineage, android-graphene, musl)	android-aosp
--name	Guest name	auto-generated
--memory	Guest memory size	1G
--partition	Partition ID	auto-assigned
--kernel	Custom kernel path	template default
--ramdisk	Custom ramdisk path	template default
--dtb	Custom DTB path	template default

Implementation

/* uos-fork main entry */
int uos_fork(const char* template, const char* name, uint64_t memory_size);

/* Create guest from template */
int uos_fork_create_guest(const uos_guest_template_t* tmpl, uos_guest_config_t* config);

/* Assign partition ID */
uint32_t uos_fork_assign_partition(void);

/* Configure Stage-2 MM */
int uos_fork_configure_mm(uint32_t guest_id, uint64_t memory_size);

---

uos-manage

Purpose

Monitor, control, and audit running guests.

Usage

# List all guests
uos-manage list

# Show guest details
uos-manage show my-android-1

# Monitor resource usage
uos-manage monitor my-android-1

# Run isolation audit
uos-manage audit my-android-1

# Start/stop/restart guest
uos-manage start my-android-1
uos-manage stop my-android-1
uos-manage restart my-android-1

# Show fleet status
uos-manage status

Commands

Command	Description
list	List all guests
show <name>	Show guest details
monitor <name>	Monitor resource usage
audit <name>	Run isolation audit
start <name>	Start guest
stop <name>	Stop guest
restart <name>	Restart guest
status	Show fleet status

Implementation

/* uos-manage main entry */
int uos_manage(const char* command, const char* guest_name);

/* List all guests */
int uos_manage_list(uos_guest_info_t* guests, uint32_t* count);

/* Show guest details */
int uos_manage_show(const char* name, uos_guest_info_t* info);

/* Monitor resource usage */
int uos_manage_monitor(const char* name, uos_guest_stats_t* stats);

/* Run isolation audit */
int uos_manage_audit(const char* name, uos_isolation_result_t* result);

/* Start guest */
int uos_manage_start(const char* name);

/* Stop guest */
int uos_manage_stop(const char* name);

/* Restart guest */
int uos_manage_restart(const char* name);

---

Guest Templates

android-aosp

name: android-aosp
type: android
kernel: guests/android-aosp/kernel
ramdisk: guests/android-aosp/ramdisk
dtb: guests/android-aosp/dtb
memory: 1G
partition: auto
hardened_malloc: true

android-lineage

name: android-lineage
type: android
kernel: guests/android-lineage/kernel
ramdisk: guests/android-lineage/ramdisk
dtb: guests/android-lineage/dtb
memory: 1G
partition: auto
hardened_malloc: true

android-graphene

name: android-graphene
type: android
kernel: guests/android-graphene/kernel
ramdisk: guests/android-graphene/ramdisk
dtb: guests/android-graphene/dtb
memory: 1G
partition: auto
hardened_malloc: true

musl

name: musl
type: personality
kernel: guests/musl/kernel
ramdisk: guests/musl/ramdisk
dtb: guests/musl/dtb
memory: 512M
partition: 0
hardened_malloc: true

---

Fleet Status

┌─────────────────────────────────────────────────────────────┐
│  UniversalisOS Fleet Status                                 │
├─────────────────────────────────────────────────────────────┤
│  ID  Name            Type      Memory  Status   Isolation   │
├─────────────────────────────────────────────────────────────┤
│  0   musl            personality 512M   RUNNING  PASS       │
│  1   android-aosp    android    1G      RUNNING  PASS       │
│  2   android-lineage android    1G      RUNNING  PASS       │
│  3   android-graphene android   1G      STOPPED  -          │
├─────────────────────────────────────────────────────────────┤
│  Total: 4 guests, 3 running, 1 stopped                     │
│  Memory: 3.5G / 8G used                                     │
│  Isolation: 3/3 PASS                                        │
└─────────────────────────────────────────────────────────────┘

---

Implementation Files

File	Purpose
tools/uos-fork/main.c	uos-fork CLI
tools/uos-manage/main.c	uos-manage CLI
tools/uos-fleet/fleet.h	Fleet management API
tools/uos-fleet/fleet.c	Fleet management implementation
tools/uos-fleet/templates.h	Guest templates
tools/uos-fleet/templates.c	Template implementation

---

Verification

• uos-fork creates guests from templates
• uos-manage lists all guests
• uos-manage shows guest details
• uos-manage runs isolation audits
• Fleet status shows correct information

---

References

• universalisos/docs/T8-2.2_ANDROID_INHERITANCE.md — Android guests
• universalisos/docs/T8-2.3_ISOLATION_AUDIT.md — Isolation audit
• universalisos/kernel/src/core/abi/uos_android_guest_config.h — Guest config