File Operations

The Sandbox provides comprehensive file system operations for managing files and directories within your isolated environment.

Base Endpoint

All file operations use the /files endpoint:

POST https://sandbox.oblien.com:55872/files/{operation}

Core Operations

List Files

List files and directories in a path.

// Using SDK
const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: false,
  includeHidden: false
});

POST /files/list HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "dirPath": "/opt/app"
}

Response:

{
  "success": true,
  "files": [
    {
      "name": "src",
      "path": "/opt/app/src",
      "type": "directory",
      "size": 4096,
      "modified": "2025-10-16T10:30:00Z"
    },
    {
      "name": "package.json",
      "path": "/opt/app/package.json",
      "type": "file",
      "size": 512,
      "modified": "2025-10-16T10:25:00Z"
    }
  ],
  "path": "/opt/app"
}

Parameters:

Parameter	Type	Required	Description
`dirPath`	string	Yes	Path to directory to list
`recursive`	boolean	No	Include subdirectories
`includeHidden`	boolean	No	Include hidden files (starting with .)

Get File Content

Read the contents of a file.

// Using SDK
const result = await sandbox.files.get({
  filePath: '/opt/app/src/index.js',
  range: { start: 1, end: 50 },
  withLineNumbers: true
});

POST /files/get HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "filePath": "/opt/app/src/index.js",
  "range": { "start": 1, "end": 50 },
  "withLineNumbers": true
}

Response:

{
  "success": true,
  "content": "import express from 'express';\n\nconst app = express();",
  "path": "/opt/app/src/index.js",
  "size": 1245,
  "lines": 42
}

Parameters:

Parameter	Type	Required	Description
`filePath`	string	Yes	Full path to file
`range`	object	No	Line range `{start, end}`
`withLineNumbers`	boolean	No	Include line numbers in output

Create File or Directory

Create a new file or directory.

// Using SDK - Create file
await sandbox.files.create({
  filePath: '/opt/app/newfile.js',
  content: 'console.log("New file");',
  isFolder: false
});

// Create directory
await sandbox.files.create({
  filePath: '/opt/app/newfolder',
  isFolder: true
});

POST /files/create HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "filePath": "/opt/app/newfile.js",
  "content": "console.log(\"New file\");",
  "isFolder": false
}

Response:

{
  "success": true,
  "message": "File created successfully",
  "path": "/opt/app/newfile.js"
}

Parameters:

Parameter	Type	Required	Description
`filePath`	string	Yes	Full path for new file/directory
`content`	string	No	File content (only for files)
`isFolder`	boolean	No	Create directory instead of file
`withWatcher`	boolean	No	Trigger file watcher (default: true)

Delete File or Directory

Delete a file or directory.

// Using SDK
await sandbox.files.delete({
  filePath: '/opt/app/oldfile.js'
});

POST /files/delete HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "filePath": "/opt/app/oldfile.js"
}

Response:

HTTP/1.1 204 No Content

Or on error:

{
  "success": false,
  "error": "File not found"
}

Parameters:

Parameter	Type	Required	Description
`filePath`	string	Yes	Path to file/directory to delete
`withWatcher`	boolean	No	Trigger file watcher (default: true)

Rename/Move File

Rename or move a file or directory.

// Using SDK
await sandbox.files.rename({
  sourcePath: '/opt/app/old-name.js',
  destinationPath: '/opt/app/new-name.js'
});

POST /files/rename HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "sourcePath": "/opt/app/old-name.js",
  "destinationPath": "/opt/app/new-name.js"
}

Response:

{
  "success": true,
  "message": "File renamed successfully",
  "from": "/opt/app/old-name.js",
  "to": "/opt/app/new-name.js"
}

Parameters:

Parameter	Type	Required	Description
`sourcePath`	string	Yes	Current path
`destinationPath`	string	Yes	New path
`withWatcher`	boolean	No	Trigger file watcher (default: true)

Edit File

Replace file content or perform advanced edits.

// Using SDK
await sandbox.files.edit({
  filePath: '/opt/app/config.json',
  content: JSON.stringify({ port: 3000, env: 'production' }, null, 2)
});

POST /files/edit HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "filePath": "/opt/app/config.json",
  "content": "{\n  \"port\": 3000,\n  \"env\": \"production\"\n}"
}

Response:

{
  "success": true,
  "message": "File edited successfully",
  "path": "/opt/app/config.json"
}

Parameters:

Parameter	Type	Required	Description
`filePath`	string	Yes	Path to file to edit
`content`	string	Yes	New file content
`withWatcher`	boolean	No	Trigger file watcher (default: true)

