BLAXEL_SANDBOX_SETUP.md

Blaxel Sandbox Setup for Manim + FFmpeg

This guide walks you through creating and deploying a custom Blaxel sandbox with Manim and FFmpeg pre-installed for rendering animations in the cloud.

Overview

Instead of installing Manim and FFmpeg at runtime (which is slow and unreliable), we create a custom Docker image with all dependencies pre-installed. This image is then deployed to Blaxel as a sandbox template that can be instantiated on-demand for rendering.

Why Custom Image?

• Faster: No installation overhead at runtime
• Reliable: Pre-tested environment with all dependencies
• FFmpeg Support: System-level dependencies properly configured
• LaTeX Support: Optional but recommended for mathematical animations

Prerequisites

1. Docker installed locally (for testing)
2. Blaxel CLI installed: npm install -g @blaxel/cli
3. Blaxel Account with API key from blaxel.ai
4. Environment Variables set:

   export BLAXEL_API_KEY="your_api_key_here"
   export BL_WORKSPACE="your_workspace_id"  # Optional
   

Step 1: Build and Test Locally

Before deploying to Blaxel, test the image locally:

# Build the Docker image
make -f Makefile.sandbox build

# Run the container locally
make -f Makefile.sandbox run

# Test the sandbox API (in another terminal)
make -f Makefile.sandbox test

# View logs
make -f Makefile.sandbox logs

# Stop the container
make -f Makefile.sandbox stop

Manual Testing

You can also test manually:

# 1. Check Manim installation
curl -X POST http://localhost:8080/process \
  -H "Content-Type: application/json" \
  -d '{
    "command": "python3 -c \"import manim; print(manim.__version__)\"",
    "waitForCompletion": true
  }'

# 2. Check FFmpeg installation
curl -X POST http://localhost:8080/process \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ffmpeg -version",
    "waitForCompletion": true
  }'

# 3. Test a simple Manim render
curl -X POST http://localhost:8080/process \
  -H "Content-Type: application/json" \
  -d '{
    "command": "python3 -c \"from manim import *; print(\\\"Manim import successful\\\")\"",
    "waitForCompletion": true
  }'

Step 2: Deploy to Blaxel

Once local testing is successful, deploy to Blaxel:

# Login to Blaxel (if not already logged in)
bl login

# Deploy the sandbox template
make -f Makefile.sandbox deploy

# Or manually:
bl deploy

This will:

1. Build your Docker image
2. Push it to Blaxel's registry
3. Create a sandbox template named based on your project

Step 3: Get the Image ID

After deployment, retrieve your custom image ID:

# List your sandboxes
bl get sandboxes

# Get specific sandbox details with image ID
bl get sandbox manim-sandbox -ojson | jq -r '.[0].spec.runtime.image'

The output will look something like:

blaxel/your-workspace/manim-sandbox:latest

Save this image ID - you'll need it in the next step.

Step 4: Update Renderer Code

Update the renderer to use your custom image instead of the generic one.

Open mcp_servers/renderer.py and find the line around line 440:

sandbox = await SandboxInstance.create(
    {
        "name": f"manim-render-{sanitized_scene_name}",
        "image": "blaxel/py-app:latest",  # Change this line
        "memory": 4096,
    }
)

Replace "blaxel/py-app:latest" with your custom image ID:

sandbox = await SandboxInstance.create(
    {
        "name": f"manim-render-{sanitized_scene_name}",
        "image": "blaxel/your-workspace/manim-sandbox:latest",  # Your custom image
        "memory": 4096,
    }
)

Better approach: Use an environment variable:

import os

MANIM_SANDBOX_IMAGE = os.getenv(
    "MANIM_SANDBOX_IMAGE", 
    "blaxel/your-workspace/manim-sandbox:latest"
)

sandbox = await SandboxInstance.create(
    {
        "name": f"manim-render-{sanitized_scene_name}",
        "image": MANIM_SANDBOX_IMAGE,
        "memory": 4096,
    }
)

Then add to your .env:

