CodeBox: state does not persist between run() calls

[yingjunwu]

Description

The documentation claims state persists between run() calls (code-execution.mdx Step 5, core-concepts.mdx). In practice, each run() call starts a fresh Python process — variables and functions defined in a previous run() are not available.

Reproduction

import asyncio
import boxlite

async def main():
    async with boxlite.CodeBox() as codebox:
        await codebox.run("""
import json

def process(data):
    return {k: v * 2 for k, v in data.items()}
""")
        result = await codebox.run("""
output = process({"a": 1, "b": 2, "c": 3})
print(json.dumps(output))
""")
        print(result)

asyncio.run(main())

Expected

Second run() can access process() and json from the first run(). Output: {"a": 2, "b": 4, "c": 6}

Actual

NameError: name 'process' is not defined

Environment

• boxlite 0.5.10
• macOS Apple Silicon
• Python 3.12

Notes

Files written to disk do persist (same VM), but Python-level state (variables, imports, function definitions) does not carry over between run() calls.

[yingjunwu]

Triage: ✅ Confirmed — P2, Documentation bug (behavior is by design)

This is a documentation bug, not a code bug. Each run() call executes python -c <code>, which spawns a new Python process. This is the correct and expected behavior for containerized execution — each exec is isolated.

The guest agent (executor.rs) spawns a new process for every exec() call by design. Files written to disk do persist (same VM filesystem), but Python-level state (variables, imports, function definitions) does not carry over.

Recommended fix:

• Short-term: Update documentation to remove the false state persistence claim. Document that each run() is a fresh process.
• Long-term (if desired): Implementing true state persistence would require a persistent Python REPL session (e.g., python -i with stdin piping, or a Jupyter kernel). This is a significant engineering effort requiring guest agent changes.

Severity: Medium — users can work around this by combining all code in a single run() call.