Resolving Sandbox Creation Issues

Last updated: March 24, 2026

If you're encountering sandboxes that fail to start properly, this is typically related to missing or incorrect entrypoint configuration in your template.

Common Symptoms

  • Sandboxes appear to be created but immediately fail or get deleted

  • 404 "Not Found" errors when trying to access the sandbox

Root Cause

This error occurs when your template doesn't have a proper entrypoint that keeps the sandbox API running. Even if your container is designed to run commands on-demand, the sandbox API must remain active for the sandbox to function properly.

Solution

Ensure your Dockerfile includes a proper ENTRYPOINT that keeps the sandbox API running. Here are the key points:

  1. Always include an entrypoint: Even if your container is meant to run commands via sandbox.process.exec, you still need the sandbox API to be running. Add the sandbox API binary to your Dockerfile like this:

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

  2. Use ENTRYPOINT instead of RUN for startup commands: If you need to run initialization commands, use a custom ENTRYPOINT script in your Dockerfile. For example: ENTRYPOINT ["/entrypoint.sh"] where entrypoint.sh starts sandbox-api, waits for it, then starts additional processes via the /process API. Note that custom entrypoint scripts must end with wait to keep the container alive.

  1. Don't leave entrypoint empty: An empty or non-functional entrypoint will cause the sandbox to fail during startup.

Additional Considerations

If you're building templates for on-demand command execution (like linting tools), remember that:

  • The sandbox needs a running process to maintain the API connection

  • You can still execute commands via sandbox.process.exec even with a running entrypoint

  • Blaxel sandboxes snapshot the entire VM state (memory + filesystem + running processes) when transitioning to standby, and restore it on resume in under 25ms

After updating your entrypoint configuration, rebuild your template and try creating a new sandbox.