Local sandbox

A local sandbox runs your agent's code in your own infrastructure instead of Composio's hosted remote sandbox, so code execution never leaves your security boundary.

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.

If none of that applies, use the remote sandbox. It's the same helper surface with no infrastructure to run.

Create a local sandbox session

A local sandbox session is a session created with the remote sandbox turned off. Set workbench.enable: false, then pass the session to experimental_createLocalWorkbenchSession (from the @composio/experimental package), which returns the two pieces you run yourself.

import { Composio } from '@composio/core';
import { experimental_createLocalWorkbenchSession } from '@composio/experimental/workbench';

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });

// Create the session with the remote sandbox disabled, so code runs in your box.
const session = await composio.create('user_123', {
  toolkits: ['github'],
  workbench: { enable: false },
});

const { helperSource, env } = await experimental_createLocalWorkbenchSession(composio, session);

You get back two things:

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 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:

from composio_helper import run_composio_tool, invoke_llm, web_search

response, error = run_composio_tool(
    "GITHUB_GET_A_PULL_REQUEST",
    {"owner": "composiohq", "repo": "composio", "pull_number": 1},
)

Every 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 project COMPOSIO_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.

Next