Skip to main content

What You’ll Learn

  • How to write an agent script into a sandbox filesystem using sbx.files.write()
  • How to upload a task definition (JSON) for the agent to consume
  • How to run the agent with sbx.commands.run() and capture its output
  • How to read structured results back from the sandbox after execution
  • The core pattern of isolating autonomous code execution inside a sandbox

Prerequisites

  • Declaw running locally or in the cloud (see Deployment)
  • DECLAW_API_KEY and DECLAW_DOMAIN set in your environment
This example uses Python only. The agent script itself is a plain Python string uploaded to the sandbox — no external agent framework is required.

Code Walkthrough

1. Define the agent script

The agent script is a Python string defined in the outer (host) process. It will be written into the sandbox and executed there. It reads a task file, runs each shell command in the task, and writes structured results to /tmp/result.json.

2. Define the task

The task is a Python dict that will be serialized to JSON and uploaded alongside the agent:

3. Create the sandbox and upload files

4. Run the agent and read results

Expected Output

Key Pattern

The outer script orchestrates; the agent script executes. This separation means:
  • The host process controls what the agent can do (via the task definition)
  • Agent code never runs on the host machine — only inside the isolated sandbox
  • Results are returned by reading files from the sandbox, keeping the interface clean