Developer docs / AI Fabric tutorials
Stateful code interpreter (REPL)
- Sandbox
- Image DSL
A code interpreter that throws away its environment after every snippet is fine for one-shot tasks, but real agents work in turns. Define x in one step, transform it in the next, print a result in the third. That only works if the variables survive between executions. You need a REPL, not a one-shot.
In this tutorial you'll keep a single sandbox alive across a whole sequence of code snippets, so state carries from one turn to the next. The approach: open the sandbox once, accumulate each turn's code into a script, and re-run the growing script every turn, giving the LLM the feeling of a persistent Python session.
Before you start
You need the AI Fabric CLI installed and authenticated: run blade setup once. No GPU is required: this runs on CPU. The sandbox environment is a small debian_slim image with NumPy, pandas, and Matplotlib so the REPL has something interesting to compute with.
Create the app and REPL image
Create sandbox_repl.py. The image defines what's available inside the REPL, so add whatever your turns will import:
import bladekit
app = bladekit.app("sandbox-repl")
repl_image = (
bladekit.Image.debian_slim(python_version="3.12")
.pip_install("numpy", "pandas", "matplotlib")
)Open one long-lived sandbox
The key difference from a one-shot interpreter: the with bladekit.Sandbox.create(...) block wraps the entire loop, not a single execution. One sandbox stays up for the whole session, so its filesystem persists across turns. We seed an empty state file to act as the REPL's memory:
@app.function(timeout=300)
def repl_session(code_turns: list[str]) -> list[dict]:
"""Execute a list of code snippets in the same sandbox. State is shared."""
results = []
with bladekit.Sandbox.create(image=repl_image, timeout=240) as sb:
# Write a persistent state file to simulate REPL memory
sb.write_file("/work/state.py", b"# shared state\n")Accumulate and re-run each turn
For each turn, read the script so far, append the new code, write it back, and run the whole thing again. Because every prior line is still in the file, a variable defined in turn 0 is in scope when turn 2 runs. That's what makes the state feel persistent:
for i, code in enumerate(code_turns):
# Append code to state and re-run the full script each turn
existing = sb.read_file("/work/state.py").decode()
sb.write_file("/work/state.py", (existing + "\n" + code + "\n").encode())
proc = sb.exec("python", "/work/state.py")
proc.wait()
results.append({
"turn": i,
"exit_code": proc.returncode,
"stdout": proc.stdout.read().decode(),
})
return resultsRe-running the full script each turn means earlier prints execute again too. For an agent that reads only the latest turn's intent, that's usually harmless, and it keeps the state model simple. When the with block exits, the sandbox is cleaned up automatically.
Drive a session
A local_entrypoint builds a list of turns (note how y in turn 1 depends on x from turn 0), ships them to the function with .remote(...), and prints each turn's output:
@app.local_entrypoint()
def main():
turns = [
"import numpy as np; x = np.array([1, 2, 3]); print('x defined')",
"y = x * 2; print(f'y = {y}')",
"print(f'sum = {y.sum()}')",
]
for r in repl_session.remote(turns):
print(f"Turn {r['turn']}: {r['stdout'].strip()}")Run it
Execute the program with the AI Fabric CLI:
blade run sandbox_repl.pyYou'll see each turn build on the last (x defined, then y = [2 4 6], then sum = 12), proving the state survived across executions inside the one sandbox. This is the building block for a multi-turn code interpreter you can hand to an agent.
Take it for a spin
Everything above in one file, ready to run.
import bladekit
app = bladekit.app("sandbox-repl")
repl_image = (
bladekit.Image.debian_slim(python_version="3.12")
.pip_install("numpy", "pandas", "matplotlib")
)
@app.function(timeout=300)
def repl_session(code_turns: list[str]) -> list[dict]:
"""Execute a list of code snippets in the same sandbox. State is shared."""
results = []
with bladekit.Sandbox.create(image=repl_image, timeout=240) as sb:
# Write a persistent state file to simulate REPL memory
sb.write_file("/work/state.py", b"# shared state\n")
for i, code in enumerate(code_turns):
# Append code to state and re-run the full script each turn
existing = sb.read_file("/work/state.py").decode()
sb.write_file("/work/state.py", (existing + "\n" + code + "\n").encode())
proc = sb.exec("python", "/work/state.py")
proc.wait()
results.append({
"turn": i,
"exit_code": proc.returncode,
"stdout": proc.stdout.read().decode(),
})
return results
@app.local_entrypoint()
def main():
turns = [
"import numpy as np; x = np.array([1, 2, 3]); print('x defined')",
"y = x * 2; print(f'y = {y}')",
"print(f'sum = {y.sum()}')",
]
for r in repl_session.remote(turns):
print(f"Turn {r['turn']}: {r['stdout'].strip()}")Concepts used: Cold start, Run