Skip to content

Commit b386b7f

Browse files
alexellisalexellis
committed
Slicer Mac troubleshooting and Linux twin explanations
Signed-off-by: Alex Ellis (OpenFaaS Ltd) <alexellis2@gmail.com>
1 parent 42db218 commit b386b7f

File tree

6 files changed

+165
-36
lines changed

6 files changed

+165
-36
lines changed

‎docs/mac/docker.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ To run both together, configure Docker for Mac to use the Docker VMM option. Doc
88

99
![Docker VMM](/images/mac/docker-vmm.png)
1010

11+
If Slicer for Mac later comes up on the wrong subnet or the VM cannot reach `192.168.64.1`, see [Troubleshooting Slicer for Mac](/mac/troubleshooting).
12+
1113
## Install and configure Docker in the VM
1214

1315
You can keep Docker running inside `slicer-1` and access it from your Mac with the local Docker CLI by forwarding the VM's Unix socket.
@@ -64,3 +66,4 @@ persistent access.
6466
## Next steps
6567

6668
- [Linux VM setup](/mac/linux-vm) - broader VM setup notes, including K3s forwarding
69+
- [Troubleshooting](/mac/troubleshooting) - recover stale vmnet or DHCP state on macOS

‎docs/mac/linux-vm.md‎

Lines changed: 68 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,85 @@
1-
# Linux VM
1+
# Persistent Linux VM
22

3-
Your main VM is `slicer-1` in the `slicer` host group. It's a persistent arm64 Linux environment that boots with the daemon and has your Mac home folder shared in via VirtioFS. This is where you do your day-to-day Linux work - running Docker, K3s, coding agents, Go/Rust builds, and anything else you'd do on a Linux workstation.
3+
Slicer for Mac has two types of VMs.
44

5-
SSH is usually not required for normal workflows. Most tasks are faster with the Slicer CLI:
5+
1. A Persistent Linux VM named `slicer-1` - analogous to WSL2 - your *Linux twin* for macOS.
6+
2. Additional persistent or ephemeral VMs ["sandboxes"](/mac/sandboxes.md) can be launched into the `sbox` host group.
7+
8+
Unlike most sandboxes that optimise for a narrow use-case, each VM is a full Linux Kernel with support for Docker, K3s, eBPF, coding agents, Go/Rust builds with systemd as the init.
9+
10+
Additionally, you can share your home folder or any other folder directly into the VM via VirtioFS.
11+
12+
A built-in guest agent can be used instead of SSH for faster, more efficient access:
613

714
- `slicer vm shell slicer-1`
815
- `slicer vm cp ...`
916
- `slicer vm forward ...`
1017

11-
Use SSH only when you need direct shell access outside this interface. You can add keys directly in the guest by writing to `~/.ssh/authorized_keys`:
18+
SSH is pre-installed, and accessible via the VM's IP address, as shown on `slicer vm list`.
19+
20+
You can add your SSH keys to: `~/.ssh/authorized_keys`, or import them directly from GitHub:
1221

1322
```bash
23+
slicer vm shell slicer-1
24+
1425
curl -sLS https://github.com/alexellis.keys > ~/.ssh/authorized_keys
1526
```
1627

