Filesystem

Every sandbox has its own isolated filesystem. You can read, write, list, and delete files using the files API. You can also upload files from your local machine and download files from the sandbox.

Writing Files

Create or overwrite files in the sandbox filesystem.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

// Write a text file
await sandbox.files.write('/home/user/hello.txt', 'Hello, Vibengine!')

// Write a JSON file
await sandbox.files.write(
  '/home/user/config.json',
  JSON.stringify({ key: 'value', debug: true }, null, 2)
)

// Write a script
await sandbox.files.write('/home/user/script.py', `
import json
data = {"result": 42}
print(json.dumps(data))
`)

from vibengine import Sandbox

sandbox = Sandbox.create()

# Write a text file
sandbox.files.write("/home/user/hello.txt", "Hello, Vibengine!")

# Write a JSON file
import json
sandbox.files.write(
    "/home/user/config.json",
    json.dumps({"key": "value", "debug": True}, indent=2)
)

# Write a script
sandbox.files.write("/home/user/script.py", """
import json
data = {"result": 42}
print(json.dumps(data))
""")

Reading Files

Read the contents of files from the sandbox.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

await sandbox.files.write('/home/user/data.txt', 'important data')

// Read the file content
const content = await sandbox.files.read('/home/user/data.txt')
console.log(content) // "important data"

from vibengine import Sandbox

sandbox = Sandbox.create()

sandbox.files.write("/home/user/data.txt", "important data")

# Read the file content
content = sandbox.files.read("/home/user/data.txt")
print(content)  # "important data"

Listing Directory Contents

List files and directories at a given path.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

// Create some files
await sandbox.files.write('/home/user/file1.txt', 'a')
await sandbox.files.write('/home/user/file2.txt', 'b')
await sandbox.commands.run('mkdir -p /home/user/subdir')

// List directory contents
const entries = await sandbox.files.list('/home/user')

for (const entry of entries) {
  console.log(`${entry.name} - ${entry.type}`)
  // "file1.txt - file"
  // "file2.txt - file"
  // "subdir - dir"
}

from vibengine import Sandbox

sandbox = Sandbox.create()

# Create some files
sandbox.files.write("/home/user/file1.txt", "a")
sandbox.files.write("/home/user/file2.txt", "b")
sandbox.commands.run("mkdir -p /home/user/subdir")

# List directory contents
entries = sandbox.files.list("/home/user")

for entry in entries:
    print(f"{entry.name} - {entry.type}")
    # "file1.txt - file"
    # "file2.txt - file"
    # "subdir - dir"

Removing Files

Delete files or directories from the sandbox.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

await sandbox.files.write('/home/user/temp.txt', 'temporary')

// Remove a file
await sandbox.files.remove('/home/user/temp.txt')

from vibengine import Sandbox

sandbox = Sandbox.create()

sandbox.files.write("/home/user/temp.txt", "temporary")

# Remove a file
sandbox.files.remove("/home/user/temp.txt")

Uploading Files

Upload a file from your local machine into the sandbox.

import { Sandbox } from 'vibengine'
import fs from 'fs'

const sandbox = await Sandbox.create()

// Read local file and upload
const localContent = fs.readFileSync('./local-data.csv', 'utf-8')
await sandbox.files.write('/home/user/data.csv', localContent)

// For binary files, use Buffer
const binaryContent = fs.readFileSync('./image.png')
await sandbox.files.write('/home/user/image.png', binaryContent)

from vibengine import Sandbox

sandbox = Sandbox.create()

# Read local file and upload
with open("./local-data.csv", "r") as f:
    sandbox.files.write("/home/user/data.csv", f.read())

# For binary files
with open("./image.png", "rb") as f:
    sandbox.files.write("/home/user/image.png", f.read())

Downloading Files

Download a file from the sandbox to your local machine.

import { Sandbox } from 'vibengine'
import fs from 'fs'

const sandbox = await Sandbox.create()

// Generate a file inside the sandbox
await sandbox.commands.run('echo "report data" > /home/user/report.txt')

// Download it
const content = await sandbox.files.read('/home/user/report.txt')
fs.writeFileSync('./downloaded-report.txt', content)

from vibengine import Sandbox

sandbox = Sandbox.create()

# Generate a file inside the sandbox
sandbox.commands.run('echo "report data" > /home/user/report.txt')

# Download it
content = sandbox.files.read("/home/user/report.txt")
with open("./downloaded-report.txt", "w") as f:
    f.write(content)

Watching Files for Changes

You can watch a directory for file changes. This is useful for monitoring output or reacting to generated files.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

// Start watching for changes
const watcher = sandbox.files.watch('/home/user', async (event) => {
  console.log(`File ${event.name} was ${event.type}`)
})

// Create a file — triggers the watcher
await sandbox.files.write('/home/user/output.txt', 'new content')

// Stop watching when done
await watcher.stop()

from vibengine import Sandbox

sandbox = Sandbox.create()

# Start watching for changes
def on_change(event):
    print(f"File {event.name} was {event.type}")

watcher = sandbox.files.watch("/home/user", on_change)

# Create a file — triggers the watcher
sandbox.files.write("/home/user/output.txt", "new content")

# Stop watching when done
watcher.stop()

File watching is event-driven and non-blocking. It runs in the background and calls your handler whenever a file system event occurs in the watched directory.

The sandbox filesystem is ephemeral. When the sandbox stops, all files are lost. Use Persistence features to save state across sessions.

Next Steps

Execute Commands — run shell commands that produce files
Persistence — save sandbox state for later
Internet Access — download files from the web into your sandbox

Filesystem

On this page