Skip to content
Build Perch
Browse documentation

Scoped folders

Short answer: Scoped folders let you confine an agent or workflow step so it can read only from one folder (or file) and write only to another. It’s fail-closed, meaning a confined run can only get narrower, never wider than the workspace it’s already sandboxed to. It’s opt-in per agent and per workflow step; nothing is confined by default.

What are scoped folders?

Every AI run in Build Perch is already sandboxed to its workspace: nothing an agent or workflow does can read or write outside it. Scoped folders add a second, tighter boundary on top of that: pick an input folder (or a specific input file) a run may read from, and an output folder (or a specific output file) it may write to. When that’s turned on, every file tool the run has (read, write, edit, move, delete, even semantic search results) is confined to those folders; the app itself enforces this on every file tool call.

For an agent, this is an editor checkbox, “Confine this agent to the folders above”, off by default; setting input/output folders alone doesn’t confine the agent until you check it. Turn it on and each folder that’s set becomes a hard boundary; a blank folder leaves that direction unrestricted.

For a workflow, scope is set per step: each step can have its own “read only from this folder” and “write only to this folder.” Setting a folder is the opt-in; there’s no separate checkbox. When a step delegates to a saved agent, the step’s scope and the agent’s own scope combine as the intersection of the two: a step can never widen what the agent it’s running is allowed to touch; if the two scopes don’t overlap, the step fails rather than silently falling back to the wider one.

A step (or an agent) can also pin a single input file instead of a folder: the file’s content is automatically read and handed to the run as part of its instructions, so it doesn’t need a separate read step.

How do I confine an agent or workflow step?

  1. Agent: in the Agent editor, set an input folder and/or output folder, then check “Confine this agent to the folders above.” Save.
  2. Workflow step: in the step editor’s scope section, choose a folder in the “read only from this folder” dropdown and/or the “write only to this folder” dropdown, or pin a specific input file instead.
  3. Run the agent or workflow as usual. A read or write outside the confined folder is refused, not silently redirected.

Good to know

  • Confinement can only narrow: it stacks on top of the always-on workspace sandbox, never replaces or widens it. There’s no way for a run (or the AI itself) to point an automation outside the active workspace.
  • The intersection rule applies to workflow steps that call a saved agent: the effective scope is always the tighter of the step’s folders and the agent’s own folders.
  • Locked folders (right-click → Lock from AI) stay off-limits to every run regardless of scope settings. See Locking folders from the AI.
  • Reverting a run’s changes afterward (see Run history and revert) is your action; the run’s scope doesn’t apply to it.
  • If the AI tries to author a scope folder outside the workspace (via create_agent or create_workflow), it’s rejected the same way any other out-of-workspace path is.