Skip to main content

What You’ll Learn

  • How to upload a dataset file with sbx.files.write()
  • How to write and execute a Python analysis script inside the sandbox
  • How to read structured JSON results back using sbx.files.read()
  • The upload-compute-download pattern for safe, isolated data processing

Prerequisites

  • Declaw running locally or in the cloud (see Deployment)
  • DECLAW_API_KEY and DECLAW_DOMAIN set in your environment

Code Walkthrough

1. Define the dataset and analysis script

Both the CSV data and the analysis script are defined as Python strings and uploaded to the sandbox filesystem:
SALES_CSV = """\
date,product,region,quantity,unit_price
2024-01-05,Widget A,North,120,9.99
2024-01-05,Widget B,South,85,14.50
2024-01-12,Widget A,South,200,9.99
...
"""

ANALYSIS_SCRIPT = """\
import csv, json
from collections import defaultdict

rows = []
with open("/home/user/data/sales.csv") as f:
    reader = csv.DictReader(f)
    for row in reader:
        row["quantity"] = int(row["quantity"])
        row["unit_price"] = float(row["unit_price"])
        row["revenue"] = row["quantity"] * row["unit_price"]
        rows.append(row)

total_revenue = sum(r["revenue"] for r in rows)
rev_by_product = defaultdict(float)
for r in rows:
    rev_by_product[r["product"]] += r["revenue"]

top_product = max(rev_by_product, key=rev_by_product.get)

results = {
    "total_records": len(rows),
    "total_revenue": round(total_revenue, 2),
    "top_product": top_product,
    "revenue_by_product": {k: round(v, 2) for k, v in sorted(rev_by_product.items())},
}

with open("/home/user/data/results.json", "w") as f:
    json.dump(results, f, indent=2)

print("Analysis complete. Results written to /home/user/data/results.json")
"""

2. Upload, execute, and read back

from declaw import Sandbox
import json

sbx = Sandbox.create(template="python", timeout=300)
try:
    # Upload the dataset and analysis script
    sbx.files.write("/home/user/data/sales.csv", SALES_CSV)
    sbx.files.write("/home/user/data/analyze.py", ANALYSIS_SCRIPT)

    # Run the analysis inside the sandbox
    result = sbx.commands.run("python3 /home/user/data/analyze.py")
    print(result.stdout)  # "Analysis complete. Results written to ..."

    # Read the computed results back to the host
    results_json = sbx.files.read("/home/user/data/results.json")
    data = json.loads(results_json)

    print(f"Total revenue:  ${data['total_revenue']:,.2f}")
    print(f"Top product:    {data['top_product']}")
    for product, rev in data["revenue_by_product"].items():
        print(f"  {product}: ${rev:,.2f}")
finally:
    sbx.kill()

Expected Output

--- Creating Sandbox ---
Sandbox created: sbx-abc123

--- Uploading Dataset ---
  Uploaded: sales.csv

--- Running Analysis ---
  stdout: Analysis complete. Results written to /home/user/data/results.json

--- Summary ---
  Total records:     15
  Total revenue:     $27,897.40
  Total quantity:    1,640
  Avg order value:   $1,859.83
  Top product:       Widget A

  Revenue by product:
    Widget A: $11,680.30
    Widget B: $8,265.00
    Widget C: $7,952.10

  Revenue by region:
    East:  $7,012.20
    North: $9,865.50
    South: $11,019.70

Pattern Notes

Why run the analysis inside the sandbox instead of locally?
  • The analysis script could be untrusted (for example, user-submitted code in a data pipeline)
  • The dataset may contain sensitive data that should not be processed on the host
  • Sandbox isolation ensures the script cannot access host files, environment variables, or network resources
Scaling the pattern:
  • Use sbx.files.write_files() to upload multiple files in a single API call
  • Use sbx.commands.run_stream() for long-running analyses where you want incremental output
  • Add network={"deny_out": ["*"]} to block all outbound network access during analysis