E2B Integration

Use the native E2B SDK to create and operate your sandbox. APIZ supplies credential issuance and an optional installation command; no sandbox object is passed to APIZ. You retain images, files, commands, timeouts and deletion.

Prerequisites And Installation

First follow the Python installation or TypeScript installation. Install the optional provider package in that same host environment:

# In the virtual environment created by the Python guide
python -m pip install e2b==2.49.1
# In your Node host project
npm install [email protected]

These are tested native SDK versions, not a promise of all future versions. Configure the four host APIZ values APIZ_USER_API_KEY, APIZ_SERVER_URL, APIZ_TEAM_ID, APIZ_CLIENT_ID from the language tutorial. Additionally set E2B_API_KEY on the host. Provider credentials never go to the guest. Your Client must already have the intended Bindings and Policies configured.

The sandbox needs sh, tar, a supported downloader, CA certificates, a writable temporary directory and outbound access to APIZ and its CLI downloads. Native creation options must be chosen by the caller; APIZ does not create a provider template or bypass firewalls.

Python: Create, Grant, Run, Revoke, Delete

Save this as host.py in your host project. With the variables exported, run python host.py in that project with your virtual environment active. This is a live readiness exercise that creates a cloud sandbox; it does not make an upstream service request. Output from CLI inspect is captured.

import os

from apiz.management import Management
from apiz.access import issue_access
from apiz.cli import install_command
from e2b import Sandbox

with Management(
    api_key=os.environ["APIZ_USER_API_KEY"],
    server_url=os.environ["APIZ_SERVER_URL"],
    team_id=os.environ["APIZ_TEAM_ID"],
) as api:
    sandbox = Sandbox.create(api_key=os.environ["E2B_API_KEY"], timeout=600)
    try:
        sandbox.commands.run(install_command(server_url=api.server_url), timeout=120)
        with issue_access(
            api, client_id=os.environ["APIZ_CLIENT_ID"], ttl_seconds=600
        ) as access:
            command = "/tmp/apiz/bin/apiz --output json client handoff inspect"
            result = sandbox.commands.run(command, envs=access.export_env(), timeout=30)
            if result.exit_code != 0:
                raise RuntimeError("Guest command failed")
        print("PASS: CLI access ready and credential group revoked")
    finally:
        sandbox.kill()

TypeScript SDK: Native Node Host

Save as host.mjs in the Node project where you installed both packages. With variables exported, run node host.mjs, or put them in a local .env and run node --env-file=.env host.mjs. This uses the same live readiness flow.

import { Management } from "@apiz/sdk/management";
import { issueAccess } from "@apiz/sdk/access";
import { installCommand } from "@apiz/sdk/cli";
import { Sandbox } from "e2b";

/** @param {string} name */
function required(name) {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}

const api = new Management({
  apiKey: required("APIZ_USER_API_KEY"),
  serverUrl: required("APIZ_SERVER_URL"),
  teamId: required("APIZ_TEAM_ID"),
});
try {
  const sandbox = await Sandbox.create({
    apiKey: required("E2B_API_KEY"),
    timeoutMs: 600_000,
  });
  try {
    await sandbox.commands.run(installCommand({ serverUrl: api.serverUrl }), {
      timeoutMs: 120_000,
    });
    const access = await issueAccess(api, {
      clientId: required("APIZ_CLIENT_ID"),
      ttlSeconds: 600,
    });
    await access.withAccess(async () => {
      const command = "/tmp/apiz/bin/apiz --output json client handoff inspect";
      const result = await sandbox.commands.run(command, {
        envs: access.exportEnv(),
        timeoutMs: 30_000,
      });
      if (result.exitCode !== 0) throw new Error("Guest command failed");
    });
    console.log("PASS: CLI access ready and credential group revoked");
  } finally {
    await sandbox.kill();
  }
} finally {
  await api.close();
}

Run Your Agent Or The Official-Tool Guest

After sandbox creation and before granting access, use the provider's native file API to upload your agent. For the shared S3 guest, read the guest_s3.py file from the guest tutorial into guest_source / guestSource, then upload it:

sandbox.files.write("/tmp/guest_s3.py", guest_source)

await sandbox.files.write("/tmp/guest_s3.py", guestSource);

Install Python/boto3 with native commands if the chosen image lacks them. Add APIZ_EXAMPLE_BINDING and APIZ_EXAMPLE_OBJECT_KEY through the grant's env option, together with APIZ_CLI_PATH=/tmp/apiz/bin/apiz, then replace the inspect command with python /tmp/guest_s3.py. The full setup/official SDK flow and expected Access Logs are explained in the Python tutorial. For your own agent, substitute its installed entrypoint and configure its official tools with APIZ CLI setup.

Async Python And Explicit Lifetime

Use native AsyncSandbox with AsyncManagement and issue_access_async; await files, commands and sandbox kill. The complete runnable async S3 example is linked in the Python guide.

with is optional: save the access object and call revoke() in finally; async callers use await access.revoke(). Inspect the cleanup report, especially unknown. TypeScript offers withAccess or explicit await access.revoke(). See Python lifecycle cases and TS lifecycle cases.

Provider-Specific Behavior

E2B uses envs for process environment in both languages. Python command timeouts are seconds; TypeScript uses timeoutMs. Use the base e2b SDK shown here; the separately named code-interpreter SDK is not required by this integration.

For a complete upstream request, run the Python S3 tutorial or TypeScript S3 tutorial. They include file upload, boto3 installation, CLI setup, the S3 call and caller-owned sandbox deletion.

Cleanup And Troubleshooting

Revoke before closing management/provider scopes. Sandbox destruction and APIZ revocation are independent operations; deleting a sandbox does not replace credential revocation. Expiry is a fallback, not proof that cleanup succeeded. Do not capture active credential environments in reusable snapshots.

Support And Validation Scope

Earlier E2B toolchain runs provide hosted evidence. The explicit installation/issuance flow has local coverage; that earlier run is not a fresh hosted pass for this revision.

Native types and local toolchain tests do not establish connectivity for your account. Before relying on the integration, run a representative allowed and denied service request, inspect Access Logs, and confirm revocation and native sandbox cleanup.

Native reference: E2B documentation.