fix(python): clarify run_script() reads from host, add run_guest_script() by yingjunwu · Pull Request #249 · boxlite-ai/boxlite

yingjunwu · 2026-02-12T23:39:56Z

Summary

Clarify run_script() docstring: it reads from the host filesystem, not from inside the container
Add run_guest_script() method for executing scripts that exist inside the VM
Mirror both changes in SyncCodeBox to maintain API parity

Closes #235

Dependency

After PR #248 is merged (which changes run() to return stdout only), run_guest_script() and SyncCodeBox.run_guest_script() should be updated to also return stdout only for consistency. Currently they return stdout + stderr to match the current run() behavior.

Test plan

Verify run_script() still works with host-side scripts
Verify run_guest_script() works with container-side scripts
Verify SyncCodeBox mirrors the same methods

🤖 Generated with Claude Code

Copilot

Pull request overview

This PR addresses issue #235 by clarifying that run_script() reads from the host filesystem and adding a new run_guest_script() method to execute scripts that exist inside the VM. The change improves the API's clarity and provides the missing functionality users expected.

Changes:

Updated run_script() docstring to explicitly state it reads from the host filesystem and sends contents to the container
Added new run_guest_script() method to execute Python scripts that exist inside the container
Added cross-reference documentation linking the two methods

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-12T23:43:31Z

sdks/python/boxlite/codebox.py


        Returns:
-            Execution output as a string
+            Execution stdout as a string


The docstring states "Execution stdout as a string" but the implementation returns stdout + stderr (via the run() method at line 89). This should be updated to "Execution output as a string (stdout + stderr)" to match the actual behavior and be consistent with the run() method's documentation at line 56.

Suggested change

Execution stdout as a string

Execution output as a string (stdout + stderr)

Copilot · 2026-02-12T23:43:31Z

sdks/python/boxlite/codebox.py

+            Execution stdout as a string
+        """
+        result = await self.exec("/usr/local/bin/python", guest_script_path)
+        return result.stdout


The run_guest_script() method returns only stdout, which is inconsistent with run() and run_script() that both return stdout + stderr. This inconsistency could lead to unexpected behavior where stderr output (including error messages) is silently discarded. Consider changing line 102 to return result.stdout + result.stderr to maintain consistency across all execution methods.

Suggested change

Execution stdout as a string

"""

result = await self.exec("/usr/local/bin/python", guest_script_path)

return result.stdout

Execution output as a string (stdout + stderr)

"""

result = await self.exec("/usr/local/bin/python", guest_script_path)

return result.stdout + result.stderr

Copilot · 2026-02-12T23:43:31Z

sdks/python/boxlite/codebox.py

+            guest_script_path: Path to the script inside the container
+
+        Returns:
+            Execution stdout as a string


The docstring states "Execution stdout as a string" but for consistency with the run() and run_script() methods, this should document what is actually returned. Update the Returns section to match the actual implementation (currently stdout only, but should likely be stdout + stderr for consistency).

…pt() run_script() reads the script from the host filesystem via open(), then sends the content to the VM. The name and docstring were misleading — users expected it to run a script inside the VM. Fix: - Update run_script() docstring to clearly state it reads from the host filesystem and point to run_guest_script() as alternative - Add run_guest_script() for running scripts already inside the VM Closes #235 Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-12T23:57:06Z

sdks/python/boxlite/codebox.py

+            guest_script_path: Path to the script inside the container
+
+        Returns:
+            Execution output as a string (stdout + stderr)


Missing example in docstring. The run_guest_script method would benefit from a usage example similar to run_script, showing how to create a script inside the container and then execute it. This would help users understand the difference between run_script and run_guest_script more clearly.

Suggested change

Execution output as a string (stdout + stderr)

Execution output as a string (stdout + stderr)

Example:

Create a script inside the container and then execute it:

>>> async with CodeBox() as cb:

... # Create the script inside the container filesystem

... await cb.exec(

... "sh",

... "-lc",

... "printf 'print(\\\"Hello from guest script!\\\")' > /tmp/guest_script.py",

... )

... # Now run the script that lives inside the container

... result = await cb.run_guest_script("/tmp/guest_script.py")

... print(result)

Hello from guest script!

Copilot · 2026-02-12T23:57:06Z

sdks/python/boxlite/sync_api/_codebox.py

+            guest_script_path: Path to the script inside the container
+
+        Returns:
+            Execution output as a string (stdout + stderr)


Missing example in docstring. The run_guest_script method would benefit from a usage example similar to run_script, showing how to create a script inside the container and then execute it. This would help users understand the difference between run_script and run_guest_script more clearly.

Suggested change

Execution output as a string (stdout + stderr)

Execution output as a string (stdout + stderr)

Example:

with SyncCodeBox() as box:

# Create a script inside the container

box.exec(

"sh",

"-lc",

"cat << 'EOF' > /tmp/guest_script.py\n"

"print('Hello from guest script!')\n"

"EOF",

)

# Run the script that now exists in the container filesystem

result = box.run_guest_script("/tmp/guest_script.py")

print(result) # Hello from guest script!

yingjunwu · 2026-02-12T23:58:11Z

Self-review after revision: This PR is now correct, with one documented dependency.

The initial version had 3 bugs that have been fixed:

Bug 1 — Wrong docstring. run_script() docstring claimed "Returns: Execution stdout as a string" but self.run() on this branch returns stdout + stderr. Fixed to say "Execution output as a string (stdout + stderr)".

Bug 2 — Inconsistent run_guest_script() return. run_guest_script() originally returned only result.stdout while run() returns stdout + stderr. Fixed to return result.stdout + result.stderr.

Bug 3 — SyncCodeBox not updated. SyncCodeBox didn't get run_guest_script() or the updated run_script() docstring, breaking the "API mirrors async CodeBox exactly" contract. Fixed: both methods are now mirrored.

Dependency on #248: This PR is self-consistent against main. However, after PR #248 is merged (which changes run() to return stdout only), run_guest_script() in both async and sync APIs should be updated to also return stdout only. This is documented in the PR description.

DorianZheng · 2026-02-13T01:50:54Z

this seems no need

yingjunwu · 2026-02-13T02:13:36Z

Closing — run_guest_script() interface is not needed.

Copilot AI review requested due to automatic review settings February 12, 2026 23:39

yingjunwu mentioned this pull request Feb 12, 2026

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

Open

Copilot started reviewing on behalf of yingjunwu February 12, 2026 23:40 View session

Copilot AI reviewed Feb 12, 2026

View reviewed changes

yingjunwu force-pushed the fix/run-script-host-clarify branch from 6815c26 to bf2527d Compare February 12, 2026 23:46

Copilot AI review requested due to automatic review settings February 12, 2026 23:53

yingjunwu force-pushed the fix/run-script-host-clarify branch from bf2527d to 6008091 Compare February 12, 2026 23:53

Copilot started reviewing on behalf of yingjunwu February 12, 2026 23:53 View session

yingjunwu mentioned this pull request Feb 12, 2026

fix(python): return only stdout from CodeBox.run() #248

Merged

5 tasks

Copilot AI reviewed Feb 12, 2026

View reviewed changes

yingjunwu closed this Feb 13, 2026

yingjunwu deleted the fix/run-script-host-clarify branch February 13, 2026 02:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(python): clarify run_script() reads from host, add run_guest_script()#249

fix(python): clarify run_script() reads from host, add run_guest_script()#249
yingjunwu wants to merge 1 commit intomainfrom
fix/run-script-host-clarify

yingjunwu commented Feb 12, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

Copilot AI Feb 12, 2026

Uh oh!

yingjunwu commented Feb 12, 2026

Uh oh!

DorianZheng commented Feb 13, 2026

Uh oh!

yingjunwu commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	Execution stdout as a string
	Execution output as a string (stdout + stderr)

-            Execution output as a string (stdout + stderr)
+            Execution output as a string (stdout + stderr)
+        Example:
+            Create a script inside the container and then execute it:
+            >>> async with CodeBox() as cb:
+            ...     # Create the script inside the container filesystem
+            ...     await cb.exec(
+            ...         "sh",
+            ...         "-lc",
+            ...         "printf 'print(\\\"Hello from guest script!\\\")' > /tmp/guest_script.py",
+            ...     )
+            ...     # Now run the script that lives inside the container
+            ...     result = await cb.run_guest_script("/tmp/guest_script.py")
+            ...     print(result)
+            Hello from guest script!

-            Execution output as a string (stdout + stderr)
+            Execution output as a string (stdout + stderr)
+        Example:
+            with SyncCodeBox() as box:
+                # Create a script inside the container
+                box.exec(
+                    "sh",
+                    "-lc",
+                    "cat << 'EOF' > /tmp/guest_script.py\n"
+                    "print('Hello from guest script!')\n"
+                    "EOF",
+                )
+                # Run the script that now exists in the container filesystem
+                result = box.run_guest_script("/tmp/guest_script.py")
+                print(result)  # Hello from guest script!

Conversation

yingjunwu commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Dependency

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

yingjunwu commented Feb 12, 2026

Uh oh!

DorianZheng commented Feb 13, 2026

Uh oh!

yingjunwu commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yingjunwu commented Feb 12, 2026 •

edited

Loading