> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Review pull requests in a sandbox you own

> Composio usually runs your tools for you. A local sandbox is for when you need to run them yourself, on your filesystem, in your shell, inside your security boundary. Build a GitHub PR reviewer that runs checks in a sandbox you own and posts one grounded comment.

Composio usually runs your tools for you. A **local sandbox** is for the times you need to run them yourself: your filesystem, your shell, your security boundary. You still get [managed auth](https://composio-preview.mintlify.site/docs/authentication) and 1000+ apps; you just keep the code execution.

This example builds a GitHub PR reviewer that does exactly that: it clones a pull request into a sandbox *you* own, runs the repo's real checks there, and posts one grounded comment. The sandbox here is E2B, but E2B is just the sample. The same pattern works with your own VM, container, Kubernetes job, or internal sandbox service.

It comes down to a handful of Composio pieces:

1. **A local sandbox session** is a [Composio session](https://composio-preview.mintlify.site/docs/how-composio-works.md) with [code execution turned off](https://composio-preview.mintlify.site/docs/configuring-sessions.md#disabling-the-sandbox). Composio still does [discovery](https://composio-preview.mintlify.site/docs/how-composio-works.md#meta-tools) and auth; it just won't run code for you.
2. **The helper contract** is what comes back: a Python helper exposing the same [`run_composio_tool`, `invoke_llm`, and `web_search`](https://composio-preview.mintlify.site/docs/sandbox/remote) tools Composio's managed sandbox runs for you, plus the `env` it needs. You inject it into your sandbox and the agent calls it.
3. **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.

> [!WARNING]
>
> **The sandbox holds your project API key**
>
> The `env` that `experimental_createLocalWorkbenchSession` returns includes your **project** `COMPOSIO_API_KEY`, and you inject that `env` into the sandbox. Anything running there can read it, including the untrusted PR code you clone and build. Treat the sandbox as your trust boundary: run it on infrastructure you control, give the reviewer a key scoped to only what it needs, and rotate the key if a run could have leaked it.

local-sandbox.runtime

code runs in your box

Host

Your orchestrator

src/runner.ts

Creates the session with
`workbench.enable: false`
, then starts a sandbox you own.

helper + env → sandbox

Sandbox · yours

Reviewer agent

your filesystem + shell

Clones the PR, installs deps, runs the repo's real checks, all
inside your boundary.

run\_composio\_tool → Composio

Composio

Session

Resolves the right GitHub action, runs it under the user's
connection, and returns the result to the sandbox.

<ul><li>· search + schema discovery</li>
<li>· managed GitHub auth</li>
<li>· tool execution + result</li></ul>

host (session, execution off)
→ your sandbox
(runs checks)
→
run\_composio\_tool
→ Composio
(resolve + execute)
→ grounded PR
comment

Below you build the host orchestration from scratch: a bare client first, then a piece at a time up to the full run loop, then a browse of the real source. You bring a Composio API key and a place to run code. Composio brings the tools.

## Setup

You need a [Composio API key](https://dashboard.composio.dev?utm_source=docs\&utm_medium=content\&utm_campaign=examples-local-sandbox-pr-reviewer), an OpenAI API key for the reviewer agent, a GitHub connection for your `COMPOSIO_USER_ID`, and [Bun](https://bun.sh).

> [accordion] 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](https://e2b.dev) 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.

```bash theme={null}
bun add @composio/core @composio/experimental e2b @openai/agents
```

Connect GitHub once for the user id you'll review as, then keep that same id for the review run:

```bash theme={null}
bun run connect
```

## 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.

```typescript src/runner.ts theme={null}
```

### Check the GitHub connection

A local sandbox still leans on Composio for auth and [tool discovery](https://composio-preview.mintlify.site/docs/how-composio-works.md#meta-tools); only code execution moves to your side. So before booting any infrastructure, confirm this user actually has [GitHub connected](https://composio-preview.mintlify.site/docs/authentication), 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.

```typescript src/runner.ts theme={null}
import { Composio } from '@composio/core';
import { experimental_createLocalWorkbenchSession } from '@composio/experimental/workbench';
import { createE2bSandbox } from './sandbox/e2b';

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
const userId = process.env.COMPOSIO_USER_ID ?? 'local-pr-reviewer-user';

// Composio runs tools as a user. Before anything else, make sure this user has
// an active GitHub connection. There's no point booting a sandbox without one.
async function requireGithubConnection() {
  const list = await composio.connectedAccounts.list({
    userIds: [userId],
    toolkitSlugs: ['github'],
    statuses: ['ACTIVE'],
  });
  if (list.items?.[0]) return;

  const request = await composio.toolkits.authorize(userId, 'github');
  throw new Error(`Connect GitHub first: ${request.redirectUrl}`);
}
```

### Create the local sandbox session

The core of the integration. You create a [Composio session](https://composio-preview.mintlify.site/docs/configuring-sessions.md#creating-a-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.

```typescript src/runner.ts theme={null}
import { Composio } from '@composio/core';
import { experimental_createLocalWorkbenchSession } from '@composio/experimental/workbench';
import { createE2bSandbox } from './sandbox/e2b';

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
const userId = process.env.COMPOSIO_USER_ID ?? 'local-pr-reviewer-user';

// Composio runs tools as a user. Before anything else, make sure this user has
// an active GitHub connection. There's no point booting a sandbox without one.
async function requireGithubConnection() {
  const list = await composio.connectedAccounts.list({
    userIds: [userId],
    toolkitSlugs: ['github'],
    statuses: ['ACTIVE'],
  });
  if (list.items?.[0]) return;

  const request = await composio.toolkits.authorize(userId, 'github');
  throw new Error(`Connect GitHub first: ${request.redirectUrl}`);
}

// The local sandbox session. Create a normal Composio session yourself with
// `workbench.enable: false` (Composio won't run code for you), then hand that
// session to the helper, which validates it's local and gives you the pieces to
// run code yourself, wherever you choose.
async function createWorkbench() {
  const session = await composio.create(userId, {
    toolkits: ['github'],
    workbench: { enable: false },
  });
  return experimental_createLocalWorkbenchSession(composio, session);
  // returns { helperSource, env }:
  //   helperSource: a Python helper exposing run_composio_tool / invoke_llm / web_search
  //   env:          the variables that helper needs to reach Composio from inside your box
}
```

### 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. 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.

```typescript src/runner.ts theme={null}
import { Composio } from '@composio/core';
import { experimental_createLocalWorkbenchSession } from '@composio/experimental/workbench';
import { createE2bSandbox } from './sandbox/e2b';

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
const userId = process.env.COMPOSIO_USER_ID ?? 'local-pr-reviewer-user';

// Composio runs tools as a user. Before anything else, make sure this user has
// an active GitHub connection. There's no point booting a sandbox without one.
async function requireGithubConnection() {
  const list = await composio.connectedAccounts.list({
    userIds: [userId],
    toolkitSlugs: ['github'],
    statuses: ['ACTIVE'],
  });
  if (list.items?.[0]) return;

  const request = await composio.toolkits.authorize(userId, 'github');
  throw new Error(`Connect GitHub first: ${request.redirectUrl}`);
}

// The local sandbox session. Create a normal Composio session yourself with
// `workbench.enable: false` (Composio won't run code for you), then hand that
// session to the helper, which validates it's local and gives you the pieces to
// run code yourself, wherever you choose.
async function createWorkbench() {
  const session = await composio.create(userId, {
    toolkits: ['github'],
    workbench: { enable: false },
  });
  return experimental_createLocalWorkbenchSession(composio, session);
  // returns { helperSource, env }:
  //   helperSource: a Python helper exposing run_composio_tool / invoke_llm / web_search
  //   env:          the variables that helper needs to reach Composio from inside your box
}

export async function runReview(repo: string, pr: number) {
  await requireGithubConnection();
  const workbench = await createWorkbench();

  // Start a sandbox you own, inject the helper, and pass the env. E2B is just
  // the sample runner; swap createE2bSandbox for any box that honors the same
  // contract: write a file, set env, run a command, stream output, tear down.
  const sandbox = await createE2bSandbox({
    apiKey: process.env.E2B_API_KEY,
    helperSource: workbench.helperSource, // written as composio_helper.py
    env: workbench.env,
  });
}
```

### Run the reviewer and stream output

Run the agent inside the sandbox and stream its output back. Whenever the agent calls `run_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.

```typescript src/runner.ts theme={null}
import { Composio } from '@composio/core';
import { experimental_createLocalWorkbenchSession } from '@composio/experimental/workbench';
import { createE2bSandbox } from './sandbox/e2b';

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
const userId = process.env.COMPOSIO_USER_ID ?? 'local-pr-reviewer-user';

// Composio runs tools as a user. Before anything else, make sure this user has
// an active GitHub connection. There's no point booting a sandbox without one.
async function requireGithubConnection() {
  const list = await composio.connectedAccounts.list({
    userIds: [userId],
    toolkitSlugs: ['github'],
    statuses: ['ACTIVE'],
  });
  if (list.items?.[0]) return;

  const request = await composio.toolkits.authorize(userId, 'github');
  throw new Error(`Connect GitHub first: ${request.redirectUrl}`);
}

// The local sandbox session. Create a normal Composio session yourself with
// `workbench.enable: false` (Composio won't run code for you), then hand that
// session to the helper, which validates it's local and gives you the pieces to
// run code yourself, wherever you choose.
async function createWorkbench() {
  const session = await composio.create(userId, {
    toolkits: ['github'],
    workbench: { enable: false },
  });
  return experimental_createLocalWorkbenchSession(composio, session);
  // returns { helperSource, env }:
  //   helperSource: a Python helper exposing run_composio_tool / invoke_llm / web_search
  //   env:          the variables that helper needs to reach Composio from inside your box
}

export async function runReview(repo: string, pr: number) {
  await requireGithubConnection();
  const workbench = await createWorkbench();

  // Start a sandbox you own, inject the helper, and pass the env. E2B is just
  // the sample runner; swap createE2bSandbox for any box that honors the same
  // contract: write a file, set env, run a command, stream output, tear down.
  const sandbox = await createE2bSandbox({
    apiKey: process.env.E2B_API_KEY,
    helperSource: workbench.helperSource, // written as composio_helper.py
    env: workbench.env,
  });

  // Run the reviewer agent inside the sandbox and stream its output back. The
  // agent calls run_composio_tool from composio_helper.py, which routes GitHub
  // actions back through Composio under this user's connection.
  const task = `Review PR #${pr} on ${repo}. Run the repo's real checks in this sandbox.`;
  try {
    await sandbox.run('npx --yes tsx agent.ts', {
      env: { ...workbench.env, TASK: task, OPENAI_API_KEY: process.env.OPENAI_API_KEY },
      onStdout: (chunk) => process.stdout.write(chunk),
      onStderr: (chunk) => process.stderr.write(chunk),
    });
  } finally {
    await sandbox.teardown();
  }
}
```

## 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 the `composio_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:

> [!NOTE]
>
> The local PR reviewer browser is a documentation snapshot; a public repository is not available.

## Run it

Dry-run first to validate your input with no credentials, network calls, or sandbox startup, then run it for real:

```bash theme={null}
bun run review -- --repo ComposioHQ/composio --pr 123 --dry-run
bun run review -- --repo ComposioHQ/composio --pr 123
```

The host opens a local sandbox session, boots the sandbox, and runs the repo's real checks inside it, then posts one grounded comment, or nothing if it can't build the PR.
