About this Install Guide

This guide shows you how to install and use the tool with the most common configuration. For advanced options and complete reference information, see the official documentation. Some install guides also include optional next steps to help you explore related workflows or integrations.

E2B provides isolated Linux sandboxes for AI agents and generated code. A self-hosted E2B installation runs each sandbox in a Firecracker microVM and exposes the E2B API and SDK interfaces.

You’ll install E2B Embed , the official single-host deployment, on an Arm Linux system. E2B Embed uses Docker Compose to run the control plane, Firecracker orchestrator, dashboard, and supporting services on one host.

These instructions are for Ubuntu 24.04 LTS on aarch64. E2B requires kernel-based virtual machine (KVM) and Linux kernel 6.10 or later on Arm.

Before you begin

Use a dedicated Arm Linux host with KVM, such as an Arm AGI CPU platform or an Arm-based bare-metal cloud instance. The installation loads kernel modules and reserves huge pages. It creates host directories and network namespaces, and changes host networking and system settings.

You need the following prerequisites:

  • Ubuntu 24.04 LTS on aarch64
  • Linux kernel 6.10 or later
  • KVM and the TUN/TAP device
  • A 4 KiB page-size kernel and cgroup v2
  • Sudo access
  • Docker Engine 27 or later, and Docker Compose 2.24 or later
  • 12 GiB of RAM and 20 GiB of free disk space, as recommended by E2B
  • Internet access to Docker Hub, Google Artifact Registry, Google Cloud Storage and GitHub

The default configuration reserves 4 GiB of RAM as huge pages for sandboxes.

Check the Arm Linux host

Print the architecture, kernel version, page size, and cgroup filesystem type:

    

        
        
uname -m
uname -r
getconf PAGESIZE
stat -fc %T /sys/fs/cgroup

    

Confirm that the output shows the following values:

  • aarch64 for the architecture
  • Kernel version 6.10 or later
  • 4096 for the page size
  • cgroup2fs for the cgroup filesystem
Note
  • The E2B Embed version used in this guide doesn’t support 64 KiB-page kernels on Arm. E2B requires a 4 KiB-page kernel, and Firecracker currently supports only 4 KiB host and guest kernels on aarch64. Support for 64 KiB pages is currently tracked as a Firecracker feature request .
  • If getconf PAGESIZE returns 65536, switch to a 4 KiB-page kernel before continuing. For more information, see E2B Embed host requirements .

If Ubuntu 24.04 is still using its original 6.8 kernel, install the current hardware enablement kernel:

    

        
        
sudo apt update
sudo apt install -y linux-generic-hwe-24.04
sudo reboot

    

After the system restarts, run uname -r again and confirm that the active kernel is version 6.10 or later.

Check KVM and TUN/TAP

Confirm that the KVM and TUN/TAP devices exist:

    

        
        
ls -l /dev/kvm /dev/net/tun

    

Check that the current user can access KVM:

    

        
        
if [ -c /dev/kvm ] && [ -r /dev/kvm ] && [ -w /dev/kvm ]; then
    echo "KVM device is accessible"
else
    echo "STOP: resolve KVM availability or permissions before continuing"
fi

    

The expected output is:

    

        
        KVM device is accessible

        
    

If /dev/kvm belongs to the kvm group but your user doesn’t have access, add the user to the group:

    

        
        
sudo usermod -aG kvm "$USER"

    

Activate the new group membership:

    

        
        
newgrp kvm

    

The command starts a new shell with kvm as the active group.

Install the host packages

Install the packages required by E2B and its verification steps:

    

        
        
sudo apt update
sudo apt install -y ca-certificates curl e2fsprogs iproute2 iptables python3-venv rsync

    

Confirm Docker installation

If Docker isn’t already installed, follow the Docker Engine install guide .

Add your user to the docker group so that the E2B commands don’t require sudo:

    

        
        
sudo usermod -aG docker "$USER"

    

Activate the new group membership:

    

        
        
newgrp docker

    

Print the installed versions:

    

        
        
docker version --format 'Docker Engine {{.Server.Version}}'
docker compose version

    

The output is similar to:

    

        
        Docker Engine 29.8.0
Docker Compose version v5.5.1

        
    

Confirm that Docker Engine is version 27 or later and Docker Compose is version 2.24 or later.

Install E2B Embed

Create a directory for the Compose deployment:

    

        
        
mkdir -p ~/e2b
cd ~/e2b

    
Note

These commands pin E2B runtime commit 780b991b5e4d814f5a7ef625a21033d75416e0f1 because main changes over time and release tag 2026.30 doesn’t contain the Embed Compose files. This revision provides matching compose.yaml and .env files, pins E2B API v0.30.0, and was validated on an Arm AGI CPU. If you select another commit from the E2B runtime repository , download both files from that commit.

