boxd 0.3.0.dev1071__tar.gz → 0.3.0.dev1074__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. {boxd-0.3.0.dev1071/src/boxd.egg-info → boxd-0.3.0.dev1074}/PKG-INFO +105 -1
  2. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/README.md +104 -0
  3. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/pyproject.toml +1 -1
  4. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/__init__.py +10 -0
  5. boxd-0.3.0.dev1074/src/boxd/_generated/api_pb2.py +730 -0
  6. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/_generated/api_pb2_grpc.py +52 -0
  7. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/_mappers.py +22 -0
  8. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/_regions.py +13 -12
  9. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/_requests.py +109 -2
  10. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/_transport.py +24 -7
  11. boxd-0.3.0.dev1074/src/boxd/computer_use.py +914 -0
  12. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/models.py +67 -1
  13. boxd-0.3.0.dev1074/src/boxd/resources/computer.py +538 -0
  14. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/machines.py +3 -0
  15. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074/src/boxd.egg-info}/PKG-INFO +105 -1
  16. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd.egg-info/SOURCES.txt +4 -0
  17. boxd-0.3.0.dev1074/tests/test_computer.py +464 -0
  18. boxd-0.3.0.dev1074/tests/test_computer_use.py +821 -0
  19. boxd-0.3.0.dev1071/src/boxd/_generated/api_pb2.py +0 -696
  20. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/LICENSE +0 -0
  21. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/setup.cfg +0 -0
  22. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/_client.py +0 -0
  23. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/_credentials.py +0 -0
  24. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/_generated/__init__.py +0 -0
  25. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/_streaming.py +0 -0
  26. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/_urls.py +0 -0
  27. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/_version_check.py +0 -0
  28. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/errors.py +0 -0
  29. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/py.typed +0 -0
  30. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/__init__.py +0 -0
  31. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/account.py +0 -0
  32. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/credentials.py +0 -0
  33. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/disks.py +0 -0
  34. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/domains.py +0 -0
  35. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/fs.py +0 -0
  36. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/orgs.py +0 -0
  37. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/regions.py +0 -0
  38. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/snapshots.py +0 -0
  39. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/teams.py +0 -0
  40. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/resources/vars.py +0 -0
  41. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd/spec.py +0 -0
  42. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd.egg-info/dependency_links.txt +0 -0
  43. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd.egg-info/requires.txt +0 -0
  44. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/src/boxd.egg-info/top_level.txt +0 -0
  45. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_create_in_one_call.py +0 -0
  46. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_credentials.py +0 -0
  47. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_delete_self.py +0 -0
  48. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_fs.py +0 -0
  49. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_mappers.py +0 -0
  50. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_namespaces.py +0 -0
  51. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_python_versions.py +0 -0
  52. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_raw_key.py +0 -0
  53. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_regions.py +0 -0
  54. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_requests.py +0 -0
  55. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_spec.py +0 -0
  56. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_streaming.py +0 -0
  57. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_transport.py +0 -0
  58. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_urls.py +0 -0
  59. {boxd-0.3.0.dev1071 → boxd-0.3.0.dev1074}/tests/test_version_check.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: boxd
3
- Version: 0.3.0.dev1071
3
+ Version: 0.3.0.dev1074
4
4
  Summary: Python SDK for the boxd cloud VM platform
5
5
  Author: Azin
6
6
  License-Expression: MIT
@@ -891,6 +891,110 @@ that aren't valid UTF-8 round-trip. Errors are
891
891
  `NotADirectoryError`, with `errno` and `filename` set. A machine started before
892
892
  `machines.fs` existed raises `MachineAgentOutdatedError` until it is rebooted.
893
893
 
