Skip to main content
Four nodes give workflows (and AI agents) a filesystem: File Read, File Modify, FS Search, and Shell. All four operate inside the workflow’s own workspace folder and double as agent tools (file_read, file_modify, fs_search, shell_execute) when connected to an AI Agent’s tools input.
These nodes touch real files on disk — everything inside the workflow’s workspace folder is genuinely created, overwritten, edited, and deleted. The sandbox confines paths to the workspace; it does not undo anything.

​
Where files live

Each workflow gets a persistent workspace directory at <DATA_DIR>/workspaces/<workflow_slug>/ — by default ~/.opencompany/workspaces/<workflow_slug>/. The directory is created automatically on first use and persists across runs, so files written in one execution are readable in the next. Every path you pass is interpreted relative to that workspace root:
  • Absolute anchors are stripped — /reports/data.csv, C:\reports\data.csv, and UNC paths all resolve to reports/data.csv inside the workspace.
  • Traversal is rejected — paths containing .. or ~ fail with a clear error telling you to use a workspace-relative path.
  • path: "." in FS Search means the workspace root, not the server’s working directory.
Other nodes share the same folder: code executors receive it as workspace_dir, and the File Downloader saves into it — so a file another node produced is immediately visible here.

​
File Read

Reads a text file from the workspace.

​
Parameters

​
string
required
File path relative to the workspace root
​
number
default:"0"
0-indexed starting line
​
number
default:"2000"
Maximum lines to read (1-10000)

​
Output

Missing files, directories passed as file_path, and paths escaping the workspace all fail with a clean, actionable error. Binary files are not supported — the node reads text.

​
File Modify

Creates, overwrites, or edits a file. Two operations:

​
Parameters

​
select
default:"write"
write (create or overwrite) or edit (string find-and-replace)
​
string
required
Target file path
​
string
File content (required for write)
​
string
Text to find (required for edit)
​
string
Replacement text (edit)
​
boolean
default:"false"
Replace every occurrence. When false, old_string must appear exactly once in the file — zero or multiple matches fail the edit.

​
Output

Write:
Edit:
write always overwrites — there is no “fail if exists” flag. An existing file at the target path is replaced wholesale. And replace_all with an empty New String deletes every occurrence of Old String, with no safeguard.
Three query modes over the workspace, selected by Mode:

​
Parameters

​
select
default:"ls"
ls (list a directory), glob (find files by pattern), or grep (search file contents by regex)
​
string
default:"."
Directory to search in, workspace-relative
​
string
Glob pattern (glob mode, e.g. **/*.md) or regex (grep mode). Required for both; unused by ls.

​
Output

** globs work. There is no result cap — a **/* glob over a huge workspace returns every match, so keep patterns specific.

​
Shell

Runs a short-lived shell command inside the workspace. The command grammar is Nushell (nu), chosen so commands behave identically on Windows, macOS, and Linux — common file operations (ls, cp, mv, mkdir, rm, open) are Nushell builtins. When nu is not installed, the node falls back to the system shell. The environment is inherited from the server, so external tools on your PATH — npm, node, python, git — are reachable.

​
Parameters

​
string
required
Nushell command to run
​
number
default:"30"
Maximum seconds (1-600). On timeout the process is killed and exit_code is 124.

​
Nushell is not bash

  • && and || are rejected up-front with a corrective error — use ; for sequencing or try { ... } catch { ... } for error handling.
  • $VAR, backticks, and > redirection differ from bash. Nushell has its own idioms for each.

​
Output

Notes on the payload:
  • stdout combines the command’s output (stderr lines are prefixed [stderr]) and is stripped of ANSI colour codes.
  • A non-zero exit_code still counts as a successful node run — the node reports that the command finished, not that it succeeded. Branch on exit_code downstream.
  • exit_code: 124 means the command hit Timeout and was killed.
  • Very long output is capped, with truncated: true set.
  • Stdin is empty — upstream input_data does not reach the command. Write inputs to a file first if a command needs them.
For long-running processes (dev servers, watchers), use the Process Manager node instead — Shell kills its command at Timeout.

​
Example: summarize new files on a schedule

Periodically check the workspace for reports and have an agent summarize what is there:
  1. Cron Scheduler — e.g. every hour.
  2. FS Search — Mode: glob, Path: ., Pattern: reports/**/*.md.
  3. AI Agent — prompt: “Here is a file listing from the workspace. Note any files added since your last summary and describe what the folder contains.” Connect File Read to the agent’s tools input so it can open files it finds interesting.
  4. Console — shows the summary each run.
This is polling: the schedule re-lists matching files on every tick, and the agent compares against what it saw before. There is no filesystem watch trigger — a file appearing between ticks is picked up on the next run, not instantly.

​
Tips

Give an agent all four nodes as tools and it can manage the workspace end-to-end: fs_search to explore, file_read to inspect, file_modify to write, shell_execute to run tools against the results.
Not sure what exists? Run FS Search with Mode ls first — the error messages for bad paths also point you there.
Prefer File Modify’s edit with a unique Old String over rewriting whole files — the uniqueness check catches accidental multi-replacements before they happen.
Shell’s exit_code is where failures live. A failing command does not fail the node — check exit_code != 0 in downstream logic.

Code Executors

Transform file contents with Python, JS, or TS

Schedulers & Triggers

Poll the workspace on a schedule

AI Agents

Let agents read, write, and search files as tools

Document Processing

Download and parse documents into the workspace