Work with files

Use sandbox.files to work with files inside a sandbox. Every path argument names a location inside the sandbox; it is the data that moves between the two machines. write(path, data) sends local bytes or text to a sandbox path, and read(path) returns a sandbox file’s content to your program.

from lithosbox import LithosBox

box = LithosBox()
sandbox = box.sandboxes.create()
sandbox.files.write("/work/message.txt", "Hello from LithosBox\n")
print(sandbox.files.read("/work/message.txt"))

write() creates missing parent directories. It replaces the entire file if that path already exists.

Upload and download

Use pathlib.Path to read a local file and send its contents to the sandbox:

from pathlib import Path

sandbox.files.write("/work/input.csv", Path("input.csv").read_bytes())

After your application creates a result, save it to your computer:

Path("result.png").write_bytes(sandbox.files.read_bytes("/work/result.png"))

Use read() for text and read_bytes() for binary files. Uploads support up to 4 MiB per call. Text reads support approximately 16 MiB, and binary reads support approximately 12 MiB. Use another transfer method for larger files.

Manage paths

sandbox.files.mkdir("/work/results")
sandbox.files.rename("/work/message.txt", "/work/results/message.txt")
print(sandbox.files.list("/work/results"))
print(sandbox.files.exists("/work/results/message.txt"))

Remove a file or directory with remove():

sandbox.files.remove("/work/results/message.txt")

Removing a directory also removes its contents.

Transfer larger files

For large inputs, download the file from a URL inside the sandbox when possible. You can also send chunks through a command’s standard input. This example uploads a local file without replacing earlier chunks:

source = Path("large-input.bin")
sandbox.run("mkdir -p /work && : > /work/large-input.bin").check()

with source.open("rb") as stream:
    while chunk := stream.read(4 * 1024 * 1024):
        sandbox.run("cat >> /work/large-input.bin", stdin=chunk).check()

size = int(sandbox.run(["wc", "-c", "/work/large-input.bin"]).check().stdout.split()[0])
assert size == source.stat().st_size

Use cat >> for appending; multiple files.write() calls to the same path would overwrite each other. Verify the size or checksum after a transfer. For large outputs, upload from the sandbox to storage you control, then download from there.

Upload a project directory

files.write() is one file per call. To ship a whole directory, pack it locally and unpack it in the sandbox with one command, sending the archive through standard input:

import io, tarfile

buffer = io.BytesIO()
with tarfile.open(fileobj=buffer, mode="w:gz") as tar:
    tar.add("my-project", arcname=".")

sandbox.run("mkdir -p /work/app && tar -xzf - -C /work/app",
            stdin=buffer.getvalue()).check()

One archive stays within the 4 MiB standard-input limit for most repositories; for a larger project, send the archive with the chunked cat >> pattern above and untar it, or download it inside the sandbox from storage you control. Exclude virtual environments and build artifacts before packing.

Keep or remove files

Files persist between commands and across archive/unarchive. To retain work before deleting the sandbox, download the files or save a durable snapshot. When you are finished:

sandbox.delete()
box.close()

Getting Started

Reference

Guides

Upload and download

Manage paths

Transfer larger files

Upload a project directory

Keep or remove files

​Upload and download

​Manage paths

​Transfer larger files

​Upload a project directory

​Keep or remove files

Upload and download

Manage paths

Transfer larger files

Upload a project directory

Keep or remove files