File Writing

Create new files, edit existing ones, and merge changes intelligently.

Create File

await sandbox.files.create({
  fullPath: '/opt/app/new-file.js',
  content: 'export default function hello() {\n  console.log("Hello!");\n}'
});

await fetch(`${sandbox.url}/files/create`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fullPath: '/opt/app/new-file.js',
    content: 'export default function hello() {\n  console.log("Hello!");\n}'
  })
});

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/new-file.js",
  "size": 62
}

Create Directory

await sandbox.files.create({
  fullPath: '/opt/app/new-folder',
  isFolder: true
});

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

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

Edit File

Replace entire file content:

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

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"

Merge Changes

Intelligently merge content into existing files:

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

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: '\n## New Section\n\nAdditional documentation here.',
    options: { silent: false }
  })
});

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

Upload Binary Files

For binary files (images, PDFs, etc.), use base64 encoding:

const imageBase64 = '...'; // base64 encoded image

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

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

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

Complete Example: Update Config

// Read existing config
const file = await sandbox.files.get({
  filePath: '/opt/app/config.json'
});

// Parse and update
const config = JSON.parse(file.content);
config.apiUrl = 'https://api.example.com';
config.timeout = 5000;

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

console.log('Config updated successfully');

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

const file = await response.json();

// Parse and update
const config = JSON.parse(file.content);
config.apiUrl = 'https://api.example.com';
config.timeout = 5000;

// Write updated config
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(config, null, 2)
  })
});

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

File Watcher Integration

Control whether file changes trigger WebSocket events:

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

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

Parameters

Create/Upload

Parameter	Type	Default	Description
`fullPath`	string	-	Full file path
`parentPath`	string	-	Parent directory
`fileName`	string	-	File name
`content`	string	-	File content
`isFolder`	boolean	false	Create directory
`withWatcher`	boolean	true	Trigger file watcher

Edit/Merge

Parameter	Type	Default	Description
`filePath`	string	required	Path to file
`content`	string	required	New content
`options`	object	-	Merge options
`withWatcher`	boolean	true	Trigger file watcher

Best Practices

Check if file exists before creating:

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

Use edit for complete replacements: Use edit() when replacing entire file content
Use merge for partial updates: Use merge() when adding to existing content
Disable watcher for batch operations: Set withWatcher: false for multiple operations
Validate content before writing: Ensure content is valid before saving

Error Handling

try {
  await sandbox.files.create({
    fullPath: '/opt/app/new-file.js',
    content: 'console.log("test");'
  });
} catch (error) {
  if (error.message.includes('already exists')) {
    // File exists, use edit instead
    await sandbox.files.edit({
      filePath: '/opt/app/new-file.js',
      content: 'console.log("test");'
    });
  } else {
    console.error('Error:', error);
  }
}

Next Steps

File Reading - Read file contents
File Listing - List directory contents
File Operations - All file operations
File Watcher - Real-time file monitoring

On this page