Binary File Operations

The sbx.files.write() API accepts both strings and raw bytes. When you pass bytes (Python) or Uint8Array (TypeScript), the SDK automatically routes the payload to the binary-safe PUT /files/raw endpoint (Content-Type: application/octet-stream, 500 MiB cap) instead of the text-only JSON endpoint. Callers pass whatever type they have — no manual base64 dance required.

What You’ll Learn

Writing raw bytes with sbx.files.write(path, b"...")
Reading bytes back with format="bytes" and verifying byte-identical round-trip
Writing real binary formats (a PNG) and proving the sandbox can decode them
The base64.b64decode(...) → files.write(...) pattern common in LLM tool-use pipelines
Mixed batch writes — WriteEntry entries with str and bytes data in a single write_files() call

Prerequisites

export DECLAW_API_KEY="your-api-key"
export DECLAW_DOMAIN="your-declaw-instance.example.com:8080"

Code Walkthrough

Python
TypeScript

import base64
import os
from declaw import Sandbox, WriteEntry

# 1x1 transparent PNG — 67 bytes.
PNG_B64 = (
    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwC"
    "AAAAC0lEQVR42mNgYAAAAAMAASsJTYQAAAAASUVORK5CYII="
)

sbx = Sandbox.create(template="base", timeout=300)

Random binary blob — the classic round-trip test:

blob = os.urandom(4096)
sbx.files.write("/tmp/blob.bin", blob)
got = sbx.files.read("/tmp/blob.bin", format="bytes")
assert bytes(got) == blob

Real PNG — write it, then let the sandbox decode it:

png_bytes = base64.b64decode(PNG_B64)
sbx.files.write("/tmp/pixel.png", png_bytes)

result = sbx.commands.run("file /tmp/pixel.png")
print(result.stdout.strip())
# /tmp/pixel.png: PNG image data, 1 x 1, 8-bit/color RGBA, non-interlaced

Base64-decoded payload — the LLM tool-use pattern:

payload_b64 = base64.b64encode(b"\x00\x01\xff\xfe\x80\x81").decode()
decoded = base64.b64decode(payload_b64)
sbx.files.write("/tmp/decoded.bin", decoded)

Mixed batch — str and bytes entries in a single call. The SDK partitions entries internally (str → JSON batch, bytes → raw PUT) and returns results in the original input order:

results = sbx.files.write_files([
    WriteEntry(path="/tmp/readme.txt", data="Hello from a mixed batch."),
    WriteEntry(path="/tmp/config.bin", data=os.urandom(256)),
])
for r in results:
    print(r.path, r.size)

import { Sandbox } from "@declaw/sdk";
import type { WriteEntry } from "@declaw/sdk";
import { Buffer } from "node:buffer";
import { randomBytes } from "node:crypto";

const PNG_B64 =
  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNgYAAAAAMAASsJTYQAAAAASUVORK5CYII=";

const sbx = await Sandbox.create({ template: "base", timeout: 300 });

Random binary blob:

const blob = new Uint8Array(randomBytes(4096));
await sbx.files.write("/tmp/blob.bin", blob);
const got = await sbx.files.read("/tmp/blob.bin", { format: "bytes" });

Real PNG:

const pngBytes = new Uint8Array(Buffer.from(PNG_B64, "base64"));
await sbx.files.write("/tmp/pixel.png", pngBytes);
const result = await sbx.commands.run("file /tmp/pixel.png");
console.log(result.stdout.trim());

Mixed batch:

const entries: WriteEntry[] = [
  { path: "/tmp/readme.txt", data: "Hello from a mixed batch." },
  { path: "/tmp/config.bin", data: new Uint8Array(randomBytes(256)) },
];
await sbx.files.writeFiles(entries);

When to use the URL helpers instead

/files/raw caps request bodies at 500 MiB, but the JSON gateway in front caps the text endpoint at 10 MiB. For very large uploads (hundreds of MB or GB-class), prefer sbx.upload_url(path) and sbx.download_url(path) — they return URLs your client can PUT/GET streams against directly.

url = sbx.upload_url("/data/huge.tar.gz")
# Use `requests`, `httpx`, or curl to PUT a large stream at this URL.

Expected Output (Python)

Sandbox created: sbx_abc123

--- Section 1: Random binary blob ---
Wrote and read back 4096 random bytes, sha=<hex>

--- Section 2: Real PNG ---
`file` output: /tmp/pixel.png: PNG image data, 1 x 1, 8-bit/color RGBA, non-interlaced

--- Section 3: Base64-decoded payload ---
Wrote 8 decoded bytes, round-trip OK

--- Section 4: Mixed batch write ---
  wrote /tmp/readme.txt (25 bytes)
  wrote /tmp/config.bin (256 bytes)
Both entries round-tripped cleanly.

Getting Started

Built-in Templates

Commands

PTY

OpenAI Agents

Filesystem

Volumes

Network Policies

PII Protection

Security Features

LLM Providers

Framework Integrations

Agent-in-Sandbox

Real-World Patterns

Security Demos

Binary File Operations

What You’ll Learn

Prerequisites

Code Walkthrough

When to use the URL helpers instead

Expected Output (Python)

​What You’ll Learn

​Prerequisites

​Code Walkthrough

​When to use the URL helpers instead

​Expected Output (Python)

What You’ll Learn

Prerequisites

Code Walkthrough

When to use the URL helpers instead

Expected Output (Python)