Skip to main content
Version: 2026.2

File Staging

File staging exposes read-only, developer-curated sets of project files to an agent. It is a generic primitive: any agent capability can consume a file set - template generation is the first consumer, but nothing about the mechanism is template-specific.

There are two roles:

  • Developers configure file sets. A file set is a named, glob-defined list of project files (parent layouts, partials, brand docs, …), declared under pimcore_agent.file_staging. Sets are read-only - the agent never writes back to project source.
  • Agents load a set into their session. The agent calls the stage_file_set MCP tool with a set name; the bundle copies the matching files into the chat session's scratch directory, where the agent reads them with its built-in view / grep / glob tools.

How staging works​

stage_file_set resolves the named set, expands its glob patterns, applies the security filters below, and copies each accepted file into the session's staged/ directory:

/app/uploads/{chatSessionId}/staged/<path relative to project root>

The relative directory layout is preserved - a file at templates/layouts/cms.html.twig is staged at staged/templates/layouts/cms.html.twig. This keeps {% include %} / {% extends %} paths meaningful and avoids basename collisions. Every call is a full re-copy, so re-staging picks up edits to the source files.

The agent reads the staged files through the same path-sandboxed SDK file tools used for uploads - see File Attachments for the directory model and Tool Security for the sandbox.

Security model​

A configured set is fenced by two layers, both enforced at resolve time:

LayerEffect
roots allowlistA glob match is staged only if it falls under one of the configured project-relative root subtrees; matches outside every root are skipped with a warning.
denylistFilename/path patterns (.env*, *.key, *.pem, auth.json, …) are always skipped, even inside an allowed root.

Paths are resolved to their real location and confined to the project root, so symlinks cannot escape it. Staging is session-scoped: files land only in the requesting session's directory, and an agent can never reach another session's files.

Enabling it on an agent​

An agent gets file staging through its allowedFileStagingSets field. A non-empty value auto-registers the pimcore-file-staging MCP group (which provides stage_file_set) and restricts the agent to exactly the listed sets

  • no separate pimcoreMcpServers entry is needed.

staged/ also holds Pimcore asset copies pulled in by stage_asset, and uploaded/ holds user uploads. All three sources share one path sandbox.

Further reading​