Structure for Platform / EULA

alexellis · alexellis · commit 7da709549c91 · 2026-04-12T09:01:51.000+01:00
Signed-off-by: Alex Ellis (OpenFaaS Ltd) &lt;alexellis2@gmail.com&gt;
diff --git a/docs/index.md b/docs/index.md
@@ -5,6 +5,8 @@ SlicerVM gives you **real Linux, in milliseconds**.
 Full VMs with systemd and a real kernel, on your Mac, your servers, or your cloud.
 Slicer is built for teams that need isolation and control without moving code and data to third-party infrastructure.
 
+By installing and starting Slicer, you agree to the [End User License Agreement (EULA)](https://slicervm.com/eula/).
+
 ## Where Slicer fits
 
 Slicer is useful for both one-off/ephemeral workloads and long-running Linux services.
diff --git a/docs/mac/overview.md b/docs/mac/overview.md
@@ -4,6 +4,8 @@ Slicer for Mac was built from the ground up to run Linux microVMs on Apple Silic
 
 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.
 
+By installing and starting Slicer, you agree to the [End User License Agreement (EULA)](https://slicervm.com/eula/).
+
 Typical use-cases include:
 
 * Real Linux with systemd instead of POSIX compatibility
diff --git a/docs/mac/sandboxes.md b/docs/mac/sandboxes.md
@@ -62,6 +62,22 @@ Stop and remove the sandbox when you are done:
 slicer vm delete sbox-1
 ```
 
+## Persistent sandboxes
+
+By default, sandboxes are ephemeral - they are deleted when the daemon stops. To create a sandbox that retains its disk and survives restarts, use `--persistent`:
+
+```bash
+slicer vm launch sbox --persistent
+```
+
+If the daemon restarts (e.g. after a reboot or sleep), persistent sandboxes are not automatically re-launched. To bring one back:
+
+```bash
+slicer relaunch sbox-1
+```
+
+This boots the VM from its existing disk. Any data written to the filesystem is still there.
+
 ## Use cases
 
 Sandboxes are designed for short-lived workloads and experimentation:
diff --git a/docs/platform/ephemeral-tasks.md b/docs/platform/ephemeral-tasks.md
@@ -1,17 +1,16 @@
-# Ephemeral Tasks
+# Run a Task in Slicer
 
-This page shows how to launch short-lived VMs for one-shot tasks via the API. The CLI can also act as a client to the API during testing.
+If your product needs to run background jobs, cron-style tasks, or headless AI agents in isolated environments, you can launch microVMs on demand through the API and tear them down when the work is done. The CLI can also act as a client to the API during testing.
 
-Use-cases could include:
+Use-cases include:
 
-* Running an AI coding agent in a contained environment without risking your whole workstation
-* Starting on-demand IDEs for pull request development or review
-* Autoscaling Kubernetes nodes - added and removed on demand
-* Running a CI build or compiling untrusted customer code
-* Starting a temporary service such as a database for end to end testing
-* Cron jobs, batch jobs, and serverless functions
+* Background jobs and batch processing as part of a SaaS product
+* Running headless AI coding agents in isolated microVMs
+* Cron jobs, scheduled tasks, and serverless-style functions
+* CI builds or compiling untrusted customer code
+* On-demand IDEs for pull request development or review
 
-One-shot tasks are VMs that are launched on demand for a specific purposes. But there's no limit on the lifetime of these VMs, they can run for any period of time - be that 250ms to process a webhook, 48 hours to run some fine-tuning, or several weeks. Just bear in mind that if you shut down or close Slicer, they will also be shut down and destroyed.
+There is no limit on how long a task VM runs - it could be 250ms to process a webhook, 48 hours for fine-tuning, or several weeks. Ephemeral VMs are cleaned up when Slicer shuts down. Use `"persistent": true` if the VM needs to survive restarts.
 
 <iframe width="560" height="315" src="https://www.youtube.com/embed/5RjtVM4bvp0?si=2TPpSKn9YXFw_Nnt" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
@@ -32,7 +31,7 @@ If you don't have ZFS set up yet, you can simply replace the storage flags with
 Create `tasks.yaml` slicer config:
 
 ```bash
-slicer new buildkit \
+slicer new task \
   --cpu 1 \
   --ram 2 \
   --count 0 \
diff --git a/docs/platform/instance-per-tenant.md b/docs/platform/instance-per-tenant.md
@@ -0,0 +1,163 @@
+# Instance Per Tenant
+
+For stronger isolation, run a separate Slicer daemon per tenant. Each gets its own UNIX socket, its own network range, and its own VM namespace. Tenant A cannot see, manage, or reach tenant B's VMs.
+
+```
+┌───────────────────────────────────────────────────────┐
+│  Your Application                                     │
+│                                                       │
+│  Tenant A request ──► /run/slicer/a3cf.sock           │
+│  Tenant B request ──► /run/slicer/e7d1.sock           │
+└───────────┬───────────────────────────┬───────────────┘
+            ▼                           ▼
+┌─────────────────────┐   ┌─────────────────────┐
+│ Slicer (a3cf)       │   │ Slicer (e7d1)       │
+│ 169.254.100.0/22    │   │ 169.254.104.0/22    │
+│                     │   │                     │
+│ ┌────────┐┌────────┐│   │ ┌────────┐┌────────┐│
+│ │ a3cf-1 ││ a3cf-2 ││   │ │ e7d1-1 ││ e7d1-2 ││
+│ └────────┘└────────┘│   │ └────────┘└────────┘│
+└─────────────────────┘   └─────────────────────┘
+```
+
+## When to use this
+
+Use a separate instance per tenant when:
+
+* You need API-level isolation - one tenant's requests cannot access another's VMs
+* You need network isolation between tenants
+* You want independent failure domains - one tenant's daemon crashing does not affect others
+* Compliance or security requirements demand full separation
+
+## Configuration
+
+Generate a config per tenant with isolated networking, a UNIX socket, and a non-overlapping IP range. Use [isolated mode networking](/reference/networking/#isolated-mode-networking) so VMs from different tenants cannot communicate.
+
+Tenant A:
+
+```bash
+slicer new a3cf \
+  --net=isolated \
+  --isolated-range 169.254.100.0/22 \
+  --socket /run/slicer/a3cf.sock \
+  --count=0 \
+  --graceful-shutdown=false \
+  --drop 192.168.1.0/24 \
+  > tenant-a.yaml
+```
+
+This produces:
+
+```yaml
+config:
+  host_groups:
+    - name: a3cf
+      storage: image
+      storage_size: 25G
+      count: 0
+      vcpu: 2
+      ram_gb: 4
+      network:
+        mode: "isolated"
+        range: "169.254.100.0/22"
+        drop: ["192.168.1.0/24"]
+        allow: ["0.0.0.0/0"]
+  image: "ghcr.io/openfaasltd/slicer-systemd:6.1.90-x86_64-latest"
+  hypervisor: firecracker
+  graceful_shutdown: false
+  api:
+    bind_address: "/run/slicer/a3cf.sock"
+```
+
+Tenant B:
+
+```bash
+slicer new e7d1 \
+  --net=isolated \
+  --isolated-range 169.254.104.0/22 \
+  --socket /run/slicer/e7d1.sock \
+  --count=0 \
+  --graceful-shutdown=false \
+  --drop 192.168.1.0/24 \
+  > tenant-b.yaml
+```
+
+```yaml
+config:
+  host_groups:
+    - name: e7d1
+      storage: image
+      storage_size: 25G
+      count: 0
+      vcpu: 2
+      ram_gb: 4
+      network:
+        mode: "isolated"
+        range: "169.254.104.0/22"
+        drop: ["192.168.1.0/24"]
+        allow: ["0.0.0.0/0"]
+  image: "ghcr.io/openfaasltd/slicer-systemd:6.1.90-x86_64-latest"
+  hypervisor: firecracker
+  graceful_shutdown: false
+  api:
+    bind_address: "/run/slicer/e7d1.sock"
+```
+
+Each `/22` range provides 256 usable VM slots. Use non-overlapping ranges when running multiple daemons on the same host (e.g. `169.254.100.0/22`, `169.254.104.0/22`, `169.254.108.0/22`).
+
+In isolated mode, each VM gets its own network namespace. VMs cannot communicate with each other, with the host, or with the LAN. The `drop` list blocks specific CIDRs. Auth is disabled by default for UNIX sockets since access is controlled by filesystem permissions.
+
+## Start each daemon
+
+Start each daemon in its own terminal or tmux window:
+
+```bash
+sudo slicer up tenant-a.yaml
+```
+
+```bash
+sudo slicer up tenant-b.yaml
+```
+
+Each daemon manages its own VMs. Your application routes requests to the correct socket based on which tenant is making the request.
+
+For production, run each daemon as a systemd service - one unit per tenant. See [running in the background](/getting-started/daemon/) for setup.
+
+## API isolation
+
+Each daemon has its own VM namespace. Listing nodes on tenant A's socket returns only tenant A's VMs:
+
+```bash
+TOKEN=$(sudo cat /var/lib/slicer/auth/token)
+
+# Tenant A: create a VM
+sudo curl -sf --unix-socket /run/slicer/a3cf.sock \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -X POST http://localhost/hostgroup/a3cf/nodes \
+  -d '{"tags":["user=alice","job=123"]}'
+
+# Tenant B: create a VM
+sudo curl -sf --unix-socket /run/slicer/e7d1.sock \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -X POST http://localhost/hostgroup/e7d1/nodes \
+  -d '{"tags":["user=bob","job=456"]}'
+
+# Tenant A sees only its own VMs
+sudo curl -sf --unix-socket /run/slicer/a3cf.sock \
+  -H "Authorization: Bearer $TOKEN" http://localhost/nodes
+```
+
+```json
+[{"hostname":"a3cf-1","hostgroup":"a3cf","ip":"169.254.100.2",
+  "tags":["user=alice","job=123"],"status":"Running"}]
+```
+
+Tenant A cannot manage, exec into, or copy files to tenant B's VMs through its socket.
+
+## See also
+
+* [Single Slicer instance](/platform/single-instance/) - simpler deployment for trusted environments
+* [Networking](/reference/networking/) - CIDR configuration and bridge setup
+* [REST API reference](/reference/api/) - full endpoint documentation
diff --git a/docs/platform/overview.md b/docs/platform/overview.md
@@ -4,6 +4,8 @@ Slicer gives you on-demand Linux VMs through a REST API and Go SDK. You can crea
 
 This section assumes [Slicer for Linux](/getting-started/install/), but many of the REST API examples will also work on [Slicer for Mac](/mac/overview/) if you use the `sbox` host group.
 
+By installing and starting Slicer, you agree to the [End User License Agreement (EULA)](https://slicervm.com/eula/).
+
 ## Self-hosted, real microVMs
 
 Slicer runs on your hardware. Every VM is a real microVM with its own kernel - not a container dressed up as one. Unlike hosted platforms like Modal, Daytona, or Fly, there are no artificial timeouts, no per-second metering, no rate limits on the API, and no mandatory scale-to-zero. Your VMs run for as long as you need them, using as many resources as the host has available.
@@ -21,6 +23,8 @@ Each VM runs a real Linux kernel with systemd. It is not a container.
 
 VMs launched through the API are called **sandboxes**. They are ephemeral by default: shut down Slicer and they are cleaned up automatically. Sandboxes can also be configured to persist, which is how multi-tenant platforms and the [Kubernetes autoscaler](/examples/autoscaling-k3s/) work - VMs stay running until you explicitly delete them.
 
+To create a persistent sandbox, pass `"persistent": true` in the create request (or `--persistent` via the CLI). Persistent VMs survive Slicer restarts and their disk is retained until you delete the VM.
+
 ## Common use-cases
 
 * **Code execution**: run untrusted or user-submitted code in a VM that gets destroyed afterwards
@@ -40,6 +44,43 @@ VMs launched through the API are called **sandboxes**. They are ephemeral by def
 
 The host group sets defaults (CPU, RAM, image, storage backend). Individual VMs can override CPU and RAM at creation time.
 
+VM hostnames are auto-assigned with an incrementing integer based on the host group name (e.g. `sandbox-1`, `sandbox-2`, `sandbox-3`). If you need to correlate a VM with a user, job, or request in your system, pass `tags` when creating the VM. Tags are returned in list responses and can be used to look up VMs later.
+
+## Reference architecture
+
+The difference between "Slicer for Linux" and "Slicer Platform" is who is driving. With Slicer for Linux, a person runs CLI commands. With Slicer Platform, your application drives Slicer through the API.
+
+```
+┌──────────────┐        ┌──────────────┐        ┌──────────────┐
+│  Your Users  │ ────►  │  Your App    │ ────►  │  Slicer API  │
+└──────────────┘        └──────────────┘        └──────┬───────┘
+                                                       │
+                                              create / exec / cp / delete
+                                                       │
+                                                       ▼
+                                                ┌──────────────┐
+                                                │   microVMs   │
+                                                └──────────────┘
+```
+
+There are two deployment models depending on your isolation requirements:
+
+* [Single Slicer instance](/platform/single-instance/) - one daemon, all tenants share it, use tags to track ownership
+* [Instance per tenant](/platform/instance-per-tenant/) - one daemon per tenant with its own UNIX socket and isolated network
+
+A typical request flow for a code execution platform:
+
+1. User submits code through your frontend
+2. Your backend calls `POST /hostgroup/sandbox/nodes` to create a VM
+3. Poll `GET /vm/HOSTNAME/health` until the agent is ready
+4. `POST /vm/HOSTNAME/cp` to copy the code into the VM
+5. `POST /vm/HOSTNAME/exec` to run it
+6. `GET /vm/HOSTNAME/cp` to copy results back
+7. `DELETE /hostgroup/sandbox/nodes/HOSTNAME` to clean up
+8. Return the result to the user
+
+The entire flow takes seconds. Each user gets a dedicated VM with its own kernel - no shared state, no container escapes.
+
 ## API surfaces
 
 Slicer exposes three ways to manage VMs programmatically:
diff --git a/docs/platform/quickstart.md b/docs/platform/quickstart.md
@@ -67,6 +67,16 @@ To override the host group defaults for CPU or RAM:
 }
 ```
 
+Hostnames are auto-assigned (`sandbox-1`, `sandbox-2`, etc.). To track which VM belongs to which user or job in your system, pass `tags`:
+
+```json
+{
+  "tags": ["user=alice", "job=convert-video-123"]
+}
+```
+
+Tags are returned when you list VMs, so your application can match VMs back to its own records.
+
 ## Wait for the agent
 
 The guest agent needs to start before you can run commands or copy files. Poll the health endpoint:
@@ -164,6 +174,20 @@ curl -sf -H "Authorization: Bearer $TOKEN" \
 
 Poll `/vm/HOSTNAME/health` and check `userdata_ran` to know when the script has finished.
 
+## Create a persistent sandbox
+
+By default, sandboxes are ephemeral - they are destroyed when Slicer shuts down. To create a VM that survives restarts and retains its disk, pass `"persistent": true`:
+
+```bash
+curl -sf -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -X POST \
+  http://127.0.0.1:8080/hostgroup/sandbox/nodes \
+  -d '{"persistent": true}'
+```
+
+The `persistent` field is returned in list responses so your application can distinguish between ephemeral and persistent VMs.
+
 ## Delete the sandbox
 
 ```bash
diff --git a/docs/platform/single-instance.md b/docs/platform/single-instance.md
diff --git a/mkdocs.yml b/mkdocs.yml
