docs: update docs (#93)

* docs: update docs

* add comments

* remove unnecessary check

* docs: update docs

Author: evgeniy-scherbina

README.md

@@ -68,12 +68,14 @@ boundary-run -- bash
 If you prefer to run `boundary` directly, you'll need to handle privilege escalation:
 
 ```bash
+# Note: sys_admin is only needed in restricted environments (e.g., Docker with seccomp).
+# If boundary works without it on your system, you can remove +sys_admin from both flags.
 sudo -E env PATH=$PATH setpriv \
   --reuid=$(id -u) \
   --regid=$(id -g) \
   --clear-groups \
-  --inh-caps=+net_admin \
-  --ambient-caps=+net_admin \
+  --inh-caps=+net_admin,+sys_admin \
+  --ambient-caps=+net_admin,+sys_admin \
   boundary --allow "domain=github.com" -- curl https://github.com
 ```
 
@@ -134,6 +136,18 @@ boundary-run --log-level debug --allow "domain=github.com" -- git pull  # Debug
 | macOS    | Not supported                  | -                         |
 | Windows  | Not supported                  | -                         |
 
+## Security and Privileges
+
+**All processes are expected to run as non-root users** for security best practices:
+
+- **boundary-parent**: The main boundary process that sets up network isolation
+- **boundary-child**: The child process created within the network namespace
+- **target/agent process**: The command you're running (e.g., `curl`, `npm`, `bash`)
+
+The `boundary-run` wrapper script handles privilege escalation automatically using `setpriv` to drop privileges before launching boundary. This ensures all processes run with the minimum required capabilities (`CAP_NET_ADMIN` and optionally `CAP_SYS_ADMIN` for restricted environments) while executing as your regular user account.
+
+If you run `boundary` directly with `sudo` (without `setpriv`), all processes will run as root, which is **not recommended** for security reasons. Always use `boundary-run` or the equivalent `setpriv` command shown in the [Direct Usage](#direct-usage) section.
+
 ## Command-Line Options
 
 ```text

scripts/boundary-wrapper.sh

@@ -13,13 +13,9 @@ else
     exit 1
 fi
 
-# Check if we're already running as the target user (not root)
-if [ "$(id -u)" -eq 0 ]; then
-    echo "Error: This wrapper should not be run as root. It will handle privilege escalation automatically." >&2
-    exit 1
-fi
-
 # Run boundary with proper privilege handling
+# Note: sys_admin is only needed in restricted environments (e.g., Docker with seccomp).
+# If boundary works without it on your system, you can remove +sys_admin from both flags.
 exec sudo -E env PATH="$PATH" setpriv \
     --reuid="$(id -u)" \
     --regid="$(id -g)" \