- A local sandbox session is a Composio session with code execution turned off. Composio still does discovery and auth; it just won’t run code for you.
- The helper contract is what comes back: a Python helper exposing the same
run_composio_tool,invoke_llm, andweb_searchtools Composio’s managed sandbox runs for you, plus theenvit needs. You inject it into your sandbox and the agent calls it. - Your sandbox is the boundary. Tool execution happens in a box you control. E2B is the replaceable sample runner; the contract it honors is the real interface.
Setup
You need a Composio API key, an OpenAI API key for the reviewer agent, a GitHub connection for yourCOMPOSIO_USER_ID, and Bun.
No sandbox provider? Use the E2B sample runner
No sandbox provider? Use the E2B sample runner
The host writes the Composio helper into a sandbox and runs the agent there, so it needs somewhere to run code. This example ships an E2B runner in
src/sandbox/e2b.ts so you can run it today with just an E2B_API_KEY. E2B is a hosted sandbox provider: that key provisions an isolated microVM to run the agent in, so you don’t have to stand up a VM or container yourself. It’s still real infrastructure, just E2B’s to manage rather than yours.E2B is deliberately isolated to that one file. To run on your own VM, container, or CI worker, replace createE2bSandbox with anything that honors the same contract: create a directory, write helperSource into it, pass env to the process, stream stdout and stderr back, and tear down on your schedule.Build the host
src/runner.ts is the host: it owns orchestration, never tool execution. It starts as a bare Composio client and grows into the full run loop, one concept at a time. Each diff below is exactly what that concept adds.
Create the Composio client
The whole thing acts as one stable user, against the connections they own. Start there.src/runner.ts — step 1: Create the Composio client
Start from scratch. One client, one stable user id. Everything below acts as this user, against the connections they own.
src/runner.ts
Check the GitHub connection
A local sandbox still leans on Composio for auth and tool discovery; only code execution moves to your side. So before booting any infrastructure, confirm this user actually has GitHub connected, and hand them a connect link if not.src/runner.ts — step 2: Check the GitHub connection
A local sandbox still uses Composio for auth and tool discovery. Before booting any infrastructure, confirm this user has an active GitHub connection, and hand them a connect link if not.
src/runner.ts
Create the local sandbox session
The core of the integration. You create a Composio session yourself with code execution off (workbench.enable: false, so Composio will not run code for you), then hand that session to experimental_createLocalWorkbenchSession. The helper validates the session is local (it errors if the session has the remote workbench enabled, because the managed workbench and a local sandbox can’t both run for one session) and returns the pieces you run yourself: a helperSource (a Python helper with run_composio_tool, invoke_llm, and web_search) and the env that helper needs to reach Composio from inside your box.
src/runner.ts — step 3: Create the local sandbox session
The whole idea. Create a Composio session yourself with workbench.enable: false (Composio will not run code for you), then hand that session to experimental_createLocalWorkbenchSession, which validates it is local and returns the helper source and env you run yourself.
src/runner.ts
Start your sandbox, inject the helper
Boot a box you control, writehelperSource into it as composio_helper.py, and pass env to the process. That helper is the only Composio-specific thing your sandbox has to carry. E2B is the sample runner; swap it for anything that honors the same contract.
src/runner.ts — step 4: Start your sandbox, inject the helper
Boot a box you control, write helperSource into it as composio_helper.py, and pass env to the process. E2B is the sample runner; this is the only Composio-specific thing your sandbox must carry.
src/runner.ts
Run the reviewer and stream output
Run the agent inside the sandbox and stream its output back. Whenever the agent callsrun_composio_tool, the helper routes that GitHub action back through Composio under this user’s connection. Tool execution happens in your box; discovery and auth stay managed.
src/runner.ts — step 5: Run the reviewer and stream output
Run the agent inside the sandbox. Whenever it calls run_composio_tool, the helper routes that GitHub action back through Composio under this user, so tool execution happens in your box, but discovery and auth stay managed.
src/runner.ts
The whole project
The file above is the spine. The real project rounds it out with a CLI, a smoke/dry-run path, the E2B runner behind the sandbox contract, the reviewer agent and its review policy, and thecomposio_helper.py the helper source compiles to. Here’s a slice of the actual source, with the Composio touch-points highlighted. Browse the tree, read the files:
The local PR reviewer browser is a documentation snapshot; a public repository is not available.