Troubleshooting custom Docker image deployment issues

Diagnose sandbox API, Dockerfile path, build timeout, entrypoint, missing build tools, and logging issues in custom Blaxel sandbox images.

Custom Docker images for sandboxes can fail during build or deployment because of missing files, dependencies, or startup configuration. Use the matching section below to identify and resolve the failure.

Include the sandbox API

Every custom sandbox image must include the sandbox-api binary:

COPY --from=ghcr.io/blaxel-ai/sandbox:latest /sandbox-api /usr/local/bin/sandbox-api

Correct Dockerfile paths

When you run bl deploy, Blaxel archives all files in your current directory and sends them to the build server. If the Dockerfile is in a subdirectory such as agent-container/, write COPY paths relative to the uploaded build context.

Incorrect:

COPY agent-container/base-package.json package.json

Correct:

COPY base-package.json package.json

Reduce build timeouts

Internal timeout increases usually resolve build timeout failures automatically. If timeouts continue:

• Install fewer packages in the Dockerfile
• Use a smaller base image where possible
• Combine RUN instructions to reduce image layers

Fix custom entrypoints

If your entrypoint checks ports with nc, install netcat:

RUN apt-get update && apt-get install -y netcat-openbsd

Use 127.0.0.1 instead of localhost in Debian-based images because localhost may not resolve correctly.

If you do not need custom initialization, remove the custom script and start the sandbox API directly:

ENTRYPOINT ["/usr/local/bin/sandbox-api"]

This entrypoint works when you start other processes programmatically through the SDK or API.

Install system libraries

Compilation errors such as unable to find library -lgcc indicate that the image lacks development packages. Install the required toolchain:

RUN apt-get update && apt-get install -y \
    build-essential \
    libc6-dev \
    libgcc-12-dev \
    pkg-config

These packages are available during the image build. Image slimming removes compilers before the sandbox starts. Disable slimming if the running sandbox needs them.

Keep build tools available at runtime

A package can install successfully in the Dockerfile and be missing when the sandbox starts. Image slimming runs after the Docker build and removes build-time files, including make, gcc, g++, and cmake. Those tools still work in RUN steps.

To keep them, disable slimming in blaxel.toml:

[build]
slim = false

See image slimming for the paths this pass removes, and for the effect on image size and boot time.

Configure the environment

Docker ENV variables are available to the entrypoint and its child processes. Extend variables such as PATH with export in your entrypoint script:

#!/bin/sh
export PATH="/root/.cargo/bin:/root/.local/bin:$PATH"
export LIBRARY_PATH="/usr/lib/x86_64-linux-gnu:/lib/x86_64-linux-gnu:$LIBRARY_PATH"
/usr/local/bin/sandbox-api

Inspect build logs

Use the CLI to view the complete build process and deployment errors:

bl logs sandbox sandbox-name

Docker sandbox tutorial

Learn how to run Docker workloads in a sandbox.

Sandbox processes

Learn how to start and manage processes programmatically.