28+
## Architecture diagram
29+
30+
```text
31+
+----------------------------+
32+
| slicer CLI |
33+
| (vm shell / vm cp / API) |
34+
+-------------+--------------+
35+
|
36+
v
37+
+--------------------------------+-----------------------------------+
38+
| slicer-mac daemon on macOS |
39+
| Reads `slicer-mac.yaml` and controls local microVMs |
40+
+-----------------------+----------------------+---------------------+
41+
| |
42+
| |
43+
v v
44+
+-----------------------------+ +----------------------------+
45+
| host_group: slicer | | host_group: sbox |
46+
| Long-lived primary workload | | Disposable / on-demand VMs |
47+
+--------------+--------------+ +-------------+--------------+
48+
| |
49+
v v
50+
+-------------+ +----------------+
51+
| slicer-1 | | sbox-1 |
52+
| main VM | | sample sbox VM |
53+
+-------------+ +----------------+
54+
```
55+
56+
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`.
57+
58+
## The VM lifecycle
59+
60+
It's important to shut down persistent VMs like `slicer-1` gracefully:
61+
62+
```bash
63+
slicer vm shutdown slicer-1
64+
slicer vm exec slicer-1 -- sudo shutdown -h 0
65+
```
66+
67+
If your VM crashes or you kill slicer-mac without letting it shut down the VMs gracefully, you may need to check the disk image, which you can do via the [Troubleshooting](/mac/troubleshooting) page.
68+
69+
If you ever want to "reset" your `slicer-1` VM, you can delete it and then relaunch it.
70+
71+
First shut down slicer-mac.
72+
73+
Then run `rm -rf ~/slicer-mac/slicer-1.img`
74+
75+
Then restart slicer-mac, and you'll get the VM re-created.
76+
1777
## Folder sharing
1878

79+
Folders can be shared directly into any Slicer VM by specifying paths in the slicer-mac.yaml config file or via an API request.
80+
81+
Most of the time copying folders between the host and guest, will be fast enough and more convenient: `slicer cp -r ./source vm:~/destination`.
82+
1983
See [Folder sharing](/mac/folder-sharing) for setup details.
2084

2185
## Forward Docker
@@ -72,36 +136,6 @@ kubectl get nodes
72136

73137
With K3s running inside Slicer, you can test controllers locally, validate Helm charts with a real install, or try RBAC changes without touching a shared cluster.
74138

75-
## Architecture diagram
76-
77-
```text
78-
+----------------------------+
79-
| slicer CLI |
80-
| (vm shell / vm cp / API) |
81-
+-------------+--------------+
82-
|
83-
v
84-
+--------------------------------+-----------------------------------+
85-
| slicer-mac daemon on macOS |
86-
| Reads `slicer-mac.yaml` and controls local microVMs |
87-
+-----------------------+----------------------+---------------------+
88-
| |
89-
| |
90-
v v
91-
+-----------------------------+ +----------------------------+
92-
| host_group: slicer | | host_group: sbox |
93-
| Long-lived primary workload | | Disposable / on-demand VMs |
94-
+--------------+--------------+ +-------------+--------------+
95-
| |
96-
v v
97-
+-------------+ +----------------+
98-
| slicer-1 | | sbox-1 |
99-
| main VM | | sample sbox VM |
100-
+-------------+ +----------------+
101-
```
102-
103-
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`.
104-
105139
## Next steps
106140

107141
- [Sandboxes](/mac/sandboxes) - spin up ephemeral VMs for AI agents and automation

‎docs/mac/overview.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,4 @@ See [Sleep behavior](/mac/sleep) for full guidance and per-mode behavior.
9595
- [Linux VM](/mac/linux-vm) - configure your persistent VM, shared folders, Docker, and K3s aka `slicer-1`
9696
- [Sandboxes](/mac/sandboxes) - spin up and tear down VMs via API for ephemeral tasks
9797
- [Coding agents](/mac/coding-agents) - automation to stand up a VM with Claude Code, OpenCode, and other agents inside the VM
98+
- [Troubleshooting](/mac/troubleshooting) - recover from stale vmnet or DHCP state on macOS

‎docs/mac/sandboxes.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,6 @@ Sandboxes are designed for short-lived workloads and experimentation:
4141

4242
You can launch sandboxes from the CLI, [Go SDK](/platform/go-sdk/), or [REST API](/reference/api).
4343

44-
4544
## Launch, use, and delete
4645

4746
Launch an ephemeral sandbox that is deleted when you reboot it or stop Slicer for Mac:
@@ -111,6 +110,10 @@ slicer relaunch sbox-1
111110

112111
## Customise sandbox resources
113112

113+
Bear in mind that `slicer-1` is already set up to use 8GB of RAM by default, so if you only have a 16GB Mac, launching two sandboxes, at 4GB of RAM each, may overcommit your system.
114+
115+
If you only need sandboxes, you can disable `slicer-1` on start-up by setting `count: 0` in the `slicer` hostgroup, or reduce its RAM allocation.
116+
114117
Edit the `sbox` host group in `slicer-mac.yaml` to change the default vCPU, RAM, or disk size for new sandboxes:
115118

