feat(sdk): expose resize_tty in Python SDK and add AI agent guide by yingjunwu · Pull Request #220 · boxlite-ai/boxlite

yingjunwu · 2026-02-09T05:28:34Z

Summary

Expose resize_tty(rows, cols) in Python SDK — adds Rust binding (PyExecution) and sync wrapper (SyncExecution), enabling terminal resizing for TTY-enabled executions without the stty stdin workaround
Add AI agent integration guide — comprehensive standalone guide covering recommended configuration, concurrency model, timeout/zombie prevention, security boundaries, file transfer patterns, and terminal resizing
Add tests — 12 new tests covering API surface (unit) and resize_tty behavior (integration for both async and sync APIs)

Implements #218 items #4 and #6.

Changed files

File	Change
`sdks/python/src/exec.rs`	Add `resize_tty` method to `PyExecution`
`sdks/python/boxlite/sync_api/_execution.py`	Add `resize_tty` to `SyncExecution`
`sdks/python/README.md`	Document `resize_tty` in Execution methods
`docs/reference/python/README.md`	Add `resize_tty` to methods table
`docs/guides/ai-agent-integration.md`	New comprehensive guide
`docs/guides/README.md`	Cross-reference to new guide
`sdks/python/tests/test_exec.py`	API surface unit tests
`sdks/python/tests/test_resize_tty.py`	Async integration tests
`sdks/python/tests/test_sync_api.py`	Sync integration tests

Test plan

cargo check -p boxlite-python — compiles without errors
cargo fmt --check -p boxlite-python — formatting passes
make dev:python — full build succeeds
pytest tests/test_exec.py — 29/29 passed (includes test_execution_has_resize_tty)
Integration tests (test_resize_tty.py, test_sync_api.py resize tests) — require VM environment

🤖 Generated with Claude Code

Provide a persistent interactive terminal example for installing Claude Code and document it in the examples README. Co-authored-by: Cursor <[email protected]>

Rename file to remove "ubuntu" misnomer, remove unused BoxOptions, consolidate imports, and improve documentation. Co-Authored-By: Claude Opus 4.6 <[email protected]>

…on guide Add resize_tty(rows, cols) binding to PyExecution (Rust) and SyncExecution (Python sync wrapper), enabling terminal resizing for TTY-enabled executions without the stty stdin workaround. Also add a comprehensive AI agent integration guide covering configuration, concurrency, timeouts, security, and file transfer patterns. Closes #218 items #4 and #6. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot

Pull request overview

This PR extends the BoxLite Python SDK to support resizing PTY/TTY-backed executions via a new Execution.resize_tty(rows, cols) API, and adds documentation aimed at AI-agent integration patterns (including timeouts, concurrency, security, and terminal sizing).

Changes:

Add resize_tty(rows, cols) to the native Python Execution binding and the sync wrapper.
Document resize_tty in Python SDK docs and add a new AI agent integration guide.
Add unit + integration tests for the new API surface and behavior, plus a new interactive example script.

Reviewed changes

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

Show a summary per file

File	Description
`sdks/python/src/exec.rs`	Adds the Rust→PyO3 binding for `Execution.resize_tty()`
`sdks/python/boxlite/sync_api/_execution.py`	Adds sync wrapper method `SyncExecution.resize_tty()`
`sdks/python/README.md`	Documents `resize_tty` in the Execution method list
`docs/reference/python/README.md`	Adds `resize_tty` to the Python reference methods table
`docs/guides/ai-agent-integration.md`	New AI agent integration guide (timeouts, concurrency, security, resizing)
`docs/guides/README.md`	Adds a cross-link to the new AI agent guide
`sdks/python/tests/test_exec.py`	Adds API surface checks for `resize_tty` export
`sdks/python/tests/test_resize_tty.py`	New async integration tests for resize behavior
`sdks/python/tests/test_sync_api.py`	Adds sync integration tests for resize behavior
`examples/python/interactive_claude_example.py`	New interactive Claude Code install terminal example
`examples/python/README.md`	Adds the new interactive Claude example to the examples index

Comments suppressed due to low confidence (1)

sdks/python/tests/test_exec.py:152

This import of module boxlite is redundant, as it was previously imported on line 10.

        import boxlite

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

Copilot · 2026-02-09T05:37:03Z

sdks/python/tests/test_sync_api.py

+        box = shared_sync_runtime.create(boxlite.BoxOptions(image="alpine:latest"))
+        execution = box.exec("sh", tty=True)
+
+        # Should not raise
+        execution.resize_tty(40, 120)
+


SyncBox.exec() (used by box here) does not accept a tty keyword argument (its signature is exec(cmd, args=None, env=None)), so this call will raise TypeError and the test will fail. Either extend the sync API to support tty (and forward it to the native async Box.exec(..., tty=...)) or adjust the test to create a TTY execution through an API that actually supports it.

Copilot · 2026-02-09T05:37:03Z

sdks/python/tests/test_sync_api.py

+        box = shared_sync_runtime.create(boxlite.BoxOptions(image="alpine:latest"))
+        execution = box.exec("sh", tty=True)
+
+        # Small terminal
+        execution.resize_tty(24, 80)
+        # Large terminal
+        execution.resize_tty(100, 300)
+        # Minimum dimensions
+        execution.resize_tty(1, 1)


