Skip to content

All posts

KubernetesAI

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

Ritesh Patel

Kubernetes: 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

  1. Add one emptyDir entry to spec.volumes for 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.
  2. Mount each volume in the agent container under volumeMounts, at the path the agent writes to.
  3. Set readOnlyRootFilesystem: true in the container’s securityContext.
  4. Set sizeLimit on 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: true on 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.name is windows, 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.

Ritesh Patel, Founder & VP Product, Nirmata

Ritesh Patel is a founder of Nirmata and leads its products. He writes about governing AI coding agents, MCP security and Kubernetes policy as code.

LinkedIn

Govern AI agents with AIControlsControl what AI agents do, and prove it.
Share

Stay up-to-date with the latest in AI, governance, and infrastructure

Subscribe to our free monthly newsletter to get industry news, DevOps tips, and articles right to your inbox on Kyverno, containerization, Kubernetes deployment & management and more.