Skip to main content
Use the local filesystem API to inspect paths, read and write content, and manage files and directories inside a running sandbox.

​
Read And Write Files

await sandbox.files.writeText("/tmp/hello.txt", "hello from sandbox");

const text = await sandbox.files.readText("/tmp/hello.txt");
const bytes = await sandbox.files.readBytes("/tmp/hello.txt");

console.log(text);
console.log(bytes.toString("utf8"));

sandbox.files.write_text("/tmp/hello.txt", "hello from sandbox")

text = sandbox.files.read_text("/tmp/hello.txt")
data = sandbox.files.read_bytes("/tmp/hello.txt")

print(text)
print(data.decode("utf-8"))
Batch writes are also supported: 
await sandbox.files.write([
  { path: "/tmp/a.txt", data: "alpha" },
  { path: "/tmp/b.bin", data: Buffer.from([1, 2, 3]) },
]);

from hyperbrowser.models import SandboxFileWriteEntry

sandbox.files.write(
    [
        SandboxFileWriteEntry(path="/tmp/a.txt", data="alpha"),
        SandboxFileWriteEntry(path="/tmp/b.bin", data=bytes([1, 2, 3])),
    ]
)

​
Read Ranges And Different Formats

Use read() when you want to control offset, length, or representation. Supported formats include:
  • text
  • bytes
  • blob
  • stream

​
List And Inspect Paths

const exists = await sandbox.files.exists("/tmp/hello.txt");
const info = await sandbox.files.getInfo("/tmp/hello.txt");
const entries = await sandbox.files.list("/tmp", { depth: 1 });

console.log(exists);
console.log(info.permissions, info.owner, info.group);
console.log(entries.map((entry) => entry.path));

exists = sandbox.files.exists("/tmp/hello.txt")
info = sandbox.files.get_info("/tmp/hello.txt")
entries = sandbox.files.list("/tmp", depth=1)

print(exists)
print(info.permissions, info.owner, info.group)
print([entry.path for entry in entries])

hx file exists <sandbox-id> /tmp/hello.txt
hx file stat <sandbox-id> /tmp/hello.txt
hx file ls <sandbox-id> /tmp --depth 1

​
Move, Copy, Remove, And Update Permissions

await sandbox.files.makeDir("/tmp/data", { parents: true });
await sandbox.files.writeText("/tmp/data/source.txt", "payload");

await sandbox.files.copy({
  source: "/tmp/data/source.txt",
  destination: "/tmp/data/copied.txt",
});

await sandbox.files.rename("/tmp/data/copied.txt", "/tmp/data/renamed.txt");
await sandbox.files.chmod({ path: "/tmp/data/renamed.txt", mode: "0644" });
await sandbox.files.remove("/tmp/data/source.txt");

sandbox.files.make_dir("/tmp/data", parents=True)
sandbox.files.write_text("/tmp/data/source.txt", "payload")

sandbox.files.copy(
    source="/tmp/data/source.txt",
    destination="/tmp/data/copied.txt",
)

sandbox.files.rename("/tmp/data/copied.txt", "/tmp/data/renamed.txt")
sandbox.files.chmod(path="/tmp/data/renamed.txt", mode="0644")
sandbox.files.remove("/tmp/data/source.txt")

hx file mkdir <sandbox-id> /tmp/data --parents
hx file cp <sandbox-id> /tmp/data/source.txt /tmp/data/copied.txt
hx file mv <sandbox-id> /tmp/data/copied.txt /tmp/data/renamed.txt
hx file chmod <sandbox-id> /tmp/data/renamed.txt 0644
hx file rm <sandbox-id> /tmp/data/source.txt

​
Behavior Notes

The current filesystem implementation has a few practical guarantees worth knowing:
  • remove is idempotent for missing paths.
  • Removing a symlink removes the link, not the target.
  • Directory listings do not recurse through symlink loops.
  • Recursive copies preserve symlinks instead of expanding them indefinitely.