Developer docs / AI Fabric tutorials
Code interpreter sandbox
- Sandbox
- GPU
- Image DSL
The moment you let an LLM write code, you have to decide where to run it. Running model-generated Python directly on your own machine is a non-starter: a single bad line could read your files, open a socket, or never terminate. What you want is a disposable box that executes the code, hands you the result, and can't reach anything it shouldn't.
In this tutorial you'll build exactly that: a function that runs untrusted Python inside a AI Fabric Sandbox. The sandbox is isolated at the OS kernel level by gVisor, with no network access and no path to the host filesystem, so even hostile code stays trapped. You get back the exit code, stdout, and stderr to inspect.
Before you start
You need the AI Fabric CLI installed and authenticated: run blade setup once. No GPU is required here: the sandbox runs on CPU, and we build its environment from fabric/base, the lightweight Python catalog image, plus a few scientific libraries.
Create the app and sandbox image
Create a file called code_interpreter.py. The image you define here is the environment the generated code will see, so give it whatever libraries you expect the LLM to reach for. We start from fabric/base and add NumPy, Matplotlib, and SciPy:
import bladekit
app = bladekit.app("code-interpreter")
image = (
bladekit.Image.from_catalog("fabric/base")
.pip_install("numpy", "matplotlib", "scipy")
)Spin up an isolated sandbox
A plain AI Fabric function takes the code as a string and opens a sandbox with bladekit.Sandbox.create(...). Used as a context manager, the sandbox is created on entry and torn down when the with block exits, so nothing lingers:
@app.function(timeout=300)
def run_generated_code(code: str) -> dict:
"""Execute LLM-generated code in an isolated sandbox and return its output."""
# gVisor (runsc) is the default: kernel-level isolation for untrusted code.
# The sandbox has no network access and cannot touch the host filesystem.
with bladekit.Sandbox.create(
image=image,
timeout=60, # auto-terminate after 60 s
# runtime="runsc" # default (gVisor): kernel-level isolation for
# # untrusted code. GPU sandboxes need a runsc-nvproxy
# # node; CPU sandboxes (like this one) run anywhere.
) as sb:Write the code in, then run it
A sandbox is a tiny filesystem plus a way to start processes. Write the generated code to a file with sb.write_file, then launch it with sb.exec and proc.wait() for it to finish:
# Write the generated code into the sandbox filesystem
sb.write_file("/work/solution.py", code.encode())
# Execute it
proc = sb.exec("python", "/work/solution.py")
proc.wait()Note that write_file takes bytes, which is why we code.encode() first. The sb.exec(...) call is python /work/solution.py inside the guest, the same command you'd type at a shell.
Collect the result
Read the streams off the finished process and return them. A non-zero exit is not an exception: it is data. An agent driving this loop wants to read the stderr and try again, not crash:
stdout = proc.stdout.read().decode("utf-8", errors="replace")
stderr = proc.stderr.read().decode("utf-8", errors="replace")
return {
"exit_code": proc.returncode,
"stdout": stdout,
"stderr": stderr,
}Call it with some LLM code
A local_entrypoint runs on your laptop. Here we stand in for an LLM with a code string, ship it to the function with .remote(...), and print what came back:
@app.local_entrypoint()
def main():
# Example: run code that the LLM produced
llm_code = """
import numpy as np
a = np.random.randn(1000, 1000)
result = np.linalg.eigvalsh(a @ a.T)
print(f"Max eigenvalue: {result.max():.4f}")
print("Done!")
"""
result = run_generated_code.remote(llm_code)
print(f"Exit code: {result['exit_code']}")
print(f"Output:\n{result['stdout']}")
if result["stderr"]:
print(f"Stderr:\n{result['stderr']}")Run it
Execute the program with the AI Fabric CLI:
blade run code_interpreter.pyThe sandbox boots, runs the NumPy snippet, and prints the largest eigenvalue along with an exit code of 0. To run many code snippets at once (say, several candidate solutions from an agent), call run_generated_code.map(list_of_code_strings) and AI Fabric fans each one out to its own sandbox in parallel.
Take it for a spin
Everything above in one file, ready to run.
import bladekit
app = bladekit.app("code-interpreter")
image = (
bladekit.Image.from_catalog("fabric/base")
.pip_install("numpy", "matplotlib", "scipy")
)
@app.function(timeout=300)
def run_generated_code(code: str) -> dict:
"""Execute LLM-generated code in an isolated sandbox and return its output."""
# gVisor (runsc) is the default: kernel-level isolation for untrusted code.
# The sandbox has no network access and cannot touch the host filesystem.
with bladekit.Sandbox.create(
image=image,
timeout=60, # auto-terminate after 60 s
# runtime="runsc" # default (gVisor): kernel-level isolation for
# # untrusted code. GPU sandboxes need a runsc-nvproxy
# # node; CPU sandboxes (like this one) run anywhere.
) as sb:
# Write the generated code into the sandbox filesystem
sb.write_file("/work/solution.py", code.encode())
# Execute it
proc = sb.exec("python", "/work/solution.py")
proc.wait()
stdout = proc.stdout.read().decode("utf-8", errors="replace")
stderr = proc.stderr.read().decode("utf-8", errors="replace")
return {
"exit_code": proc.returncode,
"stdout": stdout,
"stderr": stderr,
}
@app.local_entrypoint()
def main():
# Example: run code that the LLM produced
llm_code = """
import numpy as np
a = np.random.randn(1000, 1000)
result = np.linalg.eigvalsh(a @ a.T)
print(f"Max eigenvalue: {result.max():.4f}")
print("Done!")
"""
result = run_generated_code.remote(llm_code)
print(f"Exit code: {result['exit_code']}")
print(f"Output:\n{result['stdout']}")
if result["stderr"]:
print(f"Stderr:\n{result['stderr']}")Concepts used: Cold start, Run