116119
```yaml

‎docs/mac/troubleshooting.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Troubleshooting Slicer for Mac
2+
3+
## No Internet or LAN access from the VM
4+
5+
One failure mode on macOS is that the VM networking gets stuck on the wrong subnet because the host-side vmnet state becomes stale.
6+
You may notice one or more of the following:
7+
8+
- `slicer vm list` shows `slicer-1` on `192.168.64.2`, but the VM cannot reach `192.168.64.1`
9+
- the host shows a stale `bridge100` interface on `192.168.65.1`
10+
- DNS and Internet access fail inside the VM even though the Mac itself is online
11+
12+
The symptom is that the VM has no Internet or LAN access.
13+
The cause is that the VM networking is stuck on the wrong subnet.
14+
15+
In this case, the recovery that has worked reliably is:
16+
17+
- rewrite the stale wrong subnet in the vmnet state from `192.168.65` back to `192.168.64`
18+
- clear the DHCP lease database
19+
- remove the generated vmnet state so macOS rebuilds it
20+
21+
### Recovery steps
22+
23+
Stop Slicer for Mac and any other local VM tooling you were using first.
24+
25+
```bash
26+
pkill -f slicer-mac || true
27+
osascript -e 'tell application "Docker" to quit' || true
28+
```
29+
30+
Remove any stale host bridge created for the shared vmnet range:
31+
32+
```bash
33+
sudo ifconfig bridge100 destroy 2>/dev/null || true
34+
```
35+
36+
If the stale vmnet state shows `192.168.65` where you expect `192.168.64`, rewrite it first:
37+
38+
```bash
39+
sudo sed -i '' 's/192\.168\.65/192.168.64/g' \
40+
/Library/Preferences/SystemConfiguration/com.apple.vmnet.plist
41+
```
42+
43+
Back up and remove the DHCP lease database:
44+
45+
```bash
46+
sudo mv /var/db/dhcpd_leases /var/db/dhcpd_leases.bak.$(date +%s)
47+
```
48+
49+
Back up and remove the generated vmnet state file:
50+
51+
```bash
52+
sudo mv /Library/Preferences/SystemConfiguration/com.apple.vmnet.plist \
53+
/Library/Preferences/SystemConfiguration/com.apple.vmnet.plist.bak.$(date +%s)
54+
```
55+
56+
Start Slicer for Mac again:
57+
58+
```bash
59+
cd ~/slicer-mac
60+
./slicer-mac up
61+
```
62+
63+
### Verify the fix
64+
65+
Confirm the host bridge and VM gateway were recreated correctly:
66+
67+
```bash
68+
ifconfig -a | rg '^(bridge|vmenet)'
69+
slicer vm list
70+
slicer vm exec slicer-1 -- ping -c 2 192.168.64.1
71+
```
72+
73+
If the VM can reach `192.168.64.1` again, the stale state has been cleared.
74+
75+
### What changed
76+
77+
These are the only host-side changes made by the recovery process:
78+
79+
- removed the stale `bridge100` interface if it existed
80+
- rewrote the stale vmnet subnet from `192.168.65` to `192.168.64`
81+
- removed `/var/db/dhcpd_leases` so stale leases would not be reused
82+
- removed `/Library/Preferences/SystemConfiguration/com.apple.vmnet.plist` so macOS could recreate vmnet state
83+
84+
### Notes
85+
86+
- `bridge0` is usually the macOS Thunderbolt Bridge and is unrelated to this issue
87+
- if you also run Docker Desktop, restart Slicer for Mac first, then confirm networking works before bringing Docker back up

‎mkdocs.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,8 +160,9 @@ nav:
160160
- Slicer for Mac:
161161
- Overview: mac/overview.md
162162
- Installation: mac/installation.md
163-
- Linux VM: mac/linux-vm.md
163+
- Persistent Linux VM: mac/linux-vm.md
164164
- Sandboxes: mac/sandboxes.md
165+
- Troubleshooting: mac/troubleshooting.md
165166
- Configuration:
166167
- Enable Rosetta: mac/rosetta.md
167168
- Storage: mac/storage.md

0 commit comments

Comments
 (0)