How to run Composio safely in a sandbox

As you can see below, there is a warning that you have keep a tab on the environment keys inside the sandbox including the composio key. So, if the sandbox is compromised you will have to rotate the composio key.

If a PR has some malicious prompt injection and your PR reviewer running inside the sandbox is tricked, it can leak the Composio key

Good news is that, with our vault feature you do not have to worry about it. Our sandbox will never even see the Composio Key. So its physically imposssible to leak it.

Composio also lets you turn that managed execution off and run the tools in a sandbox you own. That's the "local workbench" mode.

This is where you can use a sandbox you prefer. This is the guide that will help you or your agents to use Composio from a InstaVM sandbox.

Start by defining a Composio Session

A local workbench session is just a normal Composio session with execution turned off:

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

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

const session = await composio.create('my-user', {
  toolkits: ['github'],
  workbench: { enable: false }, // Composio won't run code for you
});

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

You get back two things:

• helperSource — a Python helper exposing run_composio_tool, invoke_llm, and web_search. Your agent imports it and calls those.
• env — the variables the helper needs to reach Composio, including your COMPOSIO_API_KEY.

Composio still does discovery, auth, and the actual tool execution on its side. Your job is only to run the helper somewhere. That somewhere is InstaVM.

The key problem - do not do this

That env contains your project COMPOSIO_API_KEY. The obvious move is to set it in the sandbox — as an env var, or worse, export COMPOSIO_API_KEY=... && run. Either way the plaintext key is now inside the VM. Anything that runs there can read it, including the untrusted PR code you clone and build. Putting it in the VM environment instead of a command line is tidier, but it's the same secret sitting in the same blast radius.

The key doesn't need to be in the box. It only needs to be on the requests that leave the box, headed for Composio. That's exactly what a vault is for.

The vault: inject on egress, not in the VM

InstaVM's vault stores the credential server-side (encrypted, never returned by the API again) and injects it into outbound requests at the egress proxy. A transparent MITM sits on the VM's network edge: when the sandbox makes a request to a bound host, the proxy adds the auth header on the way out. The VM never sees the secret.

Composio expects header (x-api-key). Set it up once. Store the key, then bind it to Composio's backend host with that header:

from instavm import InstaVM

client = InstaVM(api_key=INSTAVM_KEY, auto_start_session=False)

vault = client.create_vault("composio")
client.add_vault_credential(vault["id"], name="COMPOSIO_API_KEY", value=COMPOSIO_KEY)

client.add_vault_service(
    vault["id"],
    host="backend.composio.dev",
    auth_config={"type": "api-key", "header": "x-api-key", "key": "COMPOSIO_API_KEY"},
)

Now boot a VM with that vault attached. Attaching the vault is what arms the transparent MITM for those hosts:

vm = client.vms.create(
    vm_lifetime_seconds=600,
    vault_ids=[vault["id"]],
    egress_policy={
        "allow_https": True,
        "allow_http": False,
        "allow_package_managers": False,
        "allowed_domains": ["backend.composio.dev"],
        "allowed_cidrs": [],
    },
)

Make a request to Composio from inside InstaVM

From inside that box, with no key anywhere in the environment, a request to Composio just works:

$ echo "[$COMPOSIO_API_KEY]"
[]
$ curl -s -o /dev/null -w "%{http_code}\n" https://backend.composio.dev/api/v3/toolkits
200

The 200 comes back because the proxy injected the key in transit. The vault's request log records it as ingress: mitm against the bound service — and if code in the box sends its own placeholder x-api-key, the proxy overwrites it with the real one. So Composio's helper can keep reading COMPOSIO_API_KEY from the environment as it always does; you just hand it a harmless placeholder, and the real key lives in the vault.

I would highly recommend everyone using a 3rd party sandbox with Composio to switch to this pattern.

Keep egress narrow

Notice the egress policy above allows exactly one host. That's the other half of the story: even if untrusted PR code wanted to exfiltrate whatever it could, the box can only talk to backend.composio.dev, and the only credential in play is one it can use but never read. Rotate it from the vault whenever you want without touching the sandbox.

The round trip

Upload the helper, drop in an agent, and let it call a tool:

# agent.py, running inside the InstaVM sandbox
import composio_helper as helper

data, error = helper.run_composio_tool("GITHUB_GET_THE_AUTHENTICATED_USER", arguments={})
print(error or data["data"]["login"])

The call leaves the sandbox, the proxy stamps the real Composio key onto it, it hits Composio, runs the GitHub action under the user's connection, and comes back. Tool execution happens in a box you control; discovery and auth stay managed by Composio; the secret stays in the vault.

host (session, execution off)
  → InstaVM VM (vault attached, egress locked, no key inside)
  → run_composio_tool
  → egress proxy injects x-api-key
  → Composio (resolve + execute)
  → result

You bring a Composio key and a place to run code. Composio brings the tools. InstaVM keeps the key out of the sandbox entirely.

Try it

Every InstaVM account gets free compute to start. Grab a key at instavm.io, a Composio key at composio.dev, put the Composio key in a vault, and run your agent in a VM instead of on your laptop.