Run persistent E2B cloud sandboxes from Convex actions with a V8-compatible client for shell commands, files, preview hosts, and AI agent tools.
npm install @e2b/convexA tableless Convex component that provides a V8-compatible E2B client for managing persistent cloud sandboxes inside Convex actions. It handles sandbox lifecycle (create, pause, resume), shell command execution, file operations, and preview hosts without requiring the full Node-oriented E2B SDK. Includes first-class integrations for Convex Agent and the Vercel AI SDK via optional subpackage imports.
The @e2b/convex component exposes a runCommand method on the E2B client that executes shell commands inside a persistent cloud sandbox from a Convex action. You identify the sandbox with a scope and key pair, and calls with the same pair reuse the existing sandbox automatically. Command output is bounded to 32 KiB per stream and capped at 1 MiB total.
The @e2b/convex component integrates with the Convex Agent framework via createAgentTools from @e2b/convex/agent, which creates thread-aware sandbox tools with optional approval rules. Sandboxes pause on timeout and resume automatically when any operation targets them, so agent sessions can persist across multiple turns without manual lifecycle management.
Using @e2b/convex, you can expose E2B sandbox operations as AI SDK tools inside any Convex action via createAiSdkTools from @e2b/convex/ai. This gives the agent access to shell commands and file operations inside an isolated cloud environment. File tool access is restricted to /home/user and /tmp by default, and the getHost preview capability is opt-in.
The @e2b/convex package ships a V8-compatible E2B client that includes only the Process and Filesystem protocol descriptors needed by the component, avoiding Node built-ins and the full E2B SDK. This makes it compatible with the Convex JavaScript runtime, which does not support Node-only packages.
No. @e2b/convex ships its own V8-compatible E2B client that includes only the Process and Filesystem protocol descriptors the component needs. The full Node-oriented E2B SDK is not imported into the Convex runtime. The pinned e2b package is a development-only dependency used as a protocol source.
Sandboxes in @e2b/convex are identified by a scope and key pair you provide. If a sandbox with that identity is already running or paused, getOrCreate returns it instead of creating a new one. Paused sandboxes resume automatically when any operation targets them, which also restarts E2B billing for that session.
File reads in @e2b/convex default to 64 KiB and are capped at 1 MiB. File writes are capped at 4 MiB. File tools are restricted to /home/user and /tmp unless the configuration is explicitly changed. These limits apply to both direct action usage and agent tool integrations.
Yes. @e2b/convex provides separate integration entry points: createAgentTools from @e2b/convex/agent for Convex Agent, and createAiSdkTools from @e2b/convex/ai for standard AI SDK usage inside any Convex action. Each integration requires its own peer dependency (ai, and optionally @convex-dev/agent), but the core package has no runtime dependency on either.
The package is pre-1.0 and the authors recommend validating it against your E2B template and network policy before deploying to production. The component uses E2B's public APIs and CI rejects Node built-ins or full-SDK imports in the emitted Convex runtime. A scheduled real-service test monitors for protocol drift.