Sandbox Tool Builder

Building your own sandboxed tool

When you lack a tool you need, write one. A sandboxed tool is just a script in your workspace that reads a JSON request on stdin and writes a JSON response on stdout. You author it, test it, then forge_tool registers it as a real tool you can call from the next turn — and it always runs inside your sandbox, not on the host.

You need a sandbox (an isolated workspace) attached to this session. If you don't have one, forge_tool will tell you.

The loop

1. Write the script into your workspace with your file-write tool, at a stable path like tools/<name>/main.py. The contract:

   • read the whole request from stdin (a JSON object),
   • write the result to stdout as a JSON object,
   • on failure, print {"error": "..."} (or exit non-zero) — that surfaces as a tool error.

   Minimal Python example (tools/wordcount/main.py):

   import sys, json
   req = json.load(sys.stdin)
   text = req.get("text", "")
   print(json.dumps({"words": len(text.split()), "chars": len(text)}))
   

2. Test it with your shell tool, exactly how the tool will be invoked:

   echo '{"text":"a b c"}' | python3 tools/wordcount/main.py
   

   Iterate until the output JSON is right.

3. Forge it — register it live:

   env(action="forge_tool", args={
     "name": "wordcount",
     "description": "Count words and characters in text.",
     "entrypoint": "tools/wordcount/main.py",
     "runtime": "python3",
     "input_schema": {"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}
   })
   

   From the next turn you can call wordcount({"text": "..."}) like any tool.

4. Use it. Call it by name. If it misbehaves, fix the script, test again, and re-forge_tool (disable the old one first if the name clashes).

Persisting it (reuse across sessions)

forge_tool is for this session. To keep it, save a Sandbox Tool Pack:

env(action="save_pack", args={"name": "text-utils", "description": "word + slug tools"})