From 3c3f28b32cdc075be0c1c406620ef4f15a73b895 Mon Sep 17 00:00:00 2001
From: JY Tan <jy8230@gmail.com>
Date: Sat, 17 Jan 2026 13:39:03 -0800
Subject: [PATCH] docs: add more information about nested sandboxing and
 integration test skip behavior

---
 docs/testing.md         | 28 ++++++++++++++++++++++++++++
 docs/troubleshooting.md | 14 ++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/docs/testing.md b/docs/testing.md
index d7a77de..0b57d7a 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -65,6 +65,34 @@ go test -v -run 'TestMacOS' ./internal/sandbox/...
 go test -v -count=1 ./internal/sandbox/...
 ```
 
+#### Sandboxed Build Environments (Nix, etc.)
+
+If you're packaging fence for a distribution (e.g., Nix, Homebrew, Debian), note that some integration tests will be skipped when running `go test` during the build.
+
+Fence's Landlock integration on Linux uses a wrapper approach: the `fence` binary re-executes itself with `--landlock-apply` inside the sandbox. Test binaries (e.g., `sandbox.test`) don't have this handler, so Landlock-specific tests automatically skip when not running as the `fence` CLI.
+
+Tests that skip include those calling `skipIfLandlockNotUsable()`:
+
+- `TestLinux_LandlockBlocksWriteOutsideWorkspace`
+- `TestLinux_LandlockProtectsGitHooks`
+- `TestLinux_LandlockProtectsGitConfig`
+- `TestLinux_LandlockProtectsBashrc`
+- `TestLinux_LandlockAllowsTmpFence`
+- `TestLinux_PathTraversalBlocked`
+- `TestLinux_SeccompBlocksDangerousSyscalls`
+
+| Test Type | What it tests | Landlock coverage |
+|-----------|---------------|-------------------|
+| `go test` (integration) | Go APIs, bwrap isolation, command blocking | Skipped (test binary can't use `--landlock-apply`) |
+| `smoke_test.sh` | Actual `fence` CLI end-to-end | ✅ Full coverage |
+
+For full test coverage including Landlock, run the smoke tests against the built binary (see "Smoke Tests" section below).
+
+**Nested sandboxing limitations:**
+
+- **macOS**: Nested Seatbelt sandboxing is not supported. If the build environment already uses `sandbox-exec` (like Nix's Darwin sandbox), fence's tests cannot create another sandbox. The kernel returns `forbidden-sandbox-reinit`. This is a macOS limitation.
+- **Linux**: Tests should work in most build sandboxes, but Landlock tests will skip as explained above. Runtime functionality is unaffected.
+
 ### Smoke Tests
 
 Smoke tests verify the compiled `fence` binary works end-to-end. Unlike integration tests (which test internal Go APIs), smoke tests exercise the CLI interface.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 66a5cac..0d2a6c4 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,5 +1,19 @@
 # Troubleshooting
 
+## Nested Sandboxing Not Supported
+
+Fence cannot run inside another sandbox that uses the same underlying technology.
+
+**macOS (Seatbelt)**: If you try to run fence inside an existing `sandbox-exec` sandbox (e.g., Nix's Darwin build sandbox), you'll see:
+
+```text
+Sandbox: sandbox-exec(...) deny(1) forbidden-sandbox-reinit
+```
+
+This is a macOS kernel limitation - nested Seatbelt sandboxes are not allowed. There is no workaround.
+
+**Linux (Landlock)**: Landlock supports stacking (nested restrictions), but fence's test binaries cannot use the Landlock wrapper (see [Testing docs](testing.md#sandboxed-build-environments-nix-etc)).
+
 ## "bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted" (Linux)
 
 This error occurs when fence tries to create a network namespace but the environment lacks the `CAP_NET_ADMIN` capability. This is common in: