# 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

```bash
# 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

```c
/* 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

```bash
# 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

```c
/* 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

```yaml
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

```yaml
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

```yaml
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

```yaml
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