Skip to main content

filesystem

Read, write, edit and search files in the agent's own workdir. This is the module an app uses to work on a project: source files, config, generated output. Git-backed change tracking is the separate workspace module; shell file ops like mv/cp live in bash.

Exact tools and parameters

Ask the running system, never a list on this page: catalog.describe_module filesystem returns the real tools, every parameter (type, required, allowed values, default) and a copy-ready example, straight from the registry the compiler validates against. This page is the why and when; the catalog is the what, and it can never be out of date.

Tools, at a glance: read, write, edit, multi_edit, glob, grep, delete. (Names only - for their parameters use catalog.describe_module.)

Editing structured files (YAML / JSON)​

edit matches exactly first, with a whitespace-tolerant fallback for prose. On .yaml/.yml/.json that fuzzy fallback is off: indentation is structure, so a near-match is refused with a re-read hint rather than silently reindented into the wrong nesting. If an edit on a config file fails, re-read the lines and copy the exact text - don't rewrite the whole file.

For large JSON, prefer edit with a patch (RFC 6902) over re-emitting the document.

Mounts: a second, read-only reference folder​

config.mounts gives every agent a second root it can read but never write - reference material that ships with the app (docs, examples, a knowledge folder), kept separate from the workdir the app is actually building in.

yaml
tools:
  modules:
    filesystem:
      config:
        mounts:
          - name: knowledge
            path: knowledge   # a folder in the app's own bundle

Once declared, a plain workdir grep/glob (no mount param) automatically also searches every mount, and any hit inside a mount comes back with a mount:<name>/... prefix in its path - so you can tell a reference hit from a workdir hit and read it back by that exact path. Pass the mount param only to restrict a search to one mount. write/edit/delete inside a mount are always rejected. Full sandboxing rules: Workdir Sandbox.

A working app​

A minimal app that grants the whole filesystem surface and tells the agent how to use it. This compiles as-is. The brain uses a Digitorn gateway model (the default - no API key needed); see the note below to use your own key or a local model instead.

yaml
app:
  app_id: file_assistant
  name: File Assistant
runtime:
  entry_agent: main
agents:
  - id: main
    system_prompt: |
      You manage files in the workspace. Explore with glob and grep, read before
      you change, edit for small changes, write for new files, multi_edit for
      several spots at once, delete to remove a path.
    brain:
      provider: openai
      backend: openai_compat
      model: mimo-v2.5-free   # a model the Digitorn gateway serves
      config:
        api_key: placeholder  # ignored in gateway mode
tools:
  modules:
    filesystem: {}
  capabilities:
    grant:
      - module: filesystem
        tools: [read, write, edit, multi_edit, glob, grep, delete]