filesystem

The filesystem block declares what the agent's virtual filesystem contains. It is optional. When it is omitted, the agent has a single in-memory filesystem mounted at /, which is the same as writing:

filesystem {
  mounts = [
    {
      path = "/"
      backend = { kind = "memory" }
    }
  ]
}

Fields

Mounts

Each mount has two fields:

Later entries win. If two mounts target the same path, the later one replaces the earlier one.

Backends

Every backend object has a kind field written in snake case.

memory

A memory backend starts empty and exists only for the lifetime of the process.

filesystem {
  mounts = [
    {
      path = "/"
      backend = { kind = "memory" }
    }
  ]
}

This backend has no additional fields.

host

A host backend exposes a real host directory inside the virtual filesystem.

filesystem {
  mounts = [
    {
      path = "/workspace"
      backend = {
        kind = "host"
        root = "./workspace"
      }
    }
  ]
}

Nothing above root is reachable.

read_only

A read_only backend wraps another backend and refuses every write through it.

filesystem {
  mounts = [
    {
      path = "/reference"
      backend = {
        kind = "read_only"
        inner = {
          kind = "host"
          root = "./reference"
        }
      }
    }
  ]
}

overlay

An overlay backend reads from an upper backend first and falls through to a lower backend. Writes go to the upper backend.

filesystem {
  mounts = [
    {
      path = "/workspace"
      backend = {
        kind = "overlay"
        upper = { kind = "memory" }
        lower = {
          kind = "read_only"
          inner = {
            kind = "host"
            root = "./workspace"
          }
        }
      }
    }
  ]
}

read_only and overlay both nest backends rather than paths, so any composition is expressible.

Precedence

Three sources compose into the final filesystem view, and a later registration at the same path wins:

1. Mounts contributed at compile time.
2. The manifest's mounts.
3. The operator's binds.

Operator binds

The topology is otherwise fixed when the agent is compiled. Operator binds are the runtime-adjustable part.

See agentc:fs for what component code sees and Give your agent a filesystem for the step-by-step recipe.