Sandbox Filesystem Tool Implementation Guide

Overview

You are building @loopstack/sandbox-filesystem, a Loopstack tool that provides secure, controlled filesystem operations within Docker sandbox environments. This tool enables workflows to read, write, list, and manage files and directories in isolated containers.

What to Build

Create a NestJS injectable tool class that extends ToolBase and provides filesystem operations executed within sandbox containers using @loopstack/sandbox-tool.

Core Operations Required

1. Read File - Read complete file contents from a specified path
2. Write File - Write content to a file, creating parent directories if needed
3. List Directory - List files and subdirectories with metadata
4. Create Directory - Create directories with recursive parent creation
5. Delete File/Directory - Remove files or directories
6. Check Existence - Verify if a file or directory exists
7. Get File Info - Retrieve metadata (size, type, timestamps)

Tool Arguments Schema

Define a Zod schema with the following structure:

typescript
1const sandboxFilesystemSchema = z.object({
2  operation: z.enum(['read', 'write', 'list', 'createDir', 'delete', 'exists', 'info']),
3  path: z.string().describe('Target filesystem path within sandbox'),
4  content: z.string().optional().describe('Content to write (for write operation)'),
5  encoding: z.string().default('utf-8').optional().describe('Character encoding'),
6  recursive: z.boolean().default(false).optional().describe('Enable recursive operations'),
7  force: z.boolean().default(false).optional().describe('Force overwrite or deletion'),
8});
9
10type SandboxFilesystemArgs = z.infer<typeof sandboxFilesystemSchema>;

Implementation Structure

typescript
1import { Injectable } from '@nestjs/common';
2import { z } from 'zod';
3import { ToolBase } from '@loopstack/core';
4import { BlockConfig, ToolResult, WithArguments } from '@loopstack/common';
5
6@Injectable()
7@BlockConfig({
8  config: {
9    description: 'Secure filesystem operations within Docker sandbox environments',
10  },
11})
12@WithArguments(sandboxFilesystemSchema)
13export class SandboxFilesystemTool extends ToolBase<SandboxFilesystemArgs> {
14  
15  async execute(args: SandboxFilesystemArgs): Promise<ToolResult<any>> {
16    // 1. Validate path for security (no ../ traversal)
17    // 2. Normalize path
18    // 3. Execute operation based on args.operation
19    // 4. Return structured result with success, data, metadata
20  }
21}

Tool Result Structure

Return a ToolResult with this structure:

typescript
1{
2  data: {
3    success: boolean,
4    data: any,              // Operation-specific payload
5    error?: string,         // Error message if failed
6    metadata?: {            // Additional context
7      bytesWritten?: number,
8      itemsCount?: number,
9      // etc.
10    }
11  }
12}

Security Requirements

Path Validation

• CRITICAL: Block path traversal attacks by rejecting paths containing ../
• Normalize all paths before execution
• Restrict access to sandbox-designated directories only
• Never allow access to system directories like /etc, /sys, /proc

Resource Limits

• Enforce maxFileSize configuration (suggest default: 10MB)
• Implement operation timeouts (suggest default: 5000ms)
• Limit recursive depth to prevent infinite loops (suggest max: 10 levels)

Error Handling

• Sanitize error messages to prevent information leakage
• Provide generic errors to users, detailed logs internally
• Fail safely on permission errors

Configuration Options

Support these configuration properties in the tool:

typescript
1interface SandboxFilesystemConfig {
2  defaultEncoding?: string;      // Default: 'utf-8'
3  maxFileSize?: number;          // Default: 10485760 (10MB)
4  allowedPaths?: string[];       // Whitelist of accessible paths
5  timeoutMs?: number;            // Default: 5000
6}

Usage Examples

Example 1: Read a Configuration File

yaml
1transitions:
2  - id: read_config
3    from: start
4    to: process
5    call:
6      - tool: sandboxFilesystem
7        args:
8          operation: 'read'
9          path: '/workspace/config.json'
10          encoding: 'utf-8'
11        assign:
12          configData: ${ result.data.data }

Example 2: Write Generated Code

yaml
1transitions:
2  - id: save_output
3    from: generate
4    to: end
5    call:
6      - tool: sandboxFilesystem
7        args:
8          operation: 'write'
9          path: '/workspace/output/generated.ts'
10          content: ${ generatedCode }
11          recursive: true
12        assign:
13          writeResult: ${ result.data }

Example 3: List Directory Contents

yaml
1transitions:
2  - id: list_files
3    from: start
4    to: process
5    call:
6      - tool: sandboxFilesystem
7        args:
8          operation: 'list'
9          path: '/workspace/data'
10          recursive: false
11        assign:
12          fileList: ${ result.data.data }

Example 4: Check File Existence Before Processing

yaml
1transitions:
2  - id: check_and_process
3    from: start
4    to: process
5    call:
6      - tool: sandboxFilesystem
7        args:
8          operation: 'exists'
9          path: '/workspace/input.txt'
10        assign:
11          fileExists: ${ result.data.data }

Dependencies

Ensure these packages are installed:

json
1{
2  "dependencies": {
3    "@loopstack/sandbox-tool": "latest",
4    "@loopstack/core": "latest",
5    "@loopstack/common": "latest",
6    "@nestjs/common": "^10.0.0",
7    "zod": "^3.22.0"
8  }
9}

Module Registration

Register the tool in your NestJS module:

typescript
1import { Module } from '@nestjs/common';
2import { SandboxFilesystemTool } from './sandbox-filesystem.tool';
3
4@Module({
5  providers: [SandboxFilesystemTool],
6  exports: [SandboxFilesystemTool],
7})
8export class SandboxFilesystemModule {}

Troubleshooting

"Path traversal detected" Error

• Ensure paths don't contain ../ sequences
• Use absolute paths starting with /workspace/ or configured allowed paths
• Normalize paths before validation

"File size exceeds maximum" Error

• Check maxFileSize configuration
• For large files, consider streaming or chunked operations
• Increase limit if appropriate for your use case

"Operation timeout" Error

• Verify sandbox container is running and accessible
• Check network connectivity to Docker environment
• Increase timeoutMs configuration for slow filesystems

Permission Denied Errors

• Verify Docker volume mounts are configured correctly
• Ensure sandbox container has appropriate user permissions
• Check that target paths are within allowed sandbox boundaries

Binary vs Text File Handling

• Use appropriate encoding: 'utf-8' for text, 'binary' or 'base64' for binary files
• Specify encoding explicitly in arguments to avoid corruption
• Consider file type when reading/writing

Best Practices

1. Always validate paths before executing operations
2. Use recursive: true only when necessary to avoid performance issues
3. Set appropriate timeouts based on expected file sizes
4. Handle errors gracefully in workflows with fallback transitions
5. Log operations for audit trails and debugging
6. Test in sandbox before production deployment
7. Limit file sizes to prevent resource exhaustion