894
+ ### Computer use
895
+
896
+ `machines.computer` works a machine's desktop (the one the console's Desktop
897
+ view shows) for computer-use agents: screenshots, the mouse and the keyboard.
898
+ The desktop starts on demand. Each call does one action and returns a
899
+ `ComputerActionResult` with the screen's size, where the pointer is, and a
900
+ screenshot taken after the action when you ask for one.
901
+
902
+ ```python
903
+ c = boxd.machines.computer
904
+
905
+ r = c.screenshot(id)
906
+ r.screen_width, r.screen_height, r.cursor # cursor.x, cursor.y
907
+ r.screenshot.data # PNG bytes; .mime_type, .width, .height
908
+ c.screenshot(id, max_width=1280, max_height=800) # scaled down to fit
909
+ c.screenshot(id, format="jpeg", quality=80) # "png" | "jpeg" | "webp"
910
+ c.screenshot(id, region=(0, 0, 640, 400)) # part of the screen: x, y, width, height
911
+
912
+ c.click(id, 640, 400) # button="right" | "middle" | "back" | "forward"
913
+ c.click(id, 640, 400, count=2, modifiers="ctrl") # a double click, ctrl held
914
+ c.move(id, 100, 100)
915
+ c.drag(id, [(100, 100), (300, 200)])
916
+ c.mouse_down(id, 100, 100)
917
+ c.mouse_up(id, 300, 200)
918
+ c.scroll(id, 640, 400, dy=3) # wheel clicks: dy down, dx right
919
+ c.type(id, "hello")
920
+ c.key(id, "ctrl+s") # "Return", "alt+Tab"; repeat=, hold_ms=
921
+ c.wait(id, 1000) # milliseconds
922
+ c.cursor_position(id)
923
+
924
+ c.click(id, 640, 400, screenshot=True) # and a screenshot after it, same call
925
+ c.key(id, "Return", screenshot={"max_width": 1280, "delay_ms": 300})
926
+
927
+ c.set_screen_size(id, 1280, 800) # hold the screen at this size
928
+ c.release_screen_size(id) # it follows the viewer again
929
+ ```
930
+
931
+ Coordinates are screen pixels from the top left; leave out `x` and `y` to act
932
+ where the pointer is. A screenshot scaled down with `max_width`/`max_height`
933
+ is smaller than the screen, so scale coordinates read off it back up. Key
934
+ names are X key names, as `xdotool` takes them, plus common aliases (`enter`,
935
+ `esc`, `cmd`, `pageup`). `screenshot=` takes `True`, a `ScreenshotOptions` or a
936
+ dict of its fields (`format`, `quality`, `max_width`, `max_height`, `region`,
937
+ `delay_ms`). An action that doesn't fit the screen, or a key name it doesn't
938
+ know, raises `APIStatusError` with `code == "invalid_argument"`.
939
+
940
+ By default the screen follows whoever is watching it in the console, so it can
941
+ change size under an agent. `set_screen_size` holds it (320x200 to 5120x2880)
942
+ until `release_screen_size` or the desktop restarts: viewers see it scaled to
943
+ fit, can still click and type, and can release it from the Desktop view. Every
944
+ result says whether it is held (`result.screen_held`).
945
+
946
+ A machine in another region takes `region=` on these calls, as elsewhere in the
947
+ SDK, and `ClaudeComputer(boxd, "my-machine", region="nyc")` on the adapters. On
948
+ `screenshot`, `region` is the part of the screen to capture, so use
949
+ `c.in_region("nyc").screenshot(id)` there.
950
+
951
+ #### Claude and OpenAI agents
952
+
953
+ `boxd.computer_use` carries out a model's computer-use tool calls on a
954
+ machine. It needs neither the `anthropic` nor the `openai` package: it reads
955
+ their responses (SDK objects or plain dicts) and returns plain dicts to send
956
+ back.
957
+
958
+ ```python
959
+ import anthropic
960
+ from boxd.computer_use import ClaudeComputer
961
+
962
+ claude = anthropic.Anthropic()
963
+ computer = ClaudeComputer(boxd, "my-machine")
964
+ messages = [{"role": "user", "content": "Open example.com and read me its heading"}]
965
+ for _ in range(30):
966
+ response = claude.messages.create(
967
+ model="claude-opus-5-5",
968
+ max_tokens=16000,
969
+ tools=[computer.tool],
970
+ messages=messages,
971
+ )
972
+ messages.append({"role": "assistant", "content": response.content})
973
+ results = computer.run(response.content)
974
+ if not results:
975
+ break
976
+ messages.append({"role": "user", "content": results})
977
+ ```
978
+
979
+ `computer.tool` is Claude's computer toolset (`{"type":
980
+ "computer_toolset_20260801"}`), and `run` carries out the turn's computer
981
+ actions in order, returning one `tool_result` for each; the first failure ends
982
+ the turn and is reported to Claude. Screenshots are scaled down to fit 1280x800
983
+ (`max_width` and `max_height` change it), and Claude's coordinates are scaled
984
+ back up to the screen for you. The first action holds the screen at 1280x800, so
985
+ that someone opening the Desktop view doesn't resize it mid-run: `screen_size=`
986
+ picks another size, `screen_size=None` leaves the screen alone, and
987
+ `computer.release()` lets go when the agent is done.
988
+
989
+ `OpenAIComputer` does the same for OpenAI's computer tool: `computer.tool` is
990
+ `{"type": "computer"}`, and `run(response.output)` returns the
991
+ `computer_call_output` items for your next request. `AsyncClaudeComputer` and
992
+ `AsyncOpenAIComputer` take an `AsyncBoxd`.
993
+
994
+ The model does whatever it decides to on the machine, as the machine's user:
995
+ give it a machine of its own. A complete Claude agent:
996
+ [`examples/claude_computer_use.py`](https://github.com/boxd-sh/sdk/blob/main/python/examples/claude_computer_use.py).
997
+
894
998
  ### Ports and proxies
895
999
 
896
1000
  ```python
