Read-Only Root Filesystem

A read-only root filesystem is a container or system configuration in which the root filesystem, the base set of directories and files the operating system and applications run from, cannot be written to at runtime. Any process running inside such a container can read the files it needs to execute, but cannot modify, delete, or add files to the underlying image.

How it works

In Docker and similar container runtimes, this is typically set with a flag, such as Docker's read-only mode, that mounts the container's root filesystem as read-only at startup. Applications that genuinely need to write data, such as temporary files or logs, are given specific writable mounts, often backed by tmpfs or a scoped volume, rather than write access to the entire filesystem. Everything outside those explicit writable paths is immutable for the life of the container.

Why it matters for AI agents

An agent that can execute shell commands or write files as part of its normal operation is also, by the same mechanism, capable of modifying its own runtime environment: installing a persistence mechanism, altering a script it will later execute, or overwriting a binary the container depends on. A read-only root filesystem removes that entire class of action by making it structurally impossible, rather than relying on the agent to simply choose not to do it. It also limits the practical impact of a compromised agent process, since even if an attacker gains code execution inside the container, they cannot persist changes to the filesystem, and a fresh container start returns to a known-good state.

Benefits beyond security

• Predictability: a container behaves the same way every time it starts, since its filesystem cannot drift from the built image
• Easier debugging: file changes during an incident are limited to the explicitly writable paths, narrowing where to look
• Simpler recovery: restarting the container discards any unauthorized modifications automatically

Agenhood's implementation

Agenhood runs every agent container with a read-only root filesystem as one layer of its container sandbox, alongside a reduced set of Linux capabilities and CPU and memory limits. Combined with egress filtering, this means an agent cannot tamper with its own execution environment even if it is coerced into running unexpected commands.