CodeBox.run_script() reads from host filesystem, not from inside VM

[yingjunwu]

Description

run_script(path) reads the script file from the host filesystem, not from inside the VM. This is counter-intuitive and undocumented — the docs show a pattern of creating a file inside the VM and then running it with run_script(), which fails.

Reproduction

import asyncio
import boxlite

async def main():
    async with boxlite.CodeBox() as codebox:
        # Create a script inside the VM
        await codebox.run("""
with open('/tmp/analysis.py', 'w') as f:
    f.write('import json\\nprint(json.dumps({"status": "ok"}))\\n')
""")
        # Try to run the script from VM path
        result = await codebox.run_script("/tmp/analysis.py")
        print(result)

asyncio.run(main())

Expected

run_script("/tmp/analysis.py") runs the script that was created inside the VM.

Actual

FileNotFoundError: [Errno 2] No such file or directory: '/tmp/analysis.py'

The error occurs on the host side, confirming run_script() tries to read from host filesystem.

Environment

• boxlite 0.5.10
• macOS Apple Silicon
• Python 3.12

Suggested fix

Either:

1. Make run_script() read from inside the VM (consistent with the name), or
2. Clearly document that run_script() reads from the host and sends content to the VM for execution

[yingjunwu]

Triage: ✅ Confirmed — P3, Low-hanging fruit (misleading API)

This is by design but poorly documented. run_script() reads the file on the host side (with open(script_path, "r")), then sends the contents to the VM via python -c. The name is misleading since it implies running a script inside the VM.

Fix in #244:

1. Updated run_script() docstring to clearly state it reads from the host filesystem
2. Added run_guest_script(guest_path) for running scripts that already exist inside the VM

Severity: Low — workaround is trivial (read file yourself and pass to run()), but the API confusion is real.

[yingjunwu]

Fix: #249