Skip to main content
Each sandbox has an isolated filesystem with specific directories for different purposes. Understanding the filesystem structure helps you organize files and persist data correctly.

​
Filesystem Structure

Each sandbox has an isolated filesystem: 
/
├── workspace/          # Persistent user data (recommended)
├── tmp/               # Temporary files (cleared on restart)
├── home/
│   └── user/          # User home directory
└── opt/
    └── packages/      # Installed packages

​
Directory Purposes

​
/workspace - Persistent Storage

The /workspace directory is the recommended location for storing user data. Files in /workspace persist across sandbox restarts, pauses, and resumes.
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# ✅ Store files in /workspace (persists across pause/resume)
sandbox.files.write("/workspace/data.csv", csv_content)

# Read persisted file
content = sandbox.files.read("/workspace/data.csv")

sandbox.kill()  # Cleanup

​
/tmp - Temporary Files

The /tmp directory is for temporary files that don’t need to persist. Files in /tmp are cleared when the sandbox restarts.
  • Python
  • JavaScript/TypeScript
# ✅ Use /tmp for temporary files
sandbox.files.write("/tmp/temp.txt", temp_data)

# Process temporary file
result = sandbox.run_code("""
with open('/tmp/temp.txt', 'r') as f:
    data = f.read()
print(data)
""")

​
/home/user - User Home Directory

The /home/user directory is the user’s home directory. Useful for storing user-specific configuration files.
  • Python
  • JavaScript/TypeScript
# Store user config
sandbox.files.write("/home/user/.config", config_data)

​
Best Practices

Always use /workspace for files that need to persist:
  • Python
  • JavaScript/TypeScript
# ✅ Good: Files persist across restarts
sandbox.files.write("/workspace/data.csv", csv_content)
sandbox.files.write("/workspace/results.json", results)
Use /tmp for files that don’t need to persist:
  • Python
  • JavaScript/TypeScript
# ✅ Good: Temporary files
sandbox.files.write("/tmp/cache.txt", cache_data)
Avoid writing to root or system directories:
  • Python
  • JavaScript/TypeScript
# ❌ Bad: Don't write to system directories
# sandbox.files.write("/etc/config", data)  # Don't do this
# sandbox.files.write("/usr/bin/script", data)  # Don't do this
Organize files in subdirectories for better structure:
  • Python
  • JavaScript/TypeScript
# ✅ Good: Organized structure
sandbox.files.write("/workspace/data/input.csv", input_data)
sandbox.files.write("/workspace/data/output.json", output_data)
sandbox.files.write("/workspace/scripts/process.py", script_code)

​
File Operations

​
Writing Files

  • Python
  • JavaScript/TypeScript
# Write text file
sandbox.files.write("/workspace/data.txt", "Hello, World!")

# Write binary file (use write_bytes for binary data)
sandbox.files.write_bytes("/workspace/image.png", image_bytes)

​
Reading Files

  • Python
  • JavaScript/TypeScript
# Read text file
content = sandbox.files.read("/workspace/data.txt")

# Read binary file (use read_bytes for binary data)
image_data = sandbox.files.read_bytes("/workspace/image.png")

​
Listing Files

  • Python
  • JavaScript/TypeScript
# List files in directory
files = sandbox.files.list("/workspace")

for file in files:
    print(f"{file.name} - {file.size} bytes")
    if file.is_file:
        print(f"  File: {file.size_kb:.2f} KB")
    else:
        print(f"  Directory")

sandbox.kill()  # Cleanup

​
Next Steps

Core Concepts

Back to Core Concepts overview

File Operations Guide

Learn more about file operations

Sandbox Lifecycle

Understand state persistence

Security

Learn about filesystem isolation