Skip to main content
During execution, your agent runs inside an isolated sandbox with a dedicated filesystem. You can read and write files using Node.js fs module — no SDK wrapper needed.

​
How It Works

Each agent execution gets its own temporary workspace. The only writable directory is /work — this is your working directory, HOME, and CWD. All other paths in the sandbox are read-only for security. Everything in /work is ephemeral — destroyed after execution ends. If you need to persist data, send it to an external API before the execution finishes.

​
Writing Files

import { createTool } from '@runflow-ai/sdk';
import { writeFile } from 'fs/promises';
import { z } from 'zod';

const generateReport = createTool({
  id: 'generate-report',
  description: 'Generate a CSV report',
  inputSchema: z.object({
    data: z.array(z.record(z.string())),
    filename: z.string(),
  }),
  execute: async (params) => {
    const headers = Object.keys(params.data[0]).join(',');
    const rows = params.data.map(row => Object.values(row).join(','));
    const csv = [headers, ...rows].join('\n');

    const path = `/work/${params.filename}`;
    await writeFile(path, csv, 'utf-8');

    return { success: true, path, rows: params.data.length };
  },
});

​
Reading Files

import { createTool } from '@runflow-ai/sdk';
import { readFile } from 'fs/promises';
import { z } from 'zod';

const readConfig = createTool({
  id: 'read-config',
  description: 'Read a configuration file',
  inputSchema: z.object({
    filename: z.string(),
  }),
  execute: async (params) => {
    const content = await readFile(`/work/${params.filename}`, 'utf-8');
    return { content };
  },
});

​
Persisting Files

Files in /work are deleted when execution ends. To keep them, send to an external service before finishing:

​
Send to External API

import { httpPost } from '@runflow-ai/sdk/http';
import { readFile, writeFile } from 'fs/promises';

await writeFile('/work/output.pdf', pdfBuffer);

const fileContent = await readFile('/work/output.pdf');
await httpPost('https://api.example.com/upload', fileContent, {
  headers: { 'Content-Type': 'application/pdf' },
});

​
Working with Binary Files

import { writeFile, readFile } from 'fs/promises';
import { httpGet } from '@runflow-ai/sdk/http';

// Download a file
const imageBuffer = await httpGet('https://example.com/image.png', {
  responseType: 'arraybuffer',
});
await writeFile('/work/image.png', Buffer.from(imageBuffer));

// Process it
const data = await readFile('/work/image.png');
// ... process the binary data

​
Temporary Files in Workflows

Workflows can pass file paths between steps: 
import { flow } from '@runflow-ai/sdk';
import { writeFile, readFile } from 'fs/promises';

const pipeline = flow('data-pipeline')
  .step('fetch', async ({ input }) => {
    const data = await fetchData(input.source);
    const path = '/work/raw-data.json';
    await writeFile(path, JSON.stringify(data));
    return { path };
  })
  .step('transform', async ({ results }) => {
    const raw = await readFile(results.fetch.path, 'utf-8');
    const data = JSON.parse(raw);
    const transformed = data.map(transform);
    const path = '/work/transformed.json';
    await writeFile(path, JSON.stringify(transformed));
    return { path, count: transformed.length };
  })
  .step('upload', async ({ results }) => {
    const content = await readFile(results.transform.path, 'utf-8');
    await httpPost('https://api.example.com/data', JSON.parse(content), {
      headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` },
    });
    return { uploaded: true };
  })
  .build();

​
Security and Limits

The sandbox is fully isolated — each execution runs in its own environment with strict constraints:
ConstraintValue
Writable directory/work only
Everything elseRead-only (agent code, system binaries, libraries)
Process userUnprivileged (no root access)
CleanupAll files deleted after execution
Never store secrets in files. Use environment variables or the Credentials module instead. Files in /work are accessible to all code running in the same execution.
The /work directory has 0777 permissions — your agent code can create, read, and write files freely within it. Trying to write anywhere else will fail with a permission error.

​
Available System Tools

The sandbox includes common utilities you can use via child_process:
  • ffmpeg / ffprobe — audio/video processing
  • python3 — Python scripts
  • node — Node.js
  • imagemagick (convert) — image manipulation
import { execSync } from 'child_process';

// Convert audio format
execSync('ffmpeg -i /work/input.ogg -ar 16000 /work/output.wav');

// Run a Python script
execSync('python3 /work/script.py');

​
Next Steps

Tools

Build tools that work with files

HTTP Utilities

Download and upload files via HTTP

Knowledge (RAG)

Upload files to knowledge bases

Media Processing

Process audio and images