Updates to the Slicer for Mac info

Signed-off-by: Alex Ellis (OpenFaaS Ltd) <alexellis2@gmail.com>

Author: alexellis

docs/index.md

@@ -49,6 +49,7 @@ Slicer for Mac:
 * On macOS, Slicer for Mac uses [Apple’s Virtualization Framework](https://developer.apple.com/documentation/virtualization).
 * Mac guests can use VirtioFS folder sharing for local paths.
 * Mac guests support Rosetta for x86_64 Linux binaries.
+* Networking uses [VZNATNetworkDeviceAttachment](https://developer.apple.com/documentation/virtualization/vznatnetworkdeviceattachment) for Internet access
 
 * Slicer runs as a daemon and exposes API, CLI, and SDK management for microVM host groups.
 * You define host groups and VM specs in YAML before launching VMs. These cannot be created via API at this point in time. Host groups need to have [non-overlapping networking](/reference/networking/) CIDRs defined.

docs/mac/overview.md

@@ -2,14 +2,19 @@
 
 Slicer for Mac was built from the ground up to run Linux microVMs on Apple Silicon.
 
-It uses the same familiar API and CLI from Slicer for Linux, but instead of using KVM, leans heavily on Apple's native [Virtualization framework](https://developer.apple.com/documentation/virtualization).
+It uses the same familiar API and CLI from Slicer for Linux, using Apple's native [Virtualization framework](https://developer.apple.com/documentation/virtualization) instead of KVM. Only Arm64 hosts and guests are supported, however Rosetta support can be enabled to run Intel/AMD binaries.
 
-Typical use-cases include: disposable sandboxes for agents, running local Kubernetes clusters, or getting access to a real Linux system, instead of making do with POSIX compatibility.
+Typical use-cases include:
 
-Slicer microVMs boot very quickly and have some advanced features like Rosetta for running Intel/AMD binaries, and folder sharing.
+* Real Linux with systemd instead of POSIX compatibility
+* Sandboxes for AI coding agents
+* Local Kubernetes testing and development
+* Exploring software like Hermes Agent or OpenClaw without polluting your Mac
+
+Files can be shared to a microVM via folder sharing using virtiofs, or by `slicer cp` (zero networking copy).
 
 !!! note "macOS versions"
-    Slicer for Mac is available on all Slicer license tiers. We've tested on macOS Sequoia and Tahoe. `slicer-mac` does not need `sudo`. Intel Macs are out of scope for Slicer at this time, but you could install Linux on them, and use Slicer for Linux instead.
+    Slicer for Mac is available on all Slicer license tiers. We've tested on macOS Sequoia and Tahoe. `slicer-mac` does not need `sudo`. Intel Macs are out of scope for Slicer at this time, but you could install Linux on them directly, and use Slicer for Linux instead.
 
 ## How it works
 
@@ -25,9 +30,9 @@ If you need to run x86_64 binaries, see [Enable Rosetta](/mac/rosetta) after the
 The config file for Slicer for Mac is named `slicer-mac.yaml`, it defines two host groups. Host groups launch and manage microVMs. The names are flexible on Slicer for Linux, but Slicer for Mac has two fixed groups instead.
 
 - The `slicer` group - a runs a Linux VM that start-up and stays running. This is your day-to-day Linux environment, similar to WSL on Windows, and is fully persistent.
-- The ``sbox` group aka "sandbox" - is for ephemeral VMs launched on demand through the CLI, API, or by one of your AI coding agents. They are permanently deleted when you shut them down, shut down Slicer for Mac, or delete them via `slicer vm delete NAME`.
+- The `sbox` group aka "sandbox" - is for ephemeral VMs launched on demand through the CLI, API, or by one of your AI coding agents. These VMs are ephemeral by default, but can be made permanent via `slicer vm launch sbox --persistent`
 
-# Architecture (conceptual)
+## Conceptual architecture
 
 ```text
                          +----------------------------+
@@ -55,11 +60,27 @@ The config file for Slicer for Mac is named `slicer-mac.yaml`, it defines two ho
                      +-------------+                  +----------------+
 ```
 
-Docker's socket is port-forwarded to your Mac as a Unix socket, so `docker` commands on the Mac talk directly to the VM. K3s exposes port 6443, so `kubectl` on your Mac can target the cluster running inside `slicer-1`. It feels like you're on Linux.
+A typical flow, might be to install Docker in `slicer-1`, and then port-forward it back to the host using its UNIX socket, so you can run `docker` directly on your machine.
+
+In a similar way, a sandbox such as `sbox-1` may have K3s installed, exposing port 6443. You can access that by copying the KUBECONFIG file back to your local machine and using the sandbox's IP or the `slicer vm forward` command.
+
+## Networking
+
+Slicer for Mac uses Apple's [VZNATNetworkDeviceAttachment](https://developer.apple.com/documentation/virtualization/vznatnetworkdeviceattachment). Guests access the Internet through your host.
+
+* The host can ingress to guests using their IP or `slicer vm forward`
+* Guests can talk to the host to access things like HTTP proxies, or a Docker pull-through cache, etc.
+* Unlike Slicer for Linux, which supports bridged mode networking, guests on Slicer for Mac cannot talk to each other, unless you install an overlay network using something like Wireguard, routing through the host.
+
+Firewall rules can be set up using `pf` to prevent guests from accessing certain IP ranges. You can also write your own intercepting proxy, and have `pf` force all NAT traffic through it to enforce your own filtering.
 
 ## Storage
 
-Unlike Slicer for Linux (which supports [devmapper](/storage/devmapper) and [ZFS](/storage/zfs) CoW backends), the Mac version uses image-backed storage. The OCI image is unpacked once, then cloned instantly using APFS' native Copy-on-Write. Launching a new sandbox doesn't copy the entire disk.
+Slicer for Mac uses image-backed storage for each virtual machine. The OCI image for the root filesystem and Kernel is unpacked once, then cloned instantly using APFS' native Copy-on-Write support. Launching a new sandbox doesn't copy the entire disk, and only deltas are actually allocated to the host's disk.
+
+If the base image is a `10GB` file, when you launch a new VM, no new bytes will be allocated, until the guest starts to change or add new files.
+
+Slicer for Linux supports ZFS and devmapper for Copy-on-Write support.
 
 ## MacBooks and sleep
 

docs/mac/storage.md

@@ -1,12 +1,12 @@
 # Storage on Slicer for Mac
 
-Slicer for Mac stores VM state using a base image flow with copy-on-write clones.
+Slicer for Mac stores VM disks using a raw disk image. Whenever a new VM is launched, a base image file is cloned instantly using the Copy-on-Write (CoW) support of APFS.
 
 You can set storage size per host group with `storage_size` in `slicer-mac.yaml`.
 
 Use `nG` style values (for example `15G`), and set at least `5G` to give enough initial headroom.
 
-Sparse files are used, so disk space is not allocated up front. A declared size of `15G` represents logical size and grows as data is written.
+Sparse files are used, so disk space is not allocated up front. A declared size of `15G` represents logical size and grows as data is written or changed.
 
 ## Image/bootstrap workflow
 
@@ -44,7 +44,7 @@ To force a full rebuild from OCI:
 
 ```bash
 rm -f ./slicer-base.img
-rm -rf ./kernel/slicer ./kernel/sbox
+rm -rf ./kernel
 rm -rf ./oci-cache
 ```
 
@@ -58,6 +58,14 @@ rm -f ./slicer-1.img
 
 If your VM crashes for some reason, or the Mac's sleep mode causes an issue with the VM, you may find the `.img` file needs to be checked or repaired with the `e2fsck` utility.
 
+Check the filesystem (read-only, no changes):
+
+```bash
+e2fsck -v -n ./slicer-1.img
+```
+
+If errors are found, repair them:
+
 ```bash
 e2fsck -f ./slicer-1.img
 ```

docs/reference/networking.md

@@ -11,12 +11,20 @@ Table of contents:
   * [Firewall](#firewall)
   * [Additional configuration for Netplan](#additional-configuration-for-netplan)
 
-Both Firecracker and Cloud Hypervisor microVMs use TAP devices for networking. A Linux TAP operates at Layer 2 (Data Link Layer), one end is attached to the microVM, and the other end is attached to the host system.
+The Firecracker, QEMU, and Cloud Hypervisors use TAP devices for networking. A Linux TAP operates at Layer 2 (Data Link Layer), one end is attached to the microVM, and the other end is attached to the host system.
 
 Slicer supports multiple networking modes for microVMs, each with their own pros and cons. Generally, you should use the default option (Bridge Networking) unless you have specific requirements that need a different mode.
 
 See `slicer new --help` to generate a Slicer config with bridge-based networking. You can also provide a CIDR block to allocate IP addresses from, if you need to run Slicer across different machines and have them all be routable on the local network.
 
+How do you pick?
+
+* Bridge networking is the default - use it when you want to get started. It lets VMs talk to each other, so it's ideal for K3s where nodes need direct IP to IP access. The host can ingress to VMs via their IP.
+
+* Isolated networking is best when you're running appliances that are connected to the Internet, and can run untrusted workloads, or for other multi-tenant services. You can block VMs from egressing to specific IPs or entire CIDRs like your LAN i.e. `192.168.0.0/24`. There is no ingress available other via `slicer forward` or via network tunnels such as [Inlets](https://inlets.dev).
+
+* CNI mode is generally not recommended or required, but enables additional networking modes, and shares a single pool of IPs across all Slicer daemons running in this mode.
+
 ## Bridge Networking
 
 The default for Slicer is to use create a Linux bridge per Slicer daemon, and to attach all microVMs within that hostgroup to the bridge. This allows microVMs to communicate with each other and with the host system.
@@ -82,7 +90,6 @@ Cons:
 * microVMs can communicate with the host, and the rest of the LAN, which may not be desirable in some use-cases
 * May also have learning delays like the bridge mode
 
-
 Example:
 
 ```yaml