E2B compatibility

The E2B gatewayThe kibotos-e2b service, which translates requests from the E2B SDK into the native API so that programs written for E2B can use Kibotos. kibotos-e2b translates the E2B control API and the envd protocol into the Kibotos native API, so programs written with the official E2B SDK run on Kibotos. These pages show which SDK calls and endpoints work, how they behave on Kibotos, and what is not supported.

Compatible versionsCopy Anchor Link

E2B compatibility is measured against the official JavaScript SDK:

• The version that passed acceptance is e2b@2.46.1.
• The compatibility target is e2b@2.49.1. It has not passed acceptance yet.
• The capabilities on these pages are those verified with 2.46.1.

ExampleCopy Anchor Link

The example needs Node.js 22 or later and e2b@2.46.1. It reads the connection settings from these environment variables:

When the deployment's certificate is not from a public CA, also set Node.js's own NODE_EXTRA_CA_CERTS to the CA file.

The following example creates a short-lived sandbox, runs a command, and then deletes the sandbox. lifecycle explicitly chooses deletion on expiration:

import { readFile } from 'node:fs/promises';
import { Sandbox } from 'e2b';

const domain = process.env.E2B_DOMAIN;
const sandbox = await Sandbox.create(process.env.E2B_TEMPLATE || 'kibotos-minimal', {
  apiKey: (await readFile(process.env.E2B_API_KEY_FILE, 'utf8')).trim(),
  domain,
  apiUrl: process.env.E2B_API_URL || `https://api.${domain}`,
  secure: true,
  timeoutMs: 60_000,
  lifecycle: { onTimeout: 'kill', autoResume: false },
});
try {
  const result = await sandbox.commands.run('printf kibotos-ready');
  console.log(result.stdout);
} finally {
  await sandbox.kill();
}

Save the example as example.mjs, then install the SDK and run it:

npm install e2b@2.46.1
E2B_DOMAIN=sandbox.example.com E2B_API_KEY_FILE="$HOME/.config/e2b/api-key" node example.mjs

By default, the SDK creates sandboxes that require public internet access. If you do not need network access, add allowInternetAccess: false to the create options. The address families and outbound capabilities a deployment supports depend on the node configuration. For background on IPv4 support, see #59. For the outbound policy, see Network.

What you can useCopy Anchor Link

Each row is one area of the SDK. The area links to the page that describes its behavior on Kibotos.

Capabilities the gateway does not provide return an explicit error. See Not supported.

Not supportedCopy Anchor Link

An unsupported capability always fails with an error. The gateway never ignores it and reports success, so your code finds out at once.

How unsupported calls failCopy Anchor Link

• The gateway returns HTTP 501 with the response body {"code":501,"message":"unimplemented: <capability name> is not supported by the core gateway"}.
• The SDK throws SandboxError with the message 501: unimplemented: <capability name> is not supported by the core gateway.
• The gateway returns 501 instead of 404 because the official SDK interprets 404 as "sandbox does not exist".
• Endpoints the gateway does not implement at all, such as GET /sandboxes, sandbox logs, and template build and listing, return a plain 404, which the SDK reports as a missing sandbox.

EndpointsCopy Anchor Link

The following routes exist but always return 501. They return immediately after authentication, without calling the native API or changing gateway state.

When the deployment is not connected to an instance metrics store, GET /sandboxes/metrics and GET /sandboxes/{id}/metrics also return 501, with the capability name metrics. See Metrics.

For progress on these capabilities, see #81, #82, #85, and #86.

Create optionsCopy Anchor Link

The official SDK sends every option you configure. An option the gateway cannot implement makes the create request fail, instead of being ignored with a 201. The create response does not echo these fields, so a failure is the only way you would know the option did not take effect. The check runs before any state is written and before any native API call.

• Every option in the table returns 501 with the response body described above.
• The error message has the same format as other creation errors, with an extra create sandbox: prefix.
• A field that is absent, null, an empty object, or an empty array counts as unset, and creation proceeds normally.

Other calls and optionsCopy Anchor Link

How the gateway worksCopy Anchor Link

The gateway has no storage of its own:

• E2B-specific information (metadata, creation options, volume names) is written into the labels and annotations of the WorkspaceA complete Linux environment for an AI Agent, running in its own MicroVM. Agents read and write files, run processes, and start services in it without affecting the host or other Workspaces. or VolumeA persistent volume that exists independently of any Workspace. A Workspace binds at most one Volume, mounted at /data by default. along with the create command, and ctrl keeps it.
• The envd token and traffic token are not stored. The gateway derives them from the gateway key and the sandbox ID.
• Each gateway instance caches only what it reads from ctrl, so several instances can serve at the same time. Each instance needs its own Operator identity; see Prepare the identity and start.

Creating and stopping sandboxes, running commands, and file operations all become calls to the Kibotos native API. The gateway itself runs no VMs. It does not emulate capabilities that the native API does not yet provide: it never copies disks, calls private VMM interfaces, or writes to the ctrl database, and it keeps no sandbox lifecycle state of its own.

• For deployment, see Install the E2B gateway and Reinstalling the gateways.
• For the code structure and tests, see E2B gateway code structure and tests.

Next stepsCopy Anchor Link

• Migrate from E2B: move an existing program step by step.
• Sandboxes and lifecycle: creation, pause and resume, and expiration on Kibotos.
• Commands and files: running processes and transferring files.
• Core concepts: Workspaces, Volumes, and their states.
• Guarantees and limits: when data is kept.