diff --git a/README.md b/README.md
index 6650dd2d..017b7bf3 100644
--- a/README.md
+++ b/README.md
@@ -178,6 +178,14 @@ the container as environment variables. Common options:
   `<state>/matrix-token` is absent (i.e., the host-level
   `hyperhive.matrix` tuwunel container hasn't provisioned the account
   yet). Set to `false` to opt a specific agent out of matrix.
+- **`hyperhive.user.name`** — Unix username the agent runs as inside
+  the container (default: the agent's own label, injected by the
+  meta-flake). Agents no longer run as root. Stand-alone module eval
+  without the meta-flake falls back to `"agent"`.
+- **`hyperhive.user.passwordlessSudo`** — Boolean (default `true`).
+  Grants the agent user `NOPASSWD: ALL` sudo so claude's `Bash` tool
+  can still escalate when needed — same surface as the old root-user
+  shape, just explicit. Set `false` for strictly unprivileged agents.
 
 See `nix/templates/harness-base.nix` for the full list of options and
 their descriptions.