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:

sandbox_repl.py
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:

Python
@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:

Python
        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

Re-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:

Python
@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:

Terminal
blade run sandbox_repl.py

You'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.

sandbox_repl.py
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

Contact the team

Loading the form…