docs: clarify Docker-in-LXC security boundary

Author: terion-labs

docs/architecture.md

@@ -188,6 +188,12 @@ Baseline `default` and `terrarium` profile behavior:
 - root disk on the Terrarium pool
 - NIC attached to `terrarium-ovn`
 
+Terrarium does not make ordinary workload containers privileged. The isolated
+ID map means container root, including root inside a Docker daemon nested in the
+container, is still separated from host root by LXC's user-namespace boundary.
+That gives Docker-heavy deployments a host protection layer they would not get
+from running all Docker workloads directly on the VPS.
+
 This is an intentional product choice: Terrarium optimizes for isolated environments that can still run realistic developer and agent workloads, including Docker Compose stacks, instead of optimizing for the narrowest possible LXC feature surface.
 
 The `strict` profile keeps the Terrarium root disk and OVN NIC but omits

docs/guides/compose.md

@@ -8,6 +8,7 @@ This is especially useful for complex projects that want their own dependencies,
 
 Terrarium's LXD `default` profile enables the settings that Docker-in-LXC usually needs:
 
+- `security.idmap.isolated=true`
 - `security.nesting=true`
 - `security.syscalls.intercept.mknod=true`
 - `security.syscalls.intercept.setxattr=true`
@@ -38,6 +39,16 @@ Terrarium gives each Compose deployment its own boundary:
 
 The stack lives in an LXC container instead of directly on the host. If the workload is compromised or misconfigured, the host is still a separate layer with a smaller blast radius.
 
+Terrarium's normal workload containers are unprivileged and use isolated ID
+maps. That means root inside the LXC, and root inside Docker containers created
+by the nested Docker daemon, does not become host root. This is especially
+useful for Compose stacks copied from the internet or built by app installers
+that assume broad Docker access.
+
+This is still a boundary, not a permission to be careless. Avoid `privileged:
+true`, broad host bind mounts, host networking, and public admin panels unless
+the app genuinely needs them and you understand the risk.
+
 ### Isolation
 
 Each Compose stack gets its own filesystem, packages, images, volumes, and daemon state. That makes it much easier to keep multiple projects on one VPS without constant interference.

docs/guides/coolify.md

@@ -15,6 +15,11 @@ That gives Coolify the SSH-managed server model it expects, while Terrarium
 keeps Docker off the host and gives you LXD isolation, OVN networking, and ZFS
 snapshots around each Docker host.
 
+The Coolify servers are unprivileged LXC containers by default. Root inside
+those containers, including root inside Docker workloads launched by Coolify, is
+not host root, so Docker misconfiguration has one more containment layer before
+it reaches the Terrarium host.
+
 ## When to use this instead of plain Compose
 
 Use [Isolated Docker Compose deployments](./compose) when you want one stack in

docs/guides/dokploy.md

@@ -11,6 +11,11 @@ On Terrarium, the clean model is:
 
 That means Dokploy gets the server model it expects, while Terrarium still gives you LXD isolation and ZFS snapshots around each Docker host.
 
+Those Docker hosts are unprivileged LXC containers by default. Root inside the
+deployment-server container, including root inside Docker workloads launched by
+Dokploy, is mapped away from host root, which adds a useful host-side safety
+layer for Docker deployments with imperfect defaults.
+
 ## When to use this instead of plain Compose
 
 Use [Isolated Docker Compose deployments](./compose) when you want one app stack in one container and you are comfortable managing Compose files yourself.

docs/security.md

@@ -5,6 +5,7 @@ Terrarium is designed to make the safe path feel natural, especially for people
 The short version:
 
 - containers are private by default
+- workload containers are unprivileged LXC by default
 - the host is hardened
 - public exposure is explicit
 - a built-in time machine is part of the default storage model
@@ -85,8 +86,17 @@ lxc launch images:ubuntu/24.04 devbox
 The compatibility alias `terrarium` has the same settings, so older commands
 that pass `--profile terrarium` still work.
 
+Terrarium workload containers are unprivileged LXC containers by default. The
+profiles use isolated ID maps, so root inside the container is not host root.
+When you run Docker inside one of these containers, Docker still needs
+Docker-friendly LXC features, but the nested Docker daemon and its containers
+sit behind the extra LXC user-namespace boundary instead of running directly on
+the host. That is a useful additional layer against badly configured Docker
+deployments.
+
 The baseline `default` and `terrarium` profiles include:
 
+- `security.idmap.isolated=true`
 - `security.nesting=true`
 - `security.syscalls.intercept.mknod=true`
 - `security.syscalls.intercept.setxattr=true`
@@ -101,6 +111,8 @@ Tradeoff:
 
 - this is more permissive than a minimal non-nested container profile
 - it is a convenience and compatibility choice, not the narrowest possible baseline
+- it does not make broad Docker privileges, unsafe host bind mounts, or exposed
+  app admin panels safe
 
 Terrarium also creates a `strict` profile for workloads that should not need
 nested container runtimes: