Metadata-Version: 2.4
Name: use-computer
Version: 0.0.30
Summary: Python SDK for use.computer sandboxes across macOS, iOS simulators, Windows, and Ubuntu
Project-URL: Homepage, https://use.computer
Project-URL: Documentation, https://api.use.computer/docs
Project-URL: Repository, https://github.com/josancamon19/use-computer-sdk
Author: use.computer
Keywords: automation,computer-use,ios,macos,sandbox,ubuntu,vnc,windows
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: agents
Requires-Dist: pillow>=10; extra == 'agents'
Provides-Extra: agents-all
Requires-Dist: anthropic>=0.86; extra == 'agents-all'
Requires-Dist: google-genai>=1; extra == 'agents-all'
Requires-Dist: litellm>=1; extra == 'agents-all'
Requires-Dist: openai>=1; extra == 'agents-all'
Requires-Dist: pillow>=10; extra == 'agents-all'
Provides-Extra: agents-anthropic
Requires-Dist: anthropic>=0.86; extra == 'agents-anthropic'
Requires-Dist: pillow>=10; extra == 'agents-anthropic'
Provides-Extra: agents-gemini
Requires-Dist: google-genai>=1; extra == 'agents-gemini'
Requires-Dist: pillow>=10; extra == 'agents-gemini'
Provides-Extra: agents-litellm
Requires-Dist: litellm>=1; extra == 'agents-litellm'
Requires-Dist: pillow>=10; extra == 'agents-litellm'
Provides-Extra: agents-openai
Requires-Dist: openai>=1; extra == 'agents-openai'
Requires-Dist: pillow>=10; extra == 'agents-openai'
Provides-Extra: harbor
Requires-Dist: harbor>=0.4.0; (python_version >= '3.12') and extra == 'harbor'
Requires-Dist: pyyaml>=6; extra == 'harbor'
Requires-Dist: tomli>=2; extra == 'harbor'
Description-Content-Type: text/markdown

# use-computer Python SDK

Python client for [use.computer](https://use.computer) — rent dedicated VMs across macOS, iOS/visionOS/tvOS simulators, Windows, and Ubuntu built for computer-use agents.

```bash
pip install use-computer
export USE_COMPUTER_API_KEY=mk_live_...
```

Optional agent and Harbor integrations are installed explicitly:

```bash
pip install "use-computer[agents]"            # shared agent helpers + debug agent
pip install "use-computer[agents-openai]"     # or agents-anthropic / agents-gemini / agents-litellm / agents-all
pip install "use-computer[harbor]"            # Harbor environment adapter (Python 3.12+)
pip install "use-computer[harbor,agents-all]" # Harbor adapter plus all provider deps
```

Base installs only the SDK client and `httpx`. The `agents-*` extras install
model-provider dependencies; `harbor` installs Harbor plus the environment
adapter dependencies, but no provider SDKs.

```python
from use_computer.agents import AnthropicComputerAgent
from use_computer.harbor.environment import UseComputerEnvironment
```

```python
from use_computer import Computer, SandboxType, SimulatorFamily

with Computer().create() as mac:
    mac.exec_ssh("open -a TextEdit")
    mac.keyboard.type("hello")
    png = mac.screenshot.take_full_screen()

with Computer().create(type=SandboxType.IOS, family=SimulatorFamily.TV) as tv:
    tv.screenshot.take_full_screen()
    tv.input.press_remote("select")

with Computer().create(type=SandboxType.IOS) as ios:
    ios.input.long_press(120, 300, duration=1.0)
```

### Windows (Beta)

```python
with Computer().create(type="windows") as win:
    print(win.run("$env:COMPUTERNAME").stdout)   # PowerShell exec (no SSH)
    win.keyboard.type("hello")
    win.screenshot.take_full_screen()
    win.ui_tree()                                 # native Windows UIAutomation tree
```

Windows sandboxes are **Beta** (admin-only). Same mouse/keyboard/screenshot/
recording/file surface as macOS; exec runs in-guest via PowerShell/cmd
(`win.run` / `win.shell`) instead of SSH. `AsyncWindowsSandbox` mirrors it.
See [docs.use.computer/docs/windows](https://docs.use.computer/docs/windows).

Selectable Windows images are exposed by `Computer().platforms()["windows"]`.
Prefer `version="windows-11"` plus `resources={"cpus": 4, "memory_mb": 4096,
"disk_gb": 40}` to select a resource profile. Explicit image IDs such as
`windows-11-4c4g40g` still work. The image metadata includes CPU/RAM/disk and
display size.

### Ubuntu (Beta)

```python
with Computer().create(type="ubuntu", version="ubuntu-24.04") as ubuntu:
    print(ubuntu.run("uname -a").stdout)  # bash exec (no SSH)
    print(ubuntu.display.get_info())
    ubuntu.keyboard.type("hello")
    ubuntu.screenshot.take_full_screen()
```

Ubuntu sandboxes are **Beta** (admin-only). They use the same KVM/noVNC backend
as Windows; pass `version="ubuntu-24.04"` plus `resources` to select CPU/RAM/disk.

Selectable Ubuntu images are exposed by `Computer().platforms()["ubuntu"]`.
Current examples include `ubuntu-24.04`, `ubuntu-24.04-4c4g80g`,
`ubuntu-24.04-4c4g40g`, and `ubuntu-24.04-2c4g40g`.

```python
client = Computer()
platforms = client.platforms()
for image in platforms["ubuntu"]["images"]:
    print(image["version"], image["resources"], image["display"])

with client.create(
    type="ubuntu",
    version="ubuntu-24.04",
    resources={"cpus": 2, "memory_mb": 4096, "disk_gb": 40},
) as ubuntu:
    print(ubuntu.display.get_info())
```

### Snapshots (Beta)

Windows and Ubuntu snapshots preserve disk + RAM state, including open apps and
running processes. Seed a VM once, snapshot it, then create new sandboxes from
that snapshot version.

```python
client = Computer()

with client.create(type="ubuntu", version="ubuntu-24.04") as ubuntu:
    ubuntu.run("google-chrome-stable --no-first-run https://example.com >/tmp/chrome.log 2>&1 &")
    snapshot = ubuntu.snapshot("chrome-seeded-ubuntu")

with client.create(type="ubuntu", snapshot=snapshot.version) as seeded:
    print(seeded.run("pgrep -af 'chrome|chromium' | head").stdout)
```

Use `client.snapshots("ubuntu")` or `client.snapshots("windows")` to list saved
snapshot versions.

Full DSL reference: [docs.use.computer/docs/sdk](https://docs.use.computer/docs/sdk)

Simulator sandboxes use `type=SandboxType.IOS` for the SDK route, but
`device_type` and `runtime` can target any installed compatible CoreSimulator
pair: iPhone or iPad with iOS, Apple Watch with watchOS, Apple TV with tvOS, or
Apple Vision with visionOS. Prefer `family=SimulatorFamily.TV`/`WATCH`/`VISION`
unless you need to pin raw CoreSimulator identifiers. Raw strings like
`type="ios"` still work for compatibility. If omitted, the gateway defaults to
iPhone 17 Pro on the latest installed iOS runtime.
Known-incompatible simulator types are filtered from family selection,
including the non-4K Apple Vision Pro type on current fleet runtimes.

### Per-family input

iPhone / iPad sims have full touch + on-screen keyboard. Apple Watch supports
touch + crown / button (no `type_text` — watchOS keyboard isn't exposed). Apple
TV has no touch — drive it with `input.press_remote(RemoteButton.SELECT)` (the
remote D-pad, select, menu, home, play/pause). **Apple Vision (visionOS) is
BETA**: sessions display and you can screenshot / launch apps, but
`input.tap` is a no-op because there's no XCTest-free coordinate tap path on
visionOS yet. Use it for read-only flows for now.

## Examples

| File                                                           | What it shows                                  |
| -------------------------------------------------------------- | ---------------------------------------------- |
| [`examples/_1_hello_macos.py`](examples/_1_hello_macos.py)     | create → exec → keyboard → screenshot          |
| [`examples/_2_hello_ios.py`](examples/_2_hello_ios.py)         | create iPhone sim → open URL → screenshot      |
| [`examples/_3_recording.py`](examples/_3_recording.py)         | start / stop / download a screen recording     |
| [`examples/_4_file_transfer.py`](examples/_4_file_transfer.py) | upload bytes, download a file back             |
| [`examples/_5_keepalive.py`](examples/_5_keepalive.py)         | heartbeat for sessions idle > 2 min            |
| [`examples/_6_hello_tvos.py`](examples/_6_hello_tvos.py)       | tvOS: pick TV family + drive the Apple Remote  |
| [`examples/_7_hello_windows.py`](examples/_7_hello_windows.py) | create Windows → run PowerShell → screenshot   |
| [`examples/_8_hello_ubuntu.py`](examples/_8_hello_ubuntu.py)   | create Ubuntu → run bash → screenshot          |
| [`examples/_9_seeding.py`](examples/_9_seeding.py)             | typed setup: files, hosts, open URLs/apps      |
| [`examples/_10_snapshots.py`](examples/_10_snapshots.py)       | snapshot seeded Ubuntu/Windows desktop state   |

For agent loops and evals: [use-computer-cookbook](https://github.com/josancamon19/use-computer-cookbook). Its Harbor job YAMLs use `use_computer.harbor.environment` and `use_computer.harbor.agents` as the canonical import paths.

## Skill for AI coding assistants

Point your assistant at [`use-computer-cookbook/skills/SKILL.md`](https://github.com/josancamon19/use-computer-cookbook/blob/main/skills/SKILL.md) — short body with per-topic references for macOS, Apple simulators, lifecycle, and the Harbor harness.

## HTTP API

Every SDK method wraps `https://api.use.computer/v1/...` with `Authorization: Bearer mk_live_...`. Swagger: [api.use.computer/docs](https://api.use.computer/docs). OpenAPI spec: [api.use.computer/openapi.yaml](https://api.use.computer/openapi.yaml).
