chroot-distro 2.3.0__tar.gz → 2.3.2__tar.gz

{chroot_distro-2.3.0 → chroot_distro-2.3.2}/.github/workflows/publish.yml

@@ -16,7 +16,7 @@ jobs:
         runs-on: ubuntu-latest
 
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v7
               with:
                   ref: ${{ github.event.workflow_run.head_sha }}
 
@@ -50,7 +50,7 @@ jobs:
             prerelease: ${{ steps.meta.outputs.prerelease }}
 
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v7
               with:
                   ref: ${{ github.event.workflow_run.head_sha }}
 
@@ -120,7 +120,7 @@ jobs:
         runs-on: ubuntu-latest
 
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v7
               with:
                   ref: ${{ needs.prepare.outputs.tag }}
 
@@ -138,7 +138,7 @@ jobs:
               run: python -m twine check dist/*
 
             - name: Upload build artifacts
-              uses: actions/upload-artifact@v4
+              uses: actions/upload-artifact@v7
               with:
                   name: python-package-distributions
                   path: dist/
@@ -153,7 +153,7 @@ jobs:
 
         steps:
             - name: Download build artifacts
-              uses: actions/download-artifact@v4
+              uses: actions/download-artifact@v8
               with:
                   name: python-package-distributions
                   path: dist/
@@ -170,7 +170,7 @@ jobs:
 
         steps:
             - name: Checkout repository
-              uses: actions/checkout@v4
+              uses: actions/checkout@v7
               with:
                   ref: ${{ needs.prepare.outputs.tag }}
                   fetch-depth: 0

{chroot_distro-2.3.0 → chroot_distro-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chroot-distro
-Version: 2.3.0
+Version: 2.3.2
 Summary: chroot-distro is a lightweight Linux container management utility built around chroot.
 Project-URL: Homepage, https://github.com/sabamdarif/chroot-distro
 Project-URL: Repository, https://github.com/sabamdarif/chroot-distro
@@ -157,15 +157,8 @@ pip install .
 ### First-run check
 
 On startup, commands that modify containers or mounts verify that the
-effective UID is `0`. If not, Chroot-Distro re-executes itself using, in
-order: `sudo`, `doas`, `pkexec`, or `su`.
-
-| Situation | Behaviour |
-|---|---|
-| Default | Auto-elevate when not root. |
-| `--no-elevate` or `CHROOT_DISTRO_NO_ELEVATE=1` | Skip elevation; exit with an error if not root. |
-| Termux, default | Prefer `su` (real root) over `sudo`. |
-| Termux, `--use-sudo` or `CHROOT_DISTRO_USE_SUDO=1` | Prefer `sudo` for elevation. |
+effective UID is `0`. If not, Chroot-Distro auto-elevates when not root by
+re-executing itself using, in order: `sudo`, `doas`, `pkexec`, or `su`.
 
 `list`, `ps`, `search`, `info`, and `help` do not require root on Termux and
 are never re-executed. On regular Linux, `list`, `ps`, and `info` still
@@ -233,8 +226,6 @@ laid out for the current terminal width.
 | Option | Description |
 |---|---|
 | `-h`, `--help` | Show top-level help. |
-| `--no-elevate` | Do not auto-elevate to root (`CHROOT_DISTRO_NO_ELEVATE=1`). |
-| `--use-sudo` | On Termux, prefer `sudo` over `su` (`CHROOT_DISTRO_USE_SUDO=1`). |
 
 Short aliases are accepted for many commands (`sh` → `login`, `rm` →
 `remove`, `ins` → `install`, etc.); each section below lists them.
@@ -477,13 +468,12 @@ chroot-distro login ubuntu --get-chroot-cmd
 | Option | Description |
 |---|---|
 | `-u`, `--user USER` | Log in as USER (default: `root`). Accepts `name`, numeric `uid`, `name:group`, or `uid:gid`. |
-| `--isolated` | Reduce host exposure and enable namespace isolation (mount, PID, UTS, IPC via `unshare`/`nsenter`). On Termux: also skip Android system, storage, and `$PREFIX` binds unless you opt in with `--shared-*` or `--bind`. (Fresh `/tmp` and `/run` are the default in every mode now, not just `--isolated`.) Mutually exclusive with `--minimal`. |
+| `--isolated` | Reduce host exposure and enable namespace isolation (mount, PID, UTS, IPC, and cgroup when supported, via `unshare`/`nsenter`). On Termux: also skip Android system, storage, and `$PREFIX` binds unless you opt in with `--shared-*` or `--bind`. (Fresh `/tmp` and `/run` are the default in every mode now, not just `--isolated`.) Mutually exclusive with `--minimal`. To get the same namespace isolation **without** reducing the mount set, set `CD_USE_NS=1` instead (see [Environment variables](#environment-variables)). |
 | `--minimal` | Bare minimum chroot: core pseudo-filesystems only (`/dev`, `/proc`, `/sys`, plus `/run`, `/dev/pts`, `/dev/shm` when present). Stripped guest environment. Mutually exclusive with `--isolated`. |
 | `--shared-home` | Bind the invoking user's host home into the guest home (or `/root` for root). On Termux, binds `TERMUX_HOME`. |
 | `--shared-tmp` | Bind host tmp (`/tmp` on Linux, `$PREFIX/tmp` on Termux) to `/tmp` in the guest. Opt-in only: by default the container gets its own fresh `/tmp`, not the host's. |
 | `--shared-display` | Share the host display server (X11 and Wayland), audio (PulseAudio/PipeWire), and D-Bus session bus with the container. Binds only the specific session sockets, not the host's whole `/run`. Opt-in only. `--shared-x11` is accepted as a backward-compatible alias. |
 | `-b`, `--bind SRC[:DST]` | Bind-mount a custom host path (repeatable). `DST` must be an absolute guest path. |
-| `--hostname STRING` | Hostname inside the container (default: the container name). |
 | `-w`, `--work-dir PATH` | Initial working directory (default: user's home). |
 | `-e`, `--env VAR=VALUE` | Set a guest environment variable (repeatable). |
 | `--get-chroot-cmd` | Print the fully assembled `env` + `chroot` command line and exit. |
@@ -572,23 +562,38 @@ Termux.)
 - Guest `ldconfig` is run inside the chroot to refresh the shared library
   cache after the new libraries are bind-mounted.
 
-#### Namespace isolation (`--isolated`)
+#### Namespace isolation (`--isolated` and `CD_USE_NS`)
 
 With `--isolated`, chroot-distro creates a per-container namespace holder
 (`unshare`) and runs bind mounts, special mounts, and `chroot` inside that
 environment (`nsenter`). Supported namespaces: **mount**, **PID**, **UTS**,
-and **IPC**. Isolation is **all-or-nothing**: chroot-distro probes the full
-requested namespace set first, and if any one of them is unsupported on the
-kernel it acquires none of them and falls back fully to a non-isolated
-login (with a warning naming the missing namespace), so a session is never
-left half-isolated. This is inspired by
+**IPC**, and **cgroup**. The cgroup namespace is acquired best-effort (used
+when the kernel supports it, skipped otherwise); the **mount/PID/UTS/IPC**
+set is **all-or-nothing**: chroot-distro probes that set first, and if any
+one of them is unsupported on the kernel it acquires none of them and falls
+back fully to a non-isolated login (with a warning naming the missing
+namespace), so a session is never left half-isolated. This is inspired by
 [Ubuntu-Chroot](Ubuntu-Chroot/tools/chroot.sh) and is **not** a full
 container runtime: there is no network namespace, no user namespace
 mapping, and no image layering.
 
-Do not mix `--isolated` and non-isolated logins on the same container
-without running `chroot-distro unmount <name>` first. Concurrent
-`--isolated` sessions share the same holder and mounts.
+`--isolated` couples two things: namespace isolation **and** a reduced set
+of host bind mounts (it skips the Android system/storage/`$PREFIX` binds on
+Termux, and `/tmp`/display sharing on Linux, unless re-enabled with
+`--shared-*` / `--bind`). If you want **only** the namespace isolation
+while keeping every default mount, set the `CD_USE_NS=1` environment
+variable instead: every `login`/`run` then runs in the same
+mount/PID/UTS/IPC/cgroup namespaces but with the full default mount set
+intact. `CD_USE_NS` accepts `1`/`true`/`yes`/`on`.
+
+> `CD_USE_NS` is set by the invoking user but the tool re-executes itself
+> as root; chroot-distro forwards the variable across `sudo`/`doas`/`pkexec`
+> /`su` automatically, so it keeps working even when the `sudo` line prints
+> `'-E' is ignored`.
+
+Do not mix isolated (via `--isolated` or `CD_USE_NS`) and non-isolated
+logins on the same container without running `chroot-distro unmount <name>`
+first. Concurrent isolated sessions share the same holder and mounts.
 
 #### Host bindings (Termux, default mode)
 
@@ -632,8 +637,7 @@ entries win):
    when not `--isolated` and not `--minimal`.
 4. Your `--env VAR=VALUE` entries.
 5. `HOME`, `USER`, `TERM` (default `xterm-256color`), `COLORTERM`
-   (when set on the host), and `HOSTNAME` (the `--hostname` value, else the
-   container name).
+   (when set on the host), and `HOSTNAME` (the container name).
 6. When display sharing is active (via `--shared-display`):
    `DISPLAY`, `XAUTHORITY`, `XDG_RUNTIME_DIR`, `WAYLAND_DISPLAY`,
    `XDG_SESSION_TYPE`, `XDG_CURRENT_DESKTOP`, `DESKTOP_SESSION`,
@@ -645,10 +649,11 @@ entries win):
    WSL2 — `GALLIUM_DRIVER`, `MESA_D3D12_DEFAULT_DEVICE_TYPE`,
    `LIBGL_ALWAYS_SOFTWARE`. Your `--env` entries override these.
 
-`HOSTNAME` is always set to the container name (or `--hostname`). The
-`hostname`/`uname` commands report it only under `--isolated`, where the
-UTS namespace is given a real hostname; without `--isolated` they still
-report the host's name (no UTS namespace to change).
+`HOSTNAME` is always set to the host system hostname name. The
+`hostname`/`uname` commands report it only when namespace isolation is
+active (via `--isolated` or `CD_USE_NS`), where the UTS namespace is given
+a real hostname; otherwise they still report the host's name (no UTS
+namespace to change).
 
 On Termux (unless isolated or minimal), `$PREFIX/bin` is appended to
 `PATH`. A snippet at `/etc/profile.d/termux-profile.sh` re-applies
@@ -1179,9 +1184,8 @@ paths on Linux are typically under `/root/.local/share/` and
 | `CD_DOWNLOAD_WORKERS` | Parallel registry layer downloads during `install` (default `4`, maximum `10`). Invalid values use the default; out-of-range values are clamped. |
 | `CD_DOWNLOAD_RATE_LIMIT` | Bandwidth limit for downloads (e.g., `5M` for 5 MiB/s, default `0` = unlimited). Supports suffixes `K`, `M`, `G` (case-insensitive). |
 | `CD_DOWNLOAD_MAX_RETRIES` | Maximum retry attempts per connection failure (default `3`, clamped between `0` and `20`). |
+| `CD_USE_NS` | When truthy (`1`/`true`/`yes`/`on`), every `login`/`run` uses full Linux namespace isolation (mount, PID, UTS, IPC, and cgroup when supported) **without** skipping any default bind mounts. Differs from `--isolated`, which also reduces the mount set. Forwarded across privilege elevation automatically. |
 | `CD_FORCE_NO_COLORS` | When set, disables ANSI colours in Chroot-Distro output. |
-| `CHROOT_DISTRO_NO_ELEVATE` | When set to `1`, disables privilege auto-elevation (same as `--no-elevate`). |
-| `CHROOT_DISTRO_USE_SUDO` | When set to `1`, prefer `sudo` over `su` on Termux (same as `--use-sudo`). |
 | `COLUMNS` | Fallback terminal width for `--help` rendering. |
 | `TERM`, `COLORTERM` | Inherited into the guest (always; even in `--minimal`). `TERM` defaults to `xterm-256color` when unset on the host. |
 
@@ -1209,7 +1213,7 @@ overridden from `manifest.json` image `Env`, but can be overridden with
 
 | Variable | Source / Fallback |
 |---|---|
-| `HOSTNAME` | `--hostname` value; fallback the container name. Under `--isolated` the UTS namespace hostname is also set so `hostname`/`uname -n` report it. |
+| `HOSTNAME` | The container name. Under `--isolated` the UTS namespace hostname is also set so `hostname`/`uname -n` report it. |
 
 **GPU — NVIDIA native Linux (auto-detected, non-minimal):**
 
@@ -1237,10 +1241,9 @@ Completion scripts for Bash, Zsh, and Fish live in
 - `_chroot-distro`
 - `chroot-distro.fish`
 
-They complete subcommands, global flags (`--no-elevate`, `--use-sudo`),
-and per-command options (including `login`/`run` flags such as
-`--shared-home`, `--shared-display`, `--get-chroot-cmd`, `--isolated`,
-and `--minimal`).
+They complete subcommands, global flags, and per-command options (including
+`login`/`run` flags such as `--shared-home`, `--shared-display`,
+`--get-chroot-cmd`, `--isolated`, and `--minimal`).
 
 If your shell does not pick them up automatically, install them manually:
 
@@ -1274,9 +1277,10 @@ cp src/chroot_distro/completions/chroot-distro.fish \
 - **Kernel features**: FUSE modules, real `iptables`, custom cgroup
   hierarchies, and similar kernel-module features may not work inside the
   guest.
-- **Namespaces**: `--isolated` provides mount/PID/UTS/IPC isolation via
-  `unshare`/`nsenter`, but there is no network namespace and no parity with
-  Docker or Podman.
+- **Namespaces**: `--isolated` (or `CD_USE_NS=1`) provides
+  mount/PID/UTS/IPC isolation, plus the cgroup namespace when the kernel
+  supports it, via `unshare`/`nsenter` — but there is no network namespace,
+  no user-namespace mapping, and no parity with Docker or Podman.
 - **Bind mount hygiene**: crashed sessions or orphan processes can leave
   mounts busy; `unmount` and lazy unmount mitigate this but orphaned
   processes should be cleaned up.

{chroot_distro-2.3.0 → chroot_distro-2.3.2}/README.md

@@ -128,15 +128,8 @@ pip install .
 ### First-run check
 
 On startup, commands that modify containers or mounts verify that the
-effective UID is `0`. If not, Chroot-Distro re-executes itself using, in
-order: `sudo`, `doas`, `pkexec`, or `su`.
-
-| Situation | Behaviour |
-|---|---|
-| Default | Auto-elevate when not root. |
-| `--no-elevate` or `CHROOT_DISTRO_NO_ELEVATE=1` | Skip elevation; exit with an error if not root. |
-| Termux, default | Prefer `su` (real root) over `sudo`. |
-| Termux, `--use-sudo` or `CHROOT_DISTRO_USE_SUDO=1` | Prefer `sudo` for elevation. |
+effective UID is `0`. If not, Chroot-Distro auto-elevates when not root by
+re-executing itself using, in order: `sudo`, `doas`, `pkexec`, or `su`.
 
 `list`, `ps`, `search`, `info`, and `help` do not require root on Termux and
 are never re-executed. On regular Linux, `list`, `ps`, and `info` still
@@ -204,8 +197,6 @@ laid out for the current terminal width.
 | Option | Description |
 |---|---|
 | `-h`, `--help` | Show top-level help. |
-| `--no-elevate` | Do not auto-elevate to root (`CHROOT_DISTRO_NO_ELEVATE=1`). |
-| `--use-sudo` | On Termux, prefer `sudo` over `su` (`CHROOT_DISTRO_USE_SUDO=1`). |
 
 Short aliases are accepted for many commands (`sh` → `login`, `rm` →
 `remove`, `ins` → `install`, etc.); each section below lists them.
@@ -448,13 +439,12 @@ chroot-distro login ubuntu --get-chroot-cmd
 | Option | Description |
 |---|---|
 | `-u`, `--user USER` | Log in as USER (default: `root`). Accepts `name`, numeric `uid`, `name:group`, or `uid:gid`. |
-| `--isolated` | Reduce host exposure and enable namespace isolation (mount, PID, UTS, IPC via `unshare`/`nsenter`). On Termux: also skip Android system, storage, and `$PREFIX` binds unless you opt in with `--shared-*` or `--bind`. (Fresh `/tmp` and `/run` are the default in every mode now, not just `--isolated`.) Mutually exclusive with `--minimal`. |
+| `--isolated` | Reduce host exposure and enable namespace isolation (mount, PID, UTS, IPC, and cgroup when supported, via `unshare`/`nsenter`). On Termux: also skip Android system, storage, and `$PREFIX` binds unless you opt in with `--shared-*` or `--bind`. (Fresh `/tmp` and `/run` are the default in every mode now, not just `--isolated`.) Mutually exclusive with `--minimal`. To get the same namespace isolation **without** reducing the mount set, set `CD_USE_NS=1` instead (see [Environment variables](#environment-variables)). |
 | `--minimal` | Bare minimum chroot: core pseudo-filesystems only (`/dev`, `/proc`, `/sys`, plus `/run`, `/dev/pts`, `/dev/shm` when present). Stripped guest environment. Mutually exclusive with `--isolated`. |
 | `--shared-home` | Bind the invoking user's host home into the guest home (or `/root` for root). On Termux, binds `TERMUX_HOME`. |
 | `--shared-tmp` | Bind host tmp (`/tmp` on Linux, `$PREFIX/tmp` on Termux) to `/tmp` in the guest. Opt-in only: by default the container gets its own fresh `/tmp`, not the host's. |
 | `--shared-display` | Share the host display server (X11 and Wayland), audio (PulseAudio/PipeWire), and D-Bus session bus with the container. Binds only the specific session sockets, not the host's whole `/run`. Opt-in only. `--shared-x11` is accepted as a backward-compatible alias. |
 | `-b`, `--bind SRC[:DST]` | Bind-mount a custom host path (repeatable). `DST` must be an absolute guest path. |
-| `--hostname STRING` | Hostname inside the container (default: the container name). |
 | `-w`, `--work-dir PATH` | Initial working directory (default: user's home). |
 | `-e`, `--env VAR=VALUE` | Set a guest environment variable (repeatable). |
 | `--get-chroot-cmd` | Print the fully assembled `env` + `chroot` command line and exit. |
@@ -543,23 +533,38 @@ Termux.)
 - Guest `ldconfig` is run inside the chroot to refresh the shared library
   cache after the new libraries are bind-mounted.
 
-#### Namespace isolation (`--isolated`)
+#### Namespace isolation (`--isolated` and `CD_USE_NS`)
 
 With `--isolated`, chroot-distro creates a per-container namespace holder
 (`unshare`) and runs bind mounts, special mounts, and `chroot` inside that
 environment (`nsenter`). Supported namespaces: **mount**, **PID**, **UTS**,
-and **IPC**. Isolation is **all-or-nothing**: chroot-distro probes the full
-requested namespace set first, and if any one of them is unsupported on the
-kernel it acquires none of them and falls back fully to a non-isolated
-login (with a warning naming the missing namespace), so a session is never
-left half-isolated. This is inspired by
+**IPC**, and **cgroup**. The cgroup namespace is acquired best-effort (used
+when the kernel supports it, skipped otherwise); the **mount/PID/UTS/IPC**
+set is **all-or-nothing**: chroot-distro probes that set first, and if any
+one of them is unsupported on the kernel it acquires none of them and falls
+back fully to a non-isolated login (with a warning naming the missing
+namespace), so a session is never left half-isolated. This is inspired by
 [Ubuntu-Chroot](Ubuntu-Chroot/tools/chroot.sh) and is **not** a full
 container runtime: there is no network namespace, no user namespace
 mapping, and no image layering.
 
-Do not mix `--isolated` and non-isolated logins on the same container
-without running `chroot-distro unmount <name>` first. Concurrent
-`--isolated` sessions share the same holder and mounts.
+`--isolated` couples two things: namespace isolation **and** a reduced set
+of host bind mounts (it skips the Android system/storage/`$PREFIX` binds on
+Termux, and `/tmp`/display sharing on Linux, unless re-enabled with
+`--shared-*` / `--bind`). If you want **only** the namespace isolation
+while keeping every default mount, set the `CD_USE_NS=1` environment
+variable instead: every `login`/`run` then runs in the same
+mount/PID/UTS/IPC/cgroup namespaces but with the full default mount set
+intact. `CD_USE_NS` accepts `1`/`true`/`yes`/`on`.
+
+> `CD_USE_NS` is set by the invoking user but the tool re-executes itself
+> as root; chroot-distro forwards the variable across `sudo`/`doas`/`pkexec`
+> /`su` automatically, so it keeps working even when the `sudo` line prints
+> `'-E' is ignored`.
+
+Do not mix isolated (via `--isolated` or `CD_USE_NS`) and non-isolated
+logins on the same container without running `chroot-distro unmount <name>`
+first. Concurrent isolated sessions share the same holder and mounts.
 
 #### Host bindings (Termux, default mode)
 
@@ -603,8 +608,7 @@ entries win):
    when not `--isolated` and not `--minimal`.
 4. Your `--env VAR=VALUE` entries.
 5. `HOME`, `USER`, `TERM` (default `xterm-256color`), `COLORTERM`
-   (when set on the host), and `HOSTNAME` (the `--hostname` value, else the
-   container name).
+   (when set on the host), and `HOSTNAME` (the container name).
 6. When display sharing is active (via `--shared-display`):
    `DISPLAY`, `XAUTHORITY`, `XDG_RUNTIME_DIR`, `WAYLAND_DISPLAY`,
    `XDG_SESSION_TYPE`, `XDG_CURRENT_DESKTOP`, `DESKTOP_SESSION`,
@@ -616,10 +620,11 @@ entries win):
    WSL2 — `GALLIUM_DRIVER`, `MESA_D3D12_DEFAULT_DEVICE_TYPE`,
    `LIBGL_ALWAYS_SOFTWARE`. Your `--env` entries override these.
 
-`HOSTNAME` is always set to the container name (or `--hostname`). The
-`hostname`/`uname` commands report it only under `--isolated`, where the
-UTS namespace is given a real hostname; without `--isolated` they still
-report the host's name (no UTS namespace to change).
+`HOSTNAME` is always set to the host system hostname name. The
+`hostname`/`uname` commands report it only when namespace isolation is
+active (via `--isolated` or `CD_USE_NS`), where the UTS namespace is given
+a real hostname; otherwise they still report the host's name (no UTS
+namespace to change).
 
 On Termux (unless isolated or minimal), `$PREFIX/bin` is appended to
 `PATH`. A snippet at `/etc/profile.d/termux-profile.sh` re-applies
@@ -1150,9 +1155,8 @@ paths on Linux are typically under `/root/.local/share/` and
 | `CD_DOWNLOAD_WORKERS` | Parallel registry layer downloads during `install` (default `4`, maximum `10`). Invalid values use the default; out-of-range values are clamped. |
 | `CD_DOWNLOAD_RATE_LIMIT` | Bandwidth limit for downloads (e.g., `5M` for 5 MiB/s, default `0` = unlimited). Supports suffixes `K`, `M`, `G` (case-insensitive). |
 | `CD_DOWNLOAD_MAX_RETRIES` | Maximum retry attempts per connection failure (default `3`, clamped between `0` and `20`). |
+| `CD_USE_NS` | When truthy (`1`/`true`/`yes`/`on`), every `login`/`run` uses full Linux namespace isolation (mount, PID, UTS, IPC, and cgroup when supported) **without** skipping any default bind mounts. Differs from `--isolated`, which also reduces the mount set. Forwarded across privilege elevation automatically. |
 | `CD_FORCE_NO_COLORS` | When set, disables ANSI colours in Chroot-Distro output. |
-| `CHROOT_DISTRO_NO_ELEVATE` | When set to `1`, disables privilege auto-elevation (same as `--no-elevate`). |
-| `CHROOT_DISTRO_USE_SUDO` | When set to `1`, prefer `sudo` over `su` on Termux (same as `--use-sudo`). |
 | `COLUMNS` | Fallback terminal width for `--help` rendering. |
 | `TERM`, `COLORTERM` | Inherited into the guest (always; even in `--minimal`). `TERM` defaults to `xterm-256color` when unset on the host. |
 
@@ -1180,7 +1184,7 @@ overridden from `manifest.json` image `Env`, but can be overridden with
 
 | Variable | Source / Fallback |
 |---|---|
-| `HOSTNAME` | `--hostname` value; fallback the container name. Under `--isolated` the UTS namespace hostname is also set so `hostname`/`uname -n` report it. |
+| `HOSTNAME` | The container name. Under `--isolated` the UTS namespace hostname is also set so `hostname`/`uname -n` report it. |
 
 **GPU — NVIDIA native Linux (auto-detected, non-minimal):**
 
@@ -1208,10 +1212,9 @@ Completion scripts for Bash, Zsh, and Fish live in
 - `_chroot-distro`
 - `chroot-distro.fish`
 
-They complete subcommands, global flags (`--no-elevate`, `--use-sudo`),
-and per-command options (including `login`/`run` flags such as
-`--shared-home`, `--shared-display`, `--get-chroot-cmd`, `--isolated`,
-and `--minimal`).
+They complete subcommands, global flags, and per-command options (including
+`login`/`run` flags such as `--shared-home`, `--shared-display`,
+`--get-chroot-cmd`, `--isolated`, and `--minimal`).
 
 If your shell does not pick them up automatically, install them manually:
 
@@ -1245,9 +1248,10 @@ cp src/chroot_distro/completions/chroot-distro.fish \
 - **Kernel features**: FUSE modules, real `iptables`, custom cgroup
   hierarchies, and similar kernel-module features may not work inside the
   guest.
-- **Namespaces**: `--isolated` provides mount/PID/UTS/IPC isolation via
-  `unshare`/`nsenter`, but there is no network namespace and no parity with
-  Docker or Podman.
+- **Namespaces**: `--isolated` (or `CD_USE_NS=1`) provides
+  mount/PID/UTS/IPC isolation, plus the cgroup namespace when the kernel
+  supports it, via `unshare`/`nsenter` — but there is no network namespace,
+  no user-namespace mapping, and no parity with Docker or Podman.
 - **Bind mount hygiene**: crashed sessions or orphan processes can leave
   mounts busy; `unmount` and lazy unmount mitigate this but orphaned
   processes should be cleaned up.