Same issue as above: SyncBox.exec() does not currently accept tty=True, so this test will error before exercising resize_tty. Add tty: bool = False to the sync exec wrapper (and pass it through) or avoid using tty in sync tests until the API supports it.

examples/python/README.md

Copilot · 2026-02-09T05:37:03Z

examples/python/README.md

+### interactive_claude_ubuntu_example.py
+Interactive terminal for Claude Code:
+- Persistent box with a bash shell
+- Install Claude Code directly in the terminal
+- Reuse the same box across sessions
+


This section header and description reference interactive_claude_ubuntu_example.py, but the added example file in this PR is named interactive_claude_example.py. Update the README section title/filename (or rename the script) so users can find and run the example.

docs/reference/python/README.md

Copilot · 2026-02-09T05:37:04Z

docs/guides/ai-agent-integration.md

+| `seccomp_enabled` | `bool` | Syscall filtering (Linux only) |
+| `max_open_files` | `int \| None` | Limit open file descriptors |
+| `max_file_size` | `int \| None` | Maximum file size in bytes |
+| `max_processes` | `int \| None` | Maximum number of processes |
+| `max_memory` | `int \| None` | Maximum virtual memory in bytes |
+| `max_cpu_time` | `int \| None` | Maximum CPU time in seconds |
+| `network_enabled` | `bool` | Allow network access from sandbox |
+| `close_fds` | `bool` | Close inherited file descriptors |
+


SecurityOptions.network_enabled is documented in the Python bindings as “macOS only” (see sdks/python/src/options.rs field doc). This guide currently presents it as a general network isolation switch; please clarify platform support/behavior (and what to do on Linux) to avoid misleading security guidance.

docs/guides/ai-agent-integration.md

Copilot · 2026-02-09T05:37:04Z

sdks/python/README.md

+- `resize_tty(rows: int, cols: int) -> None`
+  Resize PTY terminal window (async). Only works with TTY-enabled executions.
+


While updating this Execution docs section, note that the examples in this README call box.exec("python", "-c", ...) using varargs. The native Box.exec binding is exec(command, args=None, env=None, tty=False) (args must be a list), so the varargs form is misleading and can behave incorrectly (e.g., splitting strings into characters). Please update the examples/signature description in this section to match the actual API.

Co-authored-by: Copilot <[email protected]>

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Co-authored-by: Copilot <[email protected]>

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

- Resolve merge conflict in examples/python/README.md (keep main's version) - Add tty parameter to SyncBox.exec() to match native Box.exec() API - Add macOS-only annotation for network_enabled in AI agent guide - Fix missing blank line before Resource Limits heading in guide - Remove redundant boxlite import in test_exec.py Co-Authored-By: Claude Opus 4.6 <[email protected]>

DorianZheng

LGTM

yingjunwu and others added 3 commits February 5, 2026 19:02

feat(examples): add interactive Claude Code box example

448276e

Provide a persistent interactive terminal example for installing Claude Code and document it in the examples README. Co-authored-by: Cursor <[email protected]>

fix(examples): address review feedback on interactive Claude example

41bee0c

Rename file to remove "ubuntu" misnomer, remove unused BoxOptions, consolidate imports, and improve documentation. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Copilot AI review requested due to automatic review settings February 9, 2026 05:28

Copilot started reviewing on behalf of yingjunwu February 9, 2026 05:28 View session

Copilot AI reviewed Feb 9, 2026

View reviewed changes

Apply suggestions from code review

01f594c

Co-authored-by: Copilot <[email protected]>

Copilot AI review requested due to automatic review settings February 9, 2026 05:55

Copilot AI reviewed Feb 9, 2026

View reviewed changes

Apply suggestions from code review

036f8bd

Co-authored-by: Copilot <[email protected]>

Copilot AI review requested due to automatic review settings February 9, 2026 05:57

Copilot AI reviewed Feb 9, 2026

View reviewed changes

DorianZheng approved these changes Feb 9, 2026

View reviewed changes

DorianZheng merged commit 72a6935 into main Feb 9, 2026
19 checks passed

DorianZheng deleted the feat/interactive-claude-example branch February 9, 2026 07:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(sdk): expose resize_tty in Python SDK and add AI agent guide#220

feat(sdk): expose resize_tty in Python SDK and add AI agent guide#220
DorianZheng merged 6 commits intomainfrom
feat/interactive-claude-example

yingjunwu commented Feb 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 9, 2026

Uh oh!

Copilot AI Feb 9, 2026

Uh oh!

Uh oh!

Copilot AI Feb 9, 2026

Uh oh!

Uh oh!

Copilot AI Feb 9, 2026

Uh oh!

Uh oh!

Copilot AI Feb 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

DorianZheng left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		- `resize_tty(rows: int, cols: int) -> None`
		Resize PTY terminal window (async). Only works with TTY-enabled executions.

Conversation

yingjunwu commented Feb 9, 2026

Summary

Changed files

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

DorianZheng left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants