Transfer small sandbox files with integrity checks

Use file transfer for bounded artifacts

Lupin's container files route transports content as base64 and is intended for small files around two megabytes. That is useful for fixtures, short scripts, configuration and compact results. It is not a bulk object-store interface. Plan larger datasets around an approved external storage mechanism or a deliberately split format with a manifest. Splitting arbitrary binary bytes without a reassembly plan can make recovery harder. Before transfer, record the intended path, raw size and a content digest so the receiving side has a concrete definition of completeness.

Understand the encoded size limit

Base64 expands the raw file, and the current route limits encoded input and output to 2,800,000 characters. Treat roughly two megabytes as guidance rather than assuming every two-megabyte representation will fit with every client. Upload rejects invalid base64 characters and unsafe paths, creates the parent directory, decodes the content and returns the resulting byte count. Download runs a base64 command in the sandbox and rejects an oversized encoded result. A missing file and an oversized file are different failures. Keep the raw-byte size and encoded-payload size distinct in your client and error messages.

Send stable identities for writes

Uploads execute a metered command under the hood, so durable deployments require a preserved Idempotency-Key on the HTTP request. The same applies to other command-backed mutations. Use a raw request or a client that supports that header rather than assuming every SDK helper currently supplies it. Store the transfer key with the task's expected path and digest. If a response is lost, do not immediately overwrite the same destination under a fresh key. Inspect the file or download it for verification first. A path existing is evidence of existence, not proof of complete content.

curl -X POST "https://api.lupin.sh/v0/containers/$CONTAINER_ID/files" \
  -H "Authorization: Bearer $LUPIN_API_KEY" \
  -H "Idempotency-Key: fixture-upload-001" \
  -H "Content-Type: application/json" \
  -d '{"path":"/tmp/task/hello.txt","content_b64":"aGVsbG8K"}'

Verify before using or publishing

After upload, compare the reported size with the expected raw size, then verify the file's digest or parse its format through an authorized command when appropriate. After download, decode and check the same properties locally. For structured data, a valid parse can detect truncation that a plausible filename cannot. Keep untrusted filenames separate from command syntax; use the file route's path field and explicit workspace locations. The path validation rejects null bytes and parent-traversal components, but it does not decide whether overwriting a legitimate existing path is appropriate for your task.

Handle partial work and secrets deliberately

If transfer fails, retain the expected manifest and determine whether a partial destination remains before continuing. Do not publish or execute an unverified script merely because the transport request returned. Avoid moving credentials through ordinary fixture files or logging the complete encoded payload. Export the final required artifact before stopping the resource, and keep the verification record outside the sandbox. Stopping and resuming are provider lifecycle actions rather than a general archival guarantee for your deliverable. The dependable transfer result is a verified file available where the user needs it, with any unresolved size or integrity limitation stated clearly.

Sources & verification

Reviewed against the current Lupin route, provider adapter and shared input contracts, plus the linked official references. Examples were not run against live services.

• docs.python.org · 3 · library · hashlib.html ↗Checked 2026-11-05
• docs.boat.dev · quickstart ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.