File sandbox (local / MinIO / S3)

The file sandbox gives each session an isolated workspace copy. Development defaults to local; multi-instance or production should use MinIO/S3 so authoritative data lives in object storage and local disk is only a regenerable materialization mirror.

Drivers

Variable	Meaning
`AGENTFORGE_FILESANDBOX`	`local` (default) or `minio` / `s3`
`AGENTFORGE_FILESANDBOX_ROOT`	Local root; default under XDG data dir as `filesandbox`, not process cwd
`AGENTFORGE_S3_*`	endpoint, keys, bucket (default `agentforge`), path-style (default true)

flowchart TD
  Sess[Session] --> FS[File sandbox]
  FS -->|local| Disk[Local dir authoritative]
  FS -->|minio/s3| Obj[Object storage authoritative]
  Obj --> Mirror[Local mirror regenerable]

Multi-instance gate

When AGENTFORGE_MULTI_INSTANCE is true and the driver is still local, the process refuses to start. That prevents replicas from each writing their own local disk and splitting state.

Retention cleans orphan sandbox directories; see Data retention. Product positioning on “data stays in place” relates to deploying the sandbox next to the data: Data not moving.

Related reading: