fridge

Quickly start a Docker-based Python code execution sandbox for local development (e.g. executing code generated by your AI agent when developing locally). Made possible with uv and PEP 723 – Inline script metadata (up-to-date PyPA specs page).

Get started

Step 1: Clone the repo or actually only need to have the following files:

├── code_exec_client.py
├── Dockerfile
├── entrypoint.sh
└── server.py

(No need to pip install something or uv add something, the server is just built with Python standard lib socketserver.)

Step 2: Build a Docker image:

docker build -t fridge-code-exec-img .

Step 3: Up a container; tune the memory, cpu, pids, port, etc to needs:

docker run --rm \
  --name fridge \
  --memory="512m" \
  --cpus="0.5" \
  --pids-limit=100 \
  --read-only \
  --tmpfs /tmp:exec,nosuid,nodev \
  --tmpfs /home/appuser/.cache/uv:exec \
  -p 8080:8080 \
  fridge-code-exec-img

Step 4: Use the CodeExecutionClient from the code_exec_client.py in service functions, controllers, etc. Example client code below:

import logging

from code_exec_client import (
    CodeExecutionClient,
    ExecutionResult,
    ServerConnectionError,
    ServerResponseError,
)

logging.basicConfig(
    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
logger = logging.getLogger(__name__)

HOST, PORT = "localhost", 8080

SCRIPT_TO_EXECUTE = """
# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "youtube-transcript-api"
# ]
# ///

from youtube_transcript_api import YouTubeTranscriptApi

def fetch_transcript(url):
    video_id = url.split("v=")[1].split("&")[0] if "v=" in url else url.split("/")[-1]
    api = YouTubeTranscriptApi()
    transcript = api.get_transcript(video_id)
    return " ".join([f"{t['text']}" for t in transcript])

url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
print(fetch_transcript(url))

"""

def main():
    try:
        with CodeExecutionClient(HOST, PORT) as client:
            result = client.execute(SCRIPT_TO_EXECUTE)
            print_result(result)
    except (ServerConnectionError, ServerResponseError):
        logger.exception("Execution failed: %s")

if __name__ == "__main__":
    main()

Notes

The SCRIPT_TO_EXECUTE must have a PEP 723 metadata on top of the script. Working towards automatically adding this metadata so that the raw script from somewhere (e.g. LLM-generated) can be passed directly to the .execute method. For now I'm prompting the coder LLM like:

write python script to fetch the transcript of a youtube video given the URL. dont write code that requires user input. dont add docstrings and code comments. use f-strings for concatenation. when done writing the code, add a PEP 723 inline metadata on the top of the script indicating the packages to be installed with their versions; always use python >=3.12.

example PEP 723 block:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "numpy==2.3.5"
# ]
# ///