From 0b59c5bc2011b0f031dc376d4255f2c3fbbb2765 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 10 Jan 2026 14:00:54 +0000
Subject: [PATCH] Add user namespace troubleshooting docs for Ubuntu 24.04+

Document the AppArmor restriction on unprivileged user namespaces
that affects Ubuntu 24.04+ systems and how to enable them.
---
 CLAUDE.md        | 22 ++++++++++++++++++++++
 setup-sandbox.sh |  6 +++++-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 9c44714..e4b09b6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -299,6 +299,28 @@ Run `./setup-sandbox.sh` to check your system's security configuration:
 
 Use `./setup-sandbox.sh --fix` to automatically fix common issues (requires root)
 
+### Troubleshooting User Namespaces
+
+If you see the message "User namespaces not available", enable them with:
+
+```bash
+# Standard Linux systems
+sudo sysctl -w kernel.unprivileged_userns_clone=1
+
+# Ubuntu 24.04+ (AppArmor restriction)
+sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+```
+
+To make the change persistent across reboots:
+
+```bash
+# Standard Linux systems
+echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf
+
+# Ubuntu 24.04+
+echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/99-userns.conf
+```
+
 ## Quick Start
 
 ```bash
diff --git a/setup-sandbox.sh b/setup-sandbox.sh
index fbaf149..83778a6 100755
--- a/setup-sandbox.sh
+++ b/setup-sandbox.sh
@@ -115,8 +115,12 @@ check_user_namespaces() {
             check_fail "Unprivileged user namespaces disabled"
             echo ""
             echo "      Enable with:"
-            echo "        sudo sysctl kernel.unprivileged_userns_clone=1"
+            echo "        sudo sysctl -w kernel.unprivileged_userns_clone=1"
             echo "        echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf"
+            echo ""
+            echo "      On Ubuntu 24.04+ (AppArmor restriction):"
+            echo "        sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0"
+            echo "        echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/99-userns.conf"
 
             if $FIX_MODE; then
                 echo ""