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_KEYandDECLAW_DOMAINset 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