When to use it
Reach for a local sandbox when:- Sensitive code or data. The agent runs untrusted code or touches data that can’t leave your infrastructure.
- You already run sandboxes. You’d rather run agent code in your own VM, container, or CI worker than a hosted runtime.
- You need your own filesystem and shell. The task installs packages, runs a build, or shells out to local tools.
Create a local sandbox session
A local sandbox session is a session created with the remote sandbox turned off. Setworkbench.enable: false, then pass the session to experimental_createLocalWorkbenchSession (from the @composio/experimental package), which returns the two pieces you run yourself.
experimental_createLocalWorkbenchSession validates that the session is local: it throws if the session has the remote workbench enabled, because the remote sandbox and a local one can’t both run for a single session. The session you pass in must have workbench.enable: false.
The API ships under the
experimental_ prefix and the @composio/experimental/workbench entry point, so the surface may change in a future release.The helper contract
helperSource is a Python module your agent imports. It exposes the same helpers the remote sandbox runs, with the same signatures, so the agent calls tools without knowing that execution is local:
run_composio_tool call routes back through the Tool Router under the session’s connections, so auth and discovery stay managed.
Most of the workbench helpers run in a local sandbox today. Only the file helpers, which depend on the managed /mnt/files mount, are remote-only:
If your agent needs one of the file helpers, use the remote sandbox for now.
Security: the sandbox is your boundary
The helper reaches Composio with your projectCOMPOSIO_API_KEY, injected into the sandbox through env. Any code or output in the sandbox can read it, and that key acts across every connection on the project.