@@ -856,6 +856,110 @@ that aren't valid UTF-8 round-trip. Errors are
856
856
  `NotADirectoryError`, with `errno` and `filename` set. A machine started before
857
857
  `machines.fs` existed raises `MachineAgentOutdatedError` until it is rebooted.
858
858
 
859
+ ### Computer use
860
+
861
+ `machines.computer` works a machine's desktop (the one the console's Desktop
862
+ view shows) for computer-use agents: screenshots, the mouse and the keyboard.
863
+ The desktop starts on demand. Each call does one action and returns a
864
+ `ComputerActionResult` with the screen's size, where the pointer is, and a
865
+ screenshot taken after the action when you ask for one.
866
+
867
+ ```python
868
+ c = boxd.machines.computer
869
+
870
+ r = c.screenshot(id)
871
+ r.screen_width, r.screen_height, r.cursor # cursor.x, cursor.y
872
+ r.screenshot.data # PNG bytes; .mime_type, .width, .height
873
+ c.screenshot(id, max_width=1280, max_height=800) # scaled down to fit
874
+ c.screenshot(id, format="jpeg", quality=80) # "png" | "jpeg" | "webp"
875
+ c.screenshot(id, region=(0, 0, 640, 400)) # part of the screen: x, y, width, height
876
+
877
+ c.click(id, 640, 400) # button="right" | "middle" | "back" | "forward"
878
+ c.click(id, 640, 400, count=2, modifiers="ctrl") # a double click, ctrl held
879
+ c.move(id, 100, 100)
880
+ c.drag(id, [(100, 100), (300, 200)])
881
+ c.mouse_down(id, 100, 100)
882
+ c.mouse_up(id, 300, 200)
883
+ c.scroll(id, 640, 400, dy=3) # wheel clicks: dy down, dx right
884
+ c.type(id, "hello")
885
+ c.key(id, "ctrl+s") # "Return", "alt+Tab"; repeat=, hold_ms=
886
+ c.wait(id, 1000) # milliseconds
887
+ c.cursor_position(id)
888
+
889
+ c.click(id, 640, 400, screenshot=True) # and a screenshot after it, same call
890
+ c.key(id, "Return", screenshot={"max_width": 1280, "delay_ms": 300})
891
+
892
+ c.set_screen_size(id, 1280, 800) # hold the screen at this size
893
+ c.release_screen_size(id) # it follows the viewer again
894
+ ```
895
+
896
+ Coordinates are screen pixels from the top left; leave out `x` and `y` to act
897
+ where the pointer is. A screenshot scaled down with `max_width`/`max_height`
898
+ is smaller than the screen, so scale coordinates read off it back up. Key
899
+ names are X key names, as `xdotool` takes them, plus common aliases (`enter`,
900
+ `esc`, `cmd`, `pageup`). `screenshot=` takes `True`, a `ScreenshotOptions` or a
901
+ dict of its fields (`format`, `quality`, `max_width`, `max_height`, `region`,
902
+ `delay_ms`). An action that doesn't fit the screen, or a key name it doesn't
903
+ know, raises `APIStatusError` with `code == "invalid_argument"`.
904
+
905
+ By default the screen follows whoever is watching it in the console, so it can
906
+ change size under an agent. `set_screen_size` holds it (320x200 to 5120x2880)
907
+ until `release_screen_size` or the desktop restarts: viewers see it scaled to
908
+ fit, can still click and type, and can release it from the Desktop view. Every
909
+ result says whether it is held (`result.screen_held`).
910
+
911
+ A machine in another region takes `region=` on these calls, as elsewhere in the
912
+ SDK, and `ClaudeComputer(boxd, "my-machine", region="nyc")` on the adapters. On
913
+ `screenshot`, `region` is the part of the screen to capture, so use
914
+ `c.in_region("nyc").screenshot(id)` there.
915
+
916
+ #### Claude and OpenAI agents
917
+
918
+ `boxd.computer_use` carries out a model's computer-use tool calls on a
919
+ machine. It needs neither the `anthropic` nor the `openai` package: it reads
920
+ their responses (SDK objects or plain dicts) and returns plain dicts to send
921
+ back.
922
+
923
+ ```python
924
+ import anthropic
925
+ from boxd.computer_use import ClaudeComputer
926
+
927
+ claude = anthropic.Anthropic()
928
+ computer = ClaudeComputer(boxd, "my-machine")
929
+ messages = [{"role": "user", "content": "Open example.com and read me its heading"}]
930
+ for _ in range(30):
931
+ response = claude.messages.create(
932
+ model="claude-opus-5-5",
933
+ max_tokens=16000,
934
+ tools=[computer.tool],
935
+ messages=messages,
936
+ )
937
+ messages.append({"role": "assistant", "content": response.content})
938
+ results = computer.run(response.content)
939
+ if not results:
940
+ break
941
+ messages.append({"role": "user", "content": results})
942
+ ```
943
+
944
+ `computer.tool` is Claude's computer toolset (`{"type":
945
+ "computer_toolset_20260801"}`), and `run` carries out the turn's computer
946
+ actions in order, returning one `tool_result` for each; the first failure ends
947
+ the turn and is reported to Claude. Screenshots are scaled down to fit 1280x800
948
+ (`max_width` and `max_height` change it), and Claude's coordinates are scaled
949
+ back up to the screen for you. The first action holds the screen at 1280x800, so
950
+ that someone opening the Desktop view doesn't resize it mid-run: `screen_size=`
951
+ picks another size, `screen_size=None` leaves the screen alone, and
952
+ `computer.release()` lets go when the agent is done.
953
+
954
+ `OpenAIComputer` does the same for OpenAI's computer tool: `computer.tool` is
955
+ `{"type": "computer"}`, and `run(response.output)` returns the
956
+ `computer_call_output` items for your next request. `AsyncClaudeComputer` and
957
+ `AsyncOpenAIComputer` take an `AsyncBoxd`.
958
+
959
+ The model does whatever it decides to on the machine, as the machine's user:
960
+ give it a machine of its own. A complete Claude agent:
961
+ [`examples/claude_computer_use.py`](https://github.com/boxd-sh/sdk/blob/main/python/examples/claude_computer_use.py).
962
+
859
963
  ### Ports and proxies
860
964
 
861
965
  ```python
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "boxd"
3
- version = "0.3.0.dev1071"
3
+ version = "0.3.0.dev1074"
4
4
  description = "Python SDK for the boxd cloud VM platform"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -46,6 +46,8 @@ from .models import (
46
46
  Billing,
47
47
  Checkpoint,
48
48
  ClusterConfig,
49
+ ComputerActionResult,
50
+ ComputerPoint,
49
51
  CreatedApiKey,
50
52
  CreatedCheckpoint,
51
53
  CreatedDisk,
@@ -108,6 +110,9 @@ from .models import (
108
110
  RegionOrgState,
109
111
  ResizeResult,
110
112
  ResumeResult,
113
+ Screenshot,
114
+ ScreenshotFormat,
115
+ ScreenshotOptions,
111
116
  Secret,
112
117
  Snapshot,
113
118
  StateSeconds,
@@ -164,6 +169,8 @@ __all__ = [
164
169
  "Billing",
165
170
  "Checkpoint",
166
171
  "ClusterConfig",
172
+ "ComputerActionResult",
173
+ "ComputerPoint",
167
174
  "CreatedApiKey",
168
175
  "CreatedCheckpoint",
169
176
  "CreatedDisk",
@@ -226,6 +233,9 @@ __all__ = [
226
233
  "RegionOrgState",
227
234
  "ResizeResult",
228
235
  "ResumeResult",
236
+ "Screenshot",
237
+ "ScreenshotFormat",
238
+ "ScreenshotOptions",
229
239
  "Secret",
230
240
  "Snapshot",
231
241
  "StateSeconds",