File Operations

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

Overview

All file operations support both the SDK and REST API. Operations include:

List - List files and directories
Get - Read file content
Create - Create files or directories
Edit - Modify file content
Delete - Remove files or directories
Rename - Rename or move files
Exists - Check if file exists
Upload/Download - Transfer binary files

List Files

List files and directories in a path.

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: false,
  ignorePatterns: ['node_modules', '.git']
});

console.log(result.files);

Parameters:

dirPath (string, required) - Directory path to list
recursive (boolean) - Include subdirectories
ignorePatterns (string[]) - Patterns to ignore
nested (boolean) - Return nested structure
light (boolean) - Minimal info only
useGitignore (boolean) - Respect .gitignore
pathFilter (string) - Filter by path substring
includeHash (boolean) - Include file hash
includeContent (boolean) - Include file content
maxContentSize (number) - Max content size in bytes

const response = await fetch(`${sandbox.url}/files/list`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dirPath: '/opt/app',
    recursive: false,
    ignorePatterns: ['node_modules', '.git']
  })
});

const result = await response.json();

curl -X POST https://sandbox.oblien.com/files/list \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Response:

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

Get File Content

Read the contents of a file.

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

console.log(result.content);

Parameters:

filePath (string, required) - Full path to file
range (object) - Line range { start, end }
withLineNumbers (boolean) - Include line numbers

const response = await fetch(`${sandbox.url}/files/get`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filePath: '/opt/app/src/index.js',
    range: { start: 1, end: 50 },
    withLineNumbers: true
  })
});

const result = await response.json();

curl -X POST https://sandbox.oblien.com/files/get \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Response:

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

Create File or Directory

Create a new file or directory.

// Create a file
await sandbox.files.create({
  fullPath: '/opt/app/newfile.js',
  content: 'console.log("New file");'
});

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

// Alternative: Use parentPath + fileName
await sandbox.files.create({
  parentPath: '/opt/app',
  fileName: 'another-file.js',
  content: 'console.log("Another");'
});

Parameters:

fullPath (string) - Full path for new file/directory
parentPath (string) - Parent directory path
fileName (string) - File name
filePath (string) - Alternative to fullPath
content (string) - File content
isFolder (boolean) - Create directory
withWatcher (boolean, default: true) - Trigger file watcher

// Create a file
await fetch(`${sandbox.url}/files/create`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fullPath: '/opt/app/newfile.js',
    content: 'console.log("New file");'
  })
});

// Create a directory
await fetch(`${sandbox.url}/files/create`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fullPath: '/opt/app/newfolder',
    isFolder: true
  })
});

curl -X POST https://sandbox.oblien.com/files/create \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Response:

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

Edit File

Replace or modify file content.

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

Parameters:

filePath (string, required) - Path to file
content (string) - New file content
edits (object) - Edit operations (advanced)
withWatcher (boolean, default: true) - Trigger file watcher

await fetch(`${sandbox.url}/files/edit`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filePath: '/opt/app/config.json',
    content: JSON.stringify({ port: 3000, env: 'production' }, null, 2)
  })
});

curl -X POST https://sandbox.oblien.com/files/edit \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Response:

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

Delete File or Directory

Delete a file or directory.

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

Parameters:

filePath (string, required) - Path to delete
withWatcher (boolean, default: true) - Trigger file watcher

await fetch(`${sandbox.url}/files/delete`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filePath: '/opt/app/oldfile.js'
  })
});

curl -X POST https://sandbox.oblien.com/files/delete \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Response:

{
  "success": true,
  "message": "File deleted successfully"
}

Rename/Move File

Rename or move a file or directory.

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

// Or move to different directory
await sandbox.files.rename({
  sourcePath: '/opt/app/file.js',
  destinationPath: '/opt/app/src/file.js'
});

Parameters:

sourcePath (string, required) - Current path
destinationPath (string, required) - New path
withWatcher (boolean, default: true) - Trigger file watcher

await fetch(`${sandbox.url}/files/rename`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sourcePath: '/opt/app/old-name.js',
    destinationPath: '/opt/app/new-name.js'
  })
});

curl -X POST https://sandbox.oblien.com/files/rename \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Response:

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

Check File Exists

Check if a file or directory exists.

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

if (result.exists) {
  console.log('File exists!');
  console.log('Type:', result.type); // 'file' or 'directory'
}

const response = await fetch(`${sandbox.url}/files/exists`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filePath: '/opt/app/package.json'
  })
});

const result = await response.json();

curl -X POST https://sandbox.oblien.com/files/exists \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Response:

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

Merge File Changes

Intelligently merge content into a file.

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

Parameters:

filePath (string, required) - Path to file
content (string, required) - Content to merge
options (object) - Merge options
withWatcher (boolean, default: true) - Trigger file watcher

await fetch(`${sandbox.url}/files/merge`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filePath: '/opt/app/README.md',
    content: '## New Section\n\nAdditional content',
    options: { silent: false }
  })
});

curl -X POST https://sandbox.oblien.com/files/merge \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Response:

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

Upload File

Upload file content (useful for binary files).

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

await fetch(`${sandbox.url}/files/upload`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filePath: '/opt/app/image.png',
    content: base64EncodedContent
  })
});

curl -X POST https://sandbox.oblien.com/files/upload \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Response:

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

Download File

Download file content (returns base64 for binary files).

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

console.log(result.encoding); // 'base64' for binary, 'utf-8' for text
console.log(result.content);

const response = await fetch(`${sandbox.url}/files/download`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filePath: '/opt/app/image.png'
  })
});

const result = await response.json();

curl -X POST https://sandbox.oblien.com/files/download \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

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({
  fullPath: '/opt/app/temp.txt',
  content: 'temporary file',
  withWatcher: false
});

// Normal operation - triggers WebSocket event
await sandbox.files.create({
  fullPath: '/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:

const files = ['file1.js', 'file2.js', 'file3.js'];

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

// Notify once at the end
await sandbox.files.create({
  fullPath: '/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

try {
  await sandbox.files.get({ filePath: '/opt/app/missing.js' });
} catch (error) {
  console.error('Error:', error.message);
}

const response = await fetch(`${sandbox.url}/files/get`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ filePath: '/opt/app/missing.js' })
});

const result = await response.json();
if (!result.success) {
  console.error('Error:', result.error);
}

curl -X POST https://sandbox.oblien.com/files/get \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Best Practices

Check existence before operations:

const exists = await sandbox.files.exists({ filePath: path });
if (!exists.exists) {
  await sandbox.files.create({ fullPath: 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