Upload Files

Stream files from your local filesystem to the sandbox.

sandbox.upload_file(
    local_path: str,
    remote_path: str,
    overwrite: bool = False,
    progress: Optional[callable] = None,
    verify_checksum: bool = False
) -> bool

Parameters

local_pathstringrequired

Path to the local file to upload. Can be relative or absolute.

remote_pathstringrequired

Absolute path in the sandbox where the file should be stored. Must start with /.

overwriteboolean

Whether to overwrite the remote file if it exists. Defaults to False.

progresscallable

Optional callback function to track upload progress. Called periodically with bytes sent.

def on_progress(sent: int) -> None:
    # sent: bytes uploaded so far
    pass

verify_checksumboolean

Verify MD5 checksum after upload. Defaults to False.

Returns

Returns True on success. Raises SandboxFileExistsError when file exists.

Examples

Basic Example

from concave import Sandbox

sbx = Sandbox.create()

# Upload a local file to the sandbox
success = sbx.upload_file("./script.py", "/tmp/script.py")
if success:
    print("File uploaded successfully")
    
    # Execute the uploaded script
    result = sbx.execute("python /tmp/script.py")
    print(result.stdout)

sbx.delete()

Upload with Progress Tracking

from concave import Sandbox

sbx = Sandbox.create()

def on_progress(sent: int):
    mb_sent = sent / (1024 * 1024)
    print(f"\rUploading: {mb_sent:.2f} MB", end="")

# Upload a 50MB file with progress tracking
success = sbx.upload_file(
    "./large_dataset.csv",
    "/data/dataset.csv",
    progress=on_progress
)
print(f"\nUpload completed: {success}")

sbx.delete()

Upload with Checksum Verification

from concave import Sandbox

sbx = Sandbox.create()

# Upload with automatic checksum verification
success = sbx.upload_file(
    "./important_data.bin",
    "/tmp/data.bin",
    verify_checksum=True
)

if success:
    print("File uploaded and verified successfully")
else:
    print("Upload failed or checksum mismatch")

sbx.delete()

Upload Multiple Files

from concave import Sandbox

sbx = Sandbox.create()

files = [
    ("./config.json", "/app/config.json"),
    ("./script.py", "/app/script.py"),
]

for local, remote in files:
    sbx.upload_file(local, remote)
    print(f"Uploaded {local}")

sbx.delete()

Overwrite Protection

from concave import Sandbox, SandboxFileExistsError

sbx = Sandbox.create()

# First upload succeeds
success = sbx.upload_file(
    "./config.json",
    "/app/config.json"
)
print(f"First upload: {success}")  # True

# Second upload raises exception (file exists)
try:
    sbx.upload_file(
        "./config.json",
        "/app/config.json"
    )
except SandboxFileExistsError:
    print("File already exists!")

# Force overwrite
success = sbx.upload_file(
    "./config.json",
    "/app/config.json",
    overwrite=True
)
print(f"Overwrite upload: {success}")  # True

sbx.delete()

Exceptions

SandboxFileNotFoundErrorException

Raised when the local file doesn't exist.

SandboxFileExistsErrorException

Raised when the remote file already exists and overwrite=False.

SandboxValidationErrorException

Raised when remote_path is not absolute (doesn't start with /).

SandboxNotFoundErrorException

Raised when the sandbox no longer exists.

SandboxTimeoutErrorException

Raised when upload times out.

SandboxFileErrorException

Raised when checksum verification fails or other file-related errors occur.

Error Handling

from concave import (
    Sandbox,
    SandboxFileNotFoundError,
    SandboxFileError
)

sbx = Sandbox.create()

try:
    success = sbx.upload_file(
        "./data.csv",
        "/tmp/data.csv",
        verify_checksum=True
    )
    print(f"Upload successful: {success}")
except SandboxFileNotFoundError:
    print("Local file not found")
except SandboxFileError as e:
    print(f"Upload error: {e}")
finally:
    sbx.delete()