MANIM_SANDBOX_IMAGE=blaxel/your-workspace/manim-sandbox:latest

Step 5: Test End-to-End

Now test the complete pipeline:

# Run your animation generation
python main_new.py

Or if using Gradio:

python app.py

The system should now:

1. Create a sandbox using your custom image
2. Upload the Manim code
3. Execute the render command (Manim and FFmpeg already available)
4. Download the rendered video

Configuration Options

Memory Allocation

For complex animations, you may need more memory:

sandbox = await SandboxInstance.create(
    {
        "name": f"manim-render-{sanitized_scene_name}",
        "image": MANIM_SANDBOX_IMAGE,
        "memory": 8192,  # Increased from 4096
    }
)

Timeout Settings

Adjust timeouts for longer renders:

render_result = await sandbox.process.exec({
    "name": "render-manim",
    "command": cmd,
    "wait_for_completion": True,
    "timeout": 600000,  # 10 minutes (in milliseconds)
})

Custom LaTeX Packages

If you need additional LaTeX packages, update the Dockerfile:

RUN apt-get install -y \
    texlive-full \  # Install full LaTeX distribution
    && rm -rf /var/lib/apt/lists/*

Then rebuild and redeploy:

make -f Makefile.sandbox rebuild
make -f Makefile.sandbox deploy

Troubleshooting

Issue: "Sandbox creation failed"

Solution: Check your API key and workspace:

echo $BLAXEL_API_KEY
echo $BL_WORKSPACE

Re-login if needed:

bl login

Issue: "Image not found"

Solution: Verify the image was deployed:

bl get sandboxes

If not listed, redeploy:

bl deploy

Issue: "Manim not found in sandbox"

Solution: Verify the image has Manim:

# Connect to a running sandbox
bl connect sandbox your-sandbox-name

# Inside the sandbox, test:
python3 -c "import manim; print(manim.__version__)"

Issue: "FFmpeg not found"

Solution: Similar to above, verify FFmpeg:

bl connect sandbox your-sandbox-name
ffmpeg -version

Issue: "Render timeout"

Solutions:

1. Increase memory allocation (try 8192 MB)
2. Increase timeout value
3. Simplify the animation
4. Use lower quality settings

Issue: "Build fails locally"

Solution: Check Docker logs:

docker logs manim-sandbox-test

Common issues:

• Missing entrypoint.sh file (copy it first)
• Permissions on entrypoint.sh (should be executable)
• Docker daemon not running

Cost Optimization

To minimize costs:

1. Use TTL policies: Sandboxes auto-delete when idle

   sandbox = await SandboxInstance.create({
       "name": f"manim-render-{sanitized_scene_name}",
       "image": MANIM_SANDBOX_IMAGE,
       "memory": 4096,
       "lifecycle": {
           "expiration_policies": [
               {"type": "ttl-idle", "value": "5m", "action": "delete"}
           ]
       }
   })
   

2. Delete after use: Explicitly delete sandboxes when done

   try:
       # Render animation
       pass
   finally:
       await SandboxInstance.delete(sandbox.metadata.name)
   

3. Reuse sandboxes: For batch processing, reuse the same sandbox

Advanced: Multiple Sandbox Versions

You can maintain multiple versions:

# Tag with version
docker build -f Dockerfile.sandbox -t manim-sandbox:v1.0 .

# Deploy specific version
bl deploy --tag v1.0

Then specify in code:

"image": "blaxel/your-workspace/manim-sandbox:v1.0"

Next Steps

1. ✅ Build and test locally
2. ✅ Deploy to Blaxel
3. ✅ Update renderer code with image ID
4. ✅ Test end-to-end rendering
5. ✅ Configure cost optimization
6. 🎉 Start generating animations!

Resources

• Blaxel Sandboxes Documentation
• Blaxel CLI Reference
• Manim Documentation
• FFmpeg Documentation

Support

If you encounter issues:

1. Check the Blaxel dashboard for sandbox logs
2. Review the deployment logs: bl logs
3. Join Blaxel Discord/Support channels
4. Check GitHub issues for similar problems