Merge File Changes

Intelligently merge content into a file.

// Using SDK
await sandbox.files.merge({
  filePath: '/opt/app/README.md',
  content: '## New Section\n\nAdditional content',
  options: {
    strategy: 'append', // or 'prepend', 'replace'
    silent: false
  }
});

POST /files/merge HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "filePath": "/opt/app/README.md",
  "content": "## New Section\n\nAdditional content",
  "options": {
    "strategy": "append"
  }
}

Response:

{
  "success": true,
  "message": "File merged successfully",
  "path": "/opt/app/README.md",
  "linesAdded": 3
}

Parameters:

Parameter	Type	Required	Description
`filePath`	string	Yes	Path to file
`content`	string	Yes	Content to merge
`options`	object	No	Merge options
`options.strategy`	string	No	`append`, `prepend`, or `replace`
`options.silent`	boolean	No	Don't trigger file watcher

Check File Exists

Check if a file or directory exists.

// Using SDK
const exists = await sandbox.files.exists({
  filePath: '/opt/app/package.json'
});

if (exists.exists) {
  console.log('File exists!');
}

POST /files/exists HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "filePath": "/opt/app/package.json"
}

Response:

{
  "success": true,
  "exists": true,
  "path": "/opt/app/package.json",
  "type": "file"
}

Upload File

Upload file content (useful for binary files or large files).

// Using SDK
await sandbox.files.upload({
  filePath: '/opt/app/image.png',
  content: base64EncodedContent
});

POST /files/upload HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "filePath": "/opt/app/image.png",
  "content": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Response:

{
  "success": true,
  "message": "File uploaded successfully",
  "path": "/opt/app/image.png",
  "size": 15360
}

Download File

Download file content (returns base64 for binary files).

// Using SDK
const file = await sandbox.files.download({
  filePath: '/opt/app/image.png'
});

console.log(file.content); // base64 or text

POST /files/download HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "filePath": "/opt/app/image.png"
}

Response:

{
  "success": true,
  "content": "iVBORw0KGgoAAAANSUhEUgAA...",
  "encoding": "base64",
  "path": "/opt/app/image.png",
  "size": 15360,
  "mimeType": "image/png"
}

Advanced Usage

Working with File Watcher

The withWatcher parameter controls whether file changes trigger WebSocket events:

// Silent operation - no WebSocket notification
await sandbox.files.create({
  filePath: '/opt/app/temp.txt',
  content: 'temporary file',
  withWatcher: false
});

// Normal operation - triggers WebSocket event
await sandbox.files.create({
  filePath: '/opt/app/important.txt',
  content: 'important file',
  withWatcher: true // default
});

ℹ️ Info: Use withWatcher: false for batch operations to avoid flooding WebSocket listeners.

Batch Operations

Perform multiple file operations efficiently:

// Disable watcher for batch
const files = ['file1.js', 'file2.js', 'file3.js'];

for (const file of files) {
  await sandbox.files.create({
    filePath: `/opt/app/${file}`,
    content: '// Generated file',
    withWatcher: false
  });
}

// Re-enable watcher and notify once
await sandbox.files.create({
  filePath: '/opt/app/.batch-complete',
  content: '',
  withWatcher: true
});

Reading Large Files

Use range parameter for large files:

// Read first 100 lines
const chunk1 = await sandbox.files.get({
  filePath: '/opt/app/large-file.log',
  range: { start: 1, end: 100 }
});

// Read next 100 lines
const chunk2 = await sandbox.files.get({
  filePath: '/opt/app/large-file.log',
  range: { start: 101, end: 200 }
});

Error Handling

Common error scenarios:

try {
  await sandbox.files.get({ filePath: '/opt/app/missing.js' });
} catch (error) {
  if (error.status === 404) {
    console.log('File not found');
  } else if (error.status === 403) {
    console.log('Permission denied');
  } else {
    console.log('Error:', error.message);
  }
}

Best Practices

Check existence before operations:

const exists = await sandbox.files.exists({ filePath: path });
if (!exists.exists) {
  await sandbox.files.create({ filePath: path, content: '' });
}

Use line ranges for large files: Don't read entire large files at once
Disable watcher for batch operations: Improves performance for multiple file operations
Handle errors gracefully: Always wrap file operations in try-catch

Next Steps

Learn about File Listing in detail
Explore File Reading advanced features
Check File Writing best practices
Set up File Watcher for real-time updates

On this page