Local Sandbox Tools#

Before involving a model, look at where tools actually execute. This page opens LocalBackend directly, dispatches file, command, and code payloads by hand, and shows how they operate around the same local workspace.

Coverage#

Topic

Result

Backend registry

How get("local") returns the local Backend.

Sandbox handle

A local sandbox maps to one working directory.

Backend payload

File, command, and code execution are represented by BackendTool* data classes.

Structured result

Each dispatch returns a structured object.

Lifecycle

backend.close(sandbox) closes the sandbox and may clean up the working directory.

Step 1: Open the Local Backend#

from rath.backend import get

backend = get("local")
sandbox = backend.open()

print(backend.name)
print(backend.capabilities())
print(sandbox.handle)

Key lines:

Line

Explanation

get("local")

Gets the local Backend instance from the Backend registry.

backend.open()

Creates a BackendSandbox handle.

sandbox.handle

The workspace path managed by the local Backend.

Observed behavior:

  • backend.name is local.

  • sandbox.handle is a local path.

  • If no working_dir is passed, the local Backend creates a temporary directory.

Step 2: Write and Read a File#

from rath.backend import BackendToolFilesRead, BackendToolFilesWrite

write_result = sandbox.dispatch(
    BackendToolFilesWrite(path="hello.txt", data="hello OpenRath")
)
content = sandbox.dispatch(
    BackendToolFilesRead(path="hello.txt", encoding="utf-8")
)

print(write_result)
print(content)

Key lines:

Line

Explanation

BackendToolFilesWrite(...)

Describes a file write without executing it directly.

sandbox.dispatch(...)

Sends the payload to the current sandbox for execution.

BackendToolFilesRead(...)

Reads the file just written in the same workspace.

Observed behavior:

  • The write result includes the number of bytes written.

  • The read result includes the file content.

  • The relative path hello.txt is resolved from sandbox.handle.

Step 3: Run a Shell Command#

from rath.backend import BackendToolCommandRun

result = sandbox.dispatch(
    BackendToolCommandRun(cmd="pwd && cat hello.txt")
)

print(result.exit_code)
print(result.stdout.decode())
print(result.stderr.decode())

Key lines:

Line

Explanation

BackendToolCommandRun(...)

Describes a shell command execution.

exit_code

Lets the caller decide whether the command succeeded.

stdout / stderr

The current implementation stores output as bytes, so callers need to decode it.

Observed behavior:

  • pwd prints the directory for the local sandbox workspace.

  • cat hello.txt can read the content written in the previous step.

  • When a command fails, check exit_code and stderr first.

Step 4: Run Python Code#

from rath.backend import BackendToolCodeRun

result = sandbox.dispatch(
    BackendToolCodeRun(code="print(21 * 2)")
)

print(result.stdout.decode())
print(result.stderr.decode())
print(result.error)

The current local Backend writes the code to a temporary Python file, then runs it with the current Python interpreter. This is useful for checking tool paths and script behavior. Use a stricter isolated Backend for untrusted code.

Step 5: Close the Sandbox#

backend.close(sandbox)
print(sandbox.closed)

Key points:

Behavior

Notes

backend.close(sandbox)

Closes the sandbox handle.

Local workspace cleanup

The local Backend cleans up directories it manages.

Bound directory risk

When binding a real directory, make sure it can be recreated to reduce the risk of deleting important content.

Troubleshooting#

Symptom

Check

get("local") fails

Confirm OpenRath is installed and rath.backend imports correctly.

File cannot be read

Confirm the write and read happen on the same sandbox.

Command has no output

Print exit_code and stderr.decode() first.

Dispatch fails after close

Re-run backend.open() after the sandbox is closed.

Exercises#

  1. Change hello.txt to notes/hello.txt and observe whether the directory is created automatically.

  2. Rewrite the shell command so it lists all files under the workspace.

  3. Change the Python code so it reads hello.txt and prints its length.

Summary#

  • BackendTool* payloads describe Backend-side operations.

  • BackendSandbox.dispatch(...) executes a payload and returns a structured result.

  • File, command, and code payloads operate around the same sandbox workspace.

  • Built-in tools in the Session loop eventually run through this Backend dispatch layer.