Download the Compose file and its matching environment file:

    

        
        
e2b_runtime_commit=780b991b5e4d814f5a7ef625a21033d75416e0f1
curl -fsSLo compose.yaml "https://raw.githubusercontent.com/e2b-dev/runtime/${e2b_runtime_commit}/embed/compose/compose.yaml"
curl -fsSLo .env "https://raw.githubusercontent.com/e2b-dev/runtime/${e2b_runtime_commit}/embed/compose/.env"

    

Validate the Compose configuration:

    

        
        
docker compose config --quiet

    

The command exits without output when the configuration is valid.

Start E2B and wait for the base sandbox template to become ready:

    

        
        
docker compose up -d --wait

    

The first run performs host checks, configures the host, and downloads the Firecracker artifacts and container images. It also initializes the databases and builds the base template. The download and build can take several minutes.

Warning

The E2B Compose file publishes multiple service ports on every host interface. Keep the host behind a firewall. Expose ports 3000, 3001, and 3002 only to trusted clients, if needed. In particular, don’t expose the unauthenticated orchestrator API on port 5008.

Verify the installation

Check the service state:

    

        
        
docker compose ps

    

In the output, confirm that the ready service has a status beginning with Up. E2B uses this service to indicate that the stack and the base template are usable. The other long-running services should also show Up and, when a health check is configured, (healthy).

Include the one-time setup services in the output:

    

        
        
docker compose ps -a

    

The following setup services should show Exited (0):

  • preflight
  • host-setup
  • fetch-artifacts
  • Database migrators
  • seed
  • base-template

A nonzero exit code or a long-running service that isn’t Up indicates a failed installation.

Run the packaged smoke test:

    

        
        
docker compose --profile test run --rm smoke

    

The test creates a sandbox through the E2B SDK and runs a command in the Firecracker microVM. It reaches a test service through the client proxy and deletes the sandbox. Docker prints container status updates before the test result.

The final line of the output is similar to:

    

        
        smoke: ok sandbox=i7hkvuw9l8pybg2bfreo8 port 8080 reached through http://127.0.0.1:3002

        
    

The sandbox ID differs on each run. Confirm that the final line begins with smoke: ok and reports that port 8080 was reached through http://127.0.0.1:3002.

Run Python in an E2B sandbox

Load the local E2B API endpoints and generated team API key into the current shell:

    

        
        
eval "$(docker compose exec ready cat /run/e2b/sdk.env)"

    

The API key is a secret. Don’t print or store the command output in logs.

Create a Python virtual environment and install the SDK version tested by the pinned E2B deployment:

    

        
        
python3 -m venv .venv
.venv/bin/pip install e2b==2.46.0

    

Run a Python program that creates a sandbox, prints its architecture, performs a calculation, and deletes the sandbox:

    

        
        
.venv/bin/python - <<'PY'
from e2b import Sandbox

sandbox = Sandbox.create("base")
try:
    result = sandbox.commands.run(
        "uname -m && python3 -c 'print(6 * 7)'"
    )
    print(result.stdout, end="")
finally:
    sandbox.kill()
PY

    

The expected output is:

    

        
        aarch64
42

        
    

This confirms that the E2B API created an Arm64 Firecracker sandbox and ran commands inside it.

Troubleshoot E2B installation

If docker compose up fails, identify the failing service:

    

        
        
docker compose ps -a

    

Read the logs for the setup services:

    

        
        
docker compose logs preflight host-setup fetch-artifacts base-template

    

Look for a line beginning with FIX:, correct the reported problem, and run docker compose up -d --wait again. The setup steps are idempotent and skip work that already succeeded.

If sandbox creation fails on Arm with Failed to UFFD object, the running kernel lacks the userfaultfd write-protect support that E2B needs. Install the Ubuntu 24.04 hardware enablement kernel, reboot, and confirm that uname -r reports kernel 6.10 or later.

If the stack reports insufficient huge pages, check the current allocation:

    

        
        
grep -E 'HugePages_Total|HugePages_Free|Hugepagesize' /proc/meminfo

    

The default HUGEPAGES=2048 reserves 2048 pages of 2 MiB each, or 4 GiB. On a host with less memory, lower HUGEPAGES in .env and run docker compose up -d --wait again. A 512 MiB base sandbox needs 256 of the 2 MiB huge pages.

If the smoke test fails, inspect the main runtime logs:

    

        
        
docker compose logs api orchestrator client-proxy

    

After a host reboot, return to ~/e2b. Run docker compose up -d --wait to restore the host networking state that’s required by E2B.

Next steps

You can now use the E2B SDKs to run AI agent code in self-hosted Firecracker microVMs on Arm Linux.

For configuration, upgrades, security considerations, and sandbox limits, see the E2B Embed Docker Compose documentation .


Give feedback

How would you rate this tool quick-install guide?