How to make an AI agent container's root filesystem read-only

Set readOnlyRootFilesystem: true in the agent container’s securityContext, so the image’s root filesystem is mounted read-only. Then mount an emptyDir volume at each path the agent must write to, such as a scratch directory or a cache. The field defaults to false, so a container without it stays writable.
What the field does and what it leaves writable
The Kubernetes security context page lists readOnlyRootFilesystem among the container security settings and describes it as mounting the container’s root filesystem as read-only. The Pod API reference gives the field path as spec.containers[*].securityContext.readOnlyRootFilesystem, a boolean that defaults to false. It also says the field cannot be set when spec.os.name is windows.
The field covers the root filesystem and nothing else. The volumes page says a mount can be made read-only with volumeMounts[*].readOnly, which is a separate setting. A volume mounted without that flag stays writable even when the root filesystem is locked. An agent that writes to /tmp therefore needs a volume at /tmp. The rest of the image stays fixed.
Find the paths the agent must write
The Kubernetes docs do not list the paths an agent needs, because that depends on the agent’s image and tools. Find them by running the agent with the field set, in a test namespace, and reading the errors. Each failed write names a path. Most agents need a small set of paths, and the table below shows the common kinds.
| Path (example) | What the agent writes there | Volume |
|---|---|---|
/tmp |
Temporary files from the runtime and from tools | emptyDir |
/work |
Files the agent creates or edits for a task | emptyDir |
/home/agent/.cache |
Tool and package caches | emptyDir |
Start with the agent’s first task, then widen the test to every tool it can call, because a rarely used tool may write somewhere the first run never touches. Keep the list short. Each path you add is a place the agent can write to, so a mount on the whole root filesystem undoes the setting. If the agent writes log files, give them a path as well, and test that the logs are still readable after a run.
Mount each writable path as an emptyDir
- Add one
emptyDirentry tospec.volumesfor each path. The volumes page describes an emptyDir as empty scratch space that starts empty when the Pod is assigned to a node and is deleted when the Pod is removed from that node. - Mount each volume in the agent container under
volumeMounts, at the path the agent writes to. - Set
readOnlyRootFilesystem: truein the container’ssecurityContext. - Set
sizeLimiton each emptyDir. The volumes page says there is no limit on space used by default, so the field is the only cap you get.
A pod manifest with a read-only root filesystem
The manifest below uses the restricted fields from the Pod Security Standards page: runAsNonRoot, seccompProfile, allowPrivilegeEscalation: false and dropping all capabilities. It adds readOnlyRootFilesystem: true and three emptyDir mounts. The image name is an example, and the sizes are examples too. Set them from what your agent writes. The field paths and behaviour are checked against the Kubernetes v1.37 documentation as of 2026-11-20.
apiVersion: v1
kind: Pod
metadata:
name: agent-readonly
namespace: my-agents
spec:
securityContext:
runAsNonRoot: true
runAsUser: 10001
seccompProfile:
type: RuntimeDefault
containers:
- name: agent
image: ghcr.io/example/agent:1.0.0
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop:
- ALL
volumeMounts:
- name: tmp
mountPath: /tmp
- name: work
mountPath: /work
- name: cache
mountPath: /home/agent/.cache
volumes:
- name: tmp
emptyDir:
sizeLimit: 512Mi
- name: work
emptyDir:
sizeLimit: 2Gi
- name: cache
emptyDir:
sizeLimit: 1Gi
Check that the root filesystem rejects writes
Apply the manifest and open a shell in the container. The security context page uses the same two steps for its example Pod. Then test one write to a path the agent user can normally write, such as its home directory, and one write to a mounted emptyDir. The first should fail with a read-only error. The second should succeed.
kubectl apply -f agent-readonly.yaml
kubectl exec -it agent-readonly -n my-agents -- sh
# inside the container:
touch /home/agent/readonly-test # expected to fail: read-only file system
touch /work/writable-test # expected to succeed
Confirm the exact error text on your cluster. It depends on the container runtime. If the write to the home directory succeeds, the field is not set on the container you think it is, so recheck the manifest before going further. Then run one full agent task, because a write that only happens later in a run would otherwise fail in production.
Pod Security Standards does not require this field
The restricted Pod Security Standard lists the settings a pod must set. It covers privilege escalation, running as non-root, seccomp, dropping capabilities and the allowed volume types. It does not list readOnlyRootFilesystem. A pod can pass restricted with a writable root filesystem, so the field needs its own check in your agent manifests. Review it in the same pass as the restricted fields, and record the reason whenever an agent container leaves it unset.
The volume types matter for the writable paths. Restricted allows several volume sources, including emptyDir and persistentVolumeClaim. Baseline forbids hostPath volumes, so agent scratch space should not use one, whatever the level you choose.
| Volume source | Allowed by restricted | Use for agent writes |
|---|---|---|
emptyDir |
Yes | Scratch paths and caches that can be discarded |
persistentVolumeClaim |
Yes | Data that must outlive the pod, which needs its own review |
hostPath |
No (forbidden at baseline) | Not for agent workloads |
For the wider level choice, see Pod Security Admission levels for AI agent workloads.
Fine print that changes the result
- Unset means writable. A container that omits the field, or sets it to false, has a writable root filesystem. Set it explicitly in every agent container, including init containers, so the manifest states the intent.
- Mounts stay writable. A volume without
readOnly: trueon its mount is writable, whatever the root setting says. - No default size limit. An emptyDir can use as much local storage as the node allows unless you set
sizeLimit. - Windows is excluded. The API reference says the field cannot be set when
spec.os.nameiswindows, so this recipe applies to Linux pods only. Check the OS field in the pod spec before you apply it to a mixed cluster.
Where this check sits in an agent control set
A read-only root filesystem limits what a compromised or misbehaving agent can change inside its container. It does not limit what the agent can reach over the network or with its service account token, so those need their own controls. Pair it with the seccomp profile and the sandboxing approach in this series, and see the governing AI agents hub for the wider set of controls.
This post names no product for this control. If you want to compare how a policy engine checks pod fields with Pod Security Admission, the Kyverno open-source page describes that project. This post makes no claim about any product’s support for the readOnlyRootFilesystem field.
Frequently asked questions
Does readOnlyRootFilesystem stop an agent from writing files?
It stops writes to the container's root filesystem only. A volume mounted into the container stays writable unless its volumeMounts entry sets readOnly: true. That is the design you want: the image stays fixed, and the agent writes only to the paths you mount as emptyDir. Check that every mount is one the agent actually needs.
Does Pod Security Standards restricted require a read-only root filesystem?
No. The restricted page lists required settings such as runAsNonRoot, allowPrivilegeEscalation set to false, a seccompProfile, and dropping all capabilities. readOnlyRootFilesystem is not in that list. A pod can pass restricted with a writable root filesystem, so set the field yourself and review it in agent manifests.
Why does my agent fail once readOnlyRootFilesystem is true?
Usually it writes to a path that has no volume mounted. Read the error, which names the path, then add an emptyDir mount at that path and run the agent again. Tool caches and temporary files are the usual cause. Test a full task run, not just the start-up, because some writes happen later in the run.
Does an emptyDir survive a container restart in the same pod?
The volumes page says 'For any kind of volume in a given Pod, data is preserved across container restarts' (https://kubernetes.io/docs/concepts/storage/volumes/). The same page says an emptyDir is deleted when its Pod is removed from the node. Test a restart on your cluster before your agent depends on files surviving one.
Is there a default size limit on an emptyDir?
The volumes page says there is no limit on how much space an emptyDir can consume, and no isolation between containers or Pods. Measure scratch use during a full task run, so one runaway task cannot fill the node's disk unnoticed.