Skip to main content

Using OpenKruise Agents Sandbox via E2B SDK

The sandbox-manager component of OpenKruise Agents supports two E2B integration protocols: native E2B protocol and private protocol.

The daily E2E regression tests for sandbox-manager are conducted with e2b-code-interpreter == 2.4.1 / e2b == 2.8.1, while compatibility is tested with the latest version. New features in updated versions will be adapted gradually. If you have feature requests, please submit an issue via GitHub.

Comparison between private protocol and native protocol:

Assuming your configured E2B_DOMAIN is your.domain.com

Native ProtocolPrivate Protocol
api.your.domain.comyour.domain.com/kruise/api
<port>-<sid>.your.domain.comyour.domain.com/kruise/<sid>/<port>

Important Notes on E2B_DOMAIN Environment Variable​

VERY IMPORTANT: The E2B_DOMAIN environment variable of sandbox-manager must be set to the same as the client. You can edit the deployment with kubectl edit deploy -n sandbox-system sandbox-manager

How to Configure E2B_DOMAIN for Server-side (sandbox-manager)​

You can configure the server-side E2B_DOMAIN by editing the following files before running make deploy-sandbox-manager:

How to Configure E2B_DOMAIN for Client-side (E2B SDK)​

You can configure the client-side E2B_DOMAIN by setting environment variables

export E2B_DOMAIN=your.domain.com

Special Scenarios​

1. Domain with Port​

For scenarios where the Ingress gateway does not use default HTTP ports (80 or 443). For example, if the domain is your.domain.com:8080:

  • Client-side: Set environment variable E2B_DOMAIN=your.domain.com:8080

  • Server-side:​

    In configuration_patch.yaml keep the port, set E2B Domain to your.domain.com:8080​

    In ingress_patch.yaml do not keep the port, replace replace.with.your.domain with your.domain.com

How to install a certificate​

If you need to access sandbox-manager via HTTPS, you need to install a TLS certificate. It is recommended to use a trusted certificate. If you don't have a trusted certificate, you can use a self-signed one, refer to the following docs:

You can install your certificate with the following command:

# ingress-nginx example, adjust according to your ingress controller
kubectl create secret tls sandbox-manager-tls \
          --cert=fullchain.pem \
          --key=privkey.pem -n sandbox-system

1. Integration using native protocol​

This is the most standard, native integration method, but also has the highest configuration threshold, generally requiring manual deployment.

  1. Client configuration environment variables:

    # The E2B_DOMAIN env of sandbox-manager container should be set to the same
    export E2B_DOMAIN=your.domain.com
    export E2B_API_KEY=<your-api-key>

  2. Resolve wildcard domain *.your.domain.com to sandbox-manager ingress endpoint with your DNS provider

  3. Install wildcard certificate *.your.domain.com

2. Private protocol HTTPS access from outside cluster​

This approach lowers the deployment barrier by replacing wildcard domain with a single domain.

  1. Client configuration environment variables: 
    # The E2B_DOMAIN env of sandbox-manager container should be set to the same
    export E2B_DOMAIN=your.domain.com
    export E2B_API_KEY=<your-api-key>
  2. Patch client: 
    from kruise_agents.patch_e2b import patch_e2b
    patch_e2b(https=True)
  3. Resolve single domain your.domain.com to sandbox-manager ingress endpoint with your DNS provider
  4. Install single domain certificate your.domain.com

3. Private protocol in-cluster access​

This approach enables rapid automated deployment without requiring domain and certificate configuration. Recommended for E2E testing scenarios only, or after rigorous evaluation.

  1. Ensure client(agent) and sandbox-manager are in the same cluster.
  2. Client configuration environment variables: 
    # The E2B_DOMAIN env of sandbox-manager container should be set to the same
    export E2B_DOMAIN=sandbox-manager.sandbox-system.svc.cluster.local
    export E2B_API_KEY=<your-api-key>
  3. Patch client and disable HTTPS: 
    from kruise_agents.patch_e2b import patch_e2b
    patch_e2b(https=False)

4. Port forward sandbox-manager to local machine​

  1. Client configuration environment variables: 
    # The E2B_DOMAIN env of sandbox-manager container should be set to the same
    export E2B_DOMAIN=localhost
    export E2B_API_KEY=<your-api-key>
  2. Port forward sandbox-manager to local machine: 
    sudo kubectl port-forward services/sandbox-manager 80:7788 -n sandbox-system
  3. Patch client: 
    from kruise_agents.patch_e2b import patch_e2b
    patch_e2b(https=False)

E2B Compatibility​

API CategoryAPICompatibility LevelNotes
Lifecycle ManagementcreatePartially CompatibleNetwork access control and resource management implementation pending
get_infoFully Compatible
listFully Compatible
killFully Compatible
pauseFully CompatibleDue to container ecosystem efficiency considerations, current pause implementation is asynchronous
connectFully Compatible
Code Executionrun_codeFully CompatibleRequires e2b-code-interpreter running in main container
Command Executioncommands.runFully CompatibleRequires runtime injection of envd component
File Systemread/writeFully CompatibleRequires runtime injection of envd component
upload_url/download_urlNot SupportedUpload/download via pre-signed URL implementation pending
Lifecycle Eventshttps://api.e2b.app/events/sandboxes/{sbx.sandbox_id}Not SupportedLifecycle events implementation pending
Template ManagementNot SupportedTemplate management implementation pending, recommend using container images as alternative
Last updated on by ZhaoQing7892