use-computer 0.0.20__tar.gz → 0.0.22__tar.gz

{use_computer-0.0.20 → use_computer-0.0.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: use-computer
-Version: 0.0.20
+Version: 0.0.22
 Summary: Python SDK for the use.computer macOS and iOS Computer Use API
 Project-URL: Homepage, https://use.computer
 Project-URL: Documentation, https://api.use.computer/docs

use_computer-0.0.22/examples/go/hello_windows.go

@@ -0,0 +1,35 @@
+// Windows (Beta). Run:
+//   export USE_COMPUTER_API_KEY=...
+//   go run hello_windows.go
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	uc "github.com/josancamon19/use-computer-sdk/go"
+)
+
+func main() {
+	ctx := context.Background()
+	c := uc.New()
+
+	win, err := c.Create(ctx, uc.CreateOptions{Type: uc.Windows, Version: "windows-11"})
+	if err != nil {
+		panic(err)
+	}
+	defer win.Close(ctx)
+
+	name, _ := win.RunShell(ctx, "$env:COMPUTERNAME", "powershell")
+	fmt.Println("computer name:", name.Stdout)
+	win.RunShell(ctx, "Start-Process notepad", "powershell")
+	win.TypeText(ctx, "hello from use.computer")
+
+	png, err := win.Screenshot(ctx)
+	if err != nil {
+		panic(err)
+	}
+	os.WriteFile("hello_windows.png", png, 0o644)
+	fmt.Printf("saved hello_windows.png (%d bytes)\n", len(png))
+}

use_computer-0.0.22/examples/javascript/hello_windows.ts

@@ -0,0 +1,14 @@
+// Windows (Beta) — run: USE_COMPUTER_API_KEY=... npx tsx hello_windows.ts
+import { Computer } from "use-computer";
+
+const computer = new Computer();
+await using win = await computer.create({ type: "windows", version: "windows-11" });
+
+console.log("computer name:", (await win.run("$env:COMPUTERNAME")).stdout.trim());
+await win.run("Start-Process notepad");
+await win.keyboard.type("hello from use.computer");
+
+const png = await win.screenshot.takeFullScreen();
+const { writeFile } = await import("node:fs/promises");
+await writeFile("hello_windows.png", png);
+console.log(`saved hello_windows.png (${png.length} bytes)`);

use_computer-0.0.22/go/README.md

@@ -0,0 +1,46 @@
+# use-computer — Go SDK
+
+Go client for [use.computer](https://use.computer) — rent dedicated VMs (macOS, iOS/visionOS/tvOS simulators, **Windows**, **Ubuntu**) built for computer-use agents. Parity with the [Python](../python) and [TypeScript](../javascript) SDKs.
+
+```bash
+go get github.com/josancamon19/use-computer-sdk/go@latest
+export USE_COMPUTER_API_KEY=mk_live_...
+```
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+
+	uc "github.com/josancamon19/use-computer-sdk/go"
+)
+
+func main() {
+	ctx := context.Background()
+	c := uc.New() // base URL + key from env, or uc.WithBaseURL/WithAPIKey
+
+	// Windows (Beta) — no SSH; runs in-guest via PowerShell/cmd
+	win, err := c.Create(ctx, uc.CreateOptions{Type: uc.Windows, Version: "windows-11"})
+	if err != nil {
+		panic(err)
+	}
+	defer win.Close(ctx)
+
+	r, _ := win.RunShell(ctx, "$env:COMPUTERNAME", "powershell")
+	fmt.Println(r.Stdout)
+	win.Click(ctx, 400, 300)
+	win.TypeText(ctx, "hello from use.computer")
+	png, _ := win.Screenshot(ctx)
+	fmt.Printf("screenshot %d bytes\n", len(png))
+}
+```
+
+## Surface
+
+- `New(opts...)` → `*Computer`; `WithBaseURL`, `WithAPIKey`, `WithHTTPClient`.
+- `Create(ctx, CreateOptions{Type, Version, Host, Family, DeviceType, Runtime})` → `*Sandbox`.
+- `Sandbox`: `Exec` (SSH on macOS / in-guest on Ubuntu / PowerShell on Windows), `RunShell(cmd, "powershell"|"cmd")`, `Screenshot`, `Click`, `Move`, `Scroll`, `TypeText`, `PressKey`, `Hotkey`, `UITree`, `Upload`, `Download`, `StartRecording`/`StopRecording`, `Keepalive`, `Close`.
+
+Every call takes a `context.Context`. Docs: [docs.use.computer](https://docs.use.computer). Windows is **Beta** (admin-only).

use_computer-0.0.22/go/client.go

@@ -0,0 +1,192 @@
+// Package usecomputer is the Go SDK for use.computer — rent dedicated VMs
+// (macOS, iOS/visionOS/tvOS simulators, Windows, Ubuntu) for computer-use agents.
+// Parity with the Python and TypeScript SDKs.
+package usecomputer
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+)
+
+// SandboxType is the OS family of a sandbox.
+type SandboxType string
+
+const (
+	MacOS   SandboxType = "macos"
+	IOS     SandboxType = "ios"
+	Windows SandboxType = "windows"
+	Ubuntu  SandboxType = "ubuntu"
+)
+
+// Computer is a client for a use.computer gateway.
+type Computer struct {
+	baseURL string
+	apiKey  string
+	http    *http.Client
+}
+
+// Option configures a Computer.
+type Option func(*Computer)
+
+// WithBaseURL sets the gateway base URL (default $USE_COMPUTER_BASE_URL or https://api.use.computer).
+func WithBaseURL(u string) Option { return func(c *Computer) { c.baseURL = strings.TrimRight(u, "/") } }
+
+// WithAPIKey sets the API key (default $USE_COMPUTER_API_KEY).
+func WithAPIKey(k string) Option { return func(c *Computer) { c.apiKey = k } }
+
+// WithHTTPClient overrides the underlying *http.Client.
+func WithHTTPClient(h *http.Client) Option { return func(c *Computer) { c.http = h } }
+
+// New creates a Computer client.
+func New(opts ...Option) *Computer {
+	c := &Computer{
+		baseURL: envOr("USE_COMPUTER_BASE_URL", "https://api.use.computer"),
+		apiKey:  os.Getenv("USE_COMPUTER_API_KEY"),
+		http:    &http.Client{Timeout: 200 * time.Second},
+	}
+	for _, o := range opts {
+		o(c)
+	}
+	c.baseURL = strings.TrimRight(c.baseURL, "/")
+	return c
+}
+
+// CreateOptions selects the sandbox to create.
+type CreateOptions struct {
+	Type       SandboxType // default MacOS
+	Host       string      // pin to a host (e.g. "mm001")
+	Version    string      // windows image version: "windows-11" (default), "windows-10"
+	Family     string      // ios simulator family
+	DeviceType string      // ios exact device type
+	Runtime    string      // ios exact runtime
+}
+
+type createResponse struct {
+	SandboxID string `json:"sandbox_id"`
+	Type      string `json:"type"`
+	VNCURL    string `json:"vnc_url"`
+	SSHURL    string `json:"ssh_url"`
+	VMIP      string `json:"vm_ip"`
+	Host      string `json:"host"`
+}
+
+// Create provisions a new sandbox and returns it once ready.
+func (c *Computer) Create(ctx context.Context, opts CreateOptions) (*Sandbox, error) {
+	t := opts.Type
+	if t == "" {
+		t = MacOS
+	}
+	body := map[string]any{"type": string(t)}
+	if opts.Host != "" {
+		body["host"] = opts.Host
+	}
+	if t == Windows && opts.Version != "" {
+		body["version"] = opts.Version
+	}
+	if t == IOS {
+		if opts.Family != "" {
+			body["family"] = opts.Family
+		}
+		if opts.DeviceType != "" {
+			body["device_type"] = opts.DeviceType
+		}
+		if opts.Runtime != "" {
+			body["runtime"] = opts.Runtime
+		}
+	}
+	var resp createResponse
+	if err := c.doJSON(ctx, http.MethodPost, "/v1/sandboxes", body, &resp); err != nil {
+		return nil, err
+	}
+	return &Sandbox{
+		ID: resp.SandboxID, Type: t, VNCURL: resp.VNCURL, SSHURL: resp.SSHURL, VMIP: resp.VMIP,
+		c: c, prefix: "/v1/sandboxes/" + resp.SandboxID,
+	}, nil
+}
+
+// Platforms discovers available platforms, images, runtimes, and device types.
+func (c *Computer) Platforms(ctx context.Context) (map[string]any, error) {
+	var out map[string]any
+	return out, c.doJSON(ctx, http.MethodGet, "/v1/platforms", nil, &out)
+}
+
+// --- internal HTTP helpers ---
+
+func (c *Computer) newReq(ctx context.Context, method, path string, body io.Reader) (*http.Request, error) {
+	req, err := http.NewRequestWithContext(ctx, method, c.baseURL+path, body)
+	if err != nil {
+		return nil, err
+	}
+	if c.apiKey != "" {
+		req.Header.Set("Authorization", "Bearer "+c.apiKey)
+	}
+	return req, nil
+}
+
+func (c *Computer) doJSON(ctx context.Context, method, path string, body, out any) error {
+	var rdr io.Reader
+	if body != nil {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return err
+		}
+		rdr = bytes.NewReader(b)
+	} else if method == http.MethodPost {
+		rdr = strings.NewReader("{}")
+	}
+	req, err := c.newReq(ctx, method, path, rdr)
+	if err != nil {
+		return err
+	}
+	if rdr != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		b, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
+		return fmt.Errorf("%s %s: %d: %s", method, path, resp.StatusCode, strings.TrimSpace(string(b)))
+	}
+	if out == nil {
+		return nil
+	}
+	return json.NewDecoder(resp.Body).Decode(out)
+}
+
+func (c *Computer) getBytes(ctx context.Context, path string, q url.Values) ([]byte, error) {
+	if q != nil {
+		path += "?" + q.Encode()
+	}
+	req, err := c.newReq(ctx, http.MethodGet, path, nil)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		b, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
+		return nil, fmt.Errorf("GET %s: %d: %s", path, resp.StatusCode, strings.TrimSpace(string(b)))
+	}
+	return io.ReadAll(resp.Body)
+}
+
+func envOr(k, def string) string {
+	if v := os.Getenv(k); v != "" {
+		return v
+	}
+	return def
+}

use_computer-0.0.22/go/go.mod

@@ -0,0 +1,3 @@
+module github.com/josancamon19/use-computer-sdk/go
+
+go 1.22

use_computer-0.0.22/go/sandbox.go

@@ -0,0 +1,156 @@
+package usecomputer
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"net/http"
+	"net/url"
+)
+
+// Sandbox is a running VM. Action methods map 1:1 to the gateway HTTP surface.
+type Sandbox struct {
+	ID     string
+	Type   SandboxType
+	VNCURL string
+	SSHURL string // macOS only
+	VMIP   string // macOS only
+
+	c      *Computer
+	prefix string
+}
+
+// ExecResult is the outcome of a shell command.
+type ExecResult struct {
+	Stdout   string `json:"stdout"`
+	Stderr   string `json:"stderr"`
+	ExitCode int    `json:"-"`
+}
+
+type execWire struct {
+	Stdout     string `json:"stdout"`
+	Stderr     string `json:"stderr"`
+	ExitCode   *int   `json:"exit_code"`
+	ReturnCode *int   `json:"return_code"`
+}
+
+func (e execWire) result() ExecResult {
+	code := 0
+	if e.ExitCode != nil {
+		code = *e.ExitCode
+	} else if e.ReturnCode != nil {
+		code = *e.ReturnCode
+	}
+	return ExecResult{Stdout: e.Stdout, Stderr: e.Stderr, ExitCode: code}
+}
+
+// Exec runs a command: SSH on macOS, in-guest on Ubuntu, PowerShell on Windows.
+// On Windows pass shell ("powershell" or "cmd") via RunShell for cmd.
+func (s *Sandbox) Exec(ctx context.Context, command string) (ExecResult, error) {
+	var w execWire
+	err := s.c.doJSON(ctx, http.MethodPost, s.prefix+"/exec", map[string]any{"command": command}, &w)
+	return w.result(), err
+}
+
+// RunShell runs a command on Windows in the given shell ("powershell" | "cmd").
+func (s *Sandbox) RunShell(ctx context.Context, command, shell string) (ExecResult, error) {
+	var w execWire
+	err := s.c.doJSON(ctx, http.MethodPost, s.prefix+"/exec", map[string]any{"command": command, "shell": shell}, &w)
+	return w.result(), err
+}
+
+// Screenshot returns a full-screen PNG/JPEG.
+func (s *Sandbox) Screenshot(ctx context.Context) ([]byte, error) {
+	return s.c.getBytes(ctx, s.prefix+"/screenshot", nil)
+}
+
+// Click left-clicks at (x, y).
+func (s *Sandbox) Click(ctx context.Context, x, y int) error {
+	return s.c.doJSON(ctx, http.MethodPost, s.prefix+"/act",
+		map[string]any{"action": map[string]any{"type": "click", "x": x, "y": y, "button": "left"}}, nil)
+}
+
+// Move moves the cursor to (x, y).
+func (s *Sandbox) Move(ctx context.Context, x, y int) error {
+	return s.c.doJSON(ctx, http.MethodPost, s.prefix+"/mouse/move", map[string]any{"x": x, "y": y}, nil)
+}
+
+// Scroll scrolls by (dx, dy) at (x, y).
+func (s *Sandbox) Scroll(ctx context.Context, x, y, dx, dy int) error {
+	return s.c.doJSON(ctx, http.MethodPost, s.prefix+"/act",
+		map[string]any{"action": map[string]any{"type": "scroll", "x": x, "y": y, "scroll_x": dx, "scroll_y": dy}}, nil)
+}
+
+// TypeText types a string.
+func (s *Sandbox) TypeText(ctx context.Context, text string) error {
+	return s.c.doJSON(ctx, http.MethodPost, s.prefix+"/keyboard/type", map[string]any{"text": text}, nil)
+}
+
+// PressKey presses a single key.
+func (s *Sandbox) PressKey(ctx context.Context, key string) error {
+	return s.c.doJSON(ctx, http.MethodPost, s.prefix+"/keyboard/press", map[string]any{"key": key}, nil)
+}
+
+// Hotkey presses a combo, e.g. "ctrl+c" (macOS "cmd+c", Windows "win+d").
+func (s *Sandbox) Hotkey(ctx context.Context, combo string) error {
+	return s.c.doJSON(ctx, http.MethodPost, s.prefix+"/keyboard/hotkey", map[string]any{"keys": combo}, nil)
+}
+
+// UITree returns the native UI tree (macOS axe schema / Windows UIAutomation).
+func (s *Sandbox) UITree(ctx context.Context) (map[string]any, error) {
+	var out map[string]any
+	return out, s.c.doJSON(ctx, http.MethodGet, s.prefix+"/display/windows", nil, &out)
+}
+
+// Upload writes bytes to remotePath in the VM.
+func (s *Sandbox) Upload(ctx context.Context, data []byte, remotePath string) error {
+	req, err := s.c.newReq(ctx, http.MethodPut, s.prefix+"/files?"+url.Values{"path": {remotePath}}.Encode(), bytes.NewReader(data))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/octet-stream")
+	resp, err := s.c.http.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 400 {
+		return fmt.Errorf("upload %s: %d", remotePath, resp.StatusCode)
+	}
+	return nil
+}
+
+// Download reads remotePath from the VM.
+func (s *Sandbox) Download(ctx context.Context, remotePath string) ([]byte, error) {
+	return s.c.getBytes(ctx, s.prefix+"/files", url.Values{"path": {remotePath}})
+}
+
+// StartRecording starts a screen recording, returning its id.
+func (s *Sandbox) StartRecording(ctx context.Context) (string, error) {
+	var out struct {
+		RecordingID string `json:"recording_id"`
+		ID          string `json:"id"`
+	}
+	if err := s.c.doJSON(ctx, http.MethodPost, s.prefix+"/recording/start", nil, &out); err != nil {
+		return "", err
+	}
+	if out.RecordingID != "" {
+		return out.RecordingID, nil
+	}
+	return out.ID, nil
+}
+
+// StopRecording stops a recording by id.
+func (s *Sandbox) StopRecording(ctx context.Context, recordingID string) error {
+	return s.c.doJSON(ctx, http.MethodPost, s.prefix+"/recording/stop", map[string]any{"recording_id": recordingID}, nil)
+}
+
+// Keepalive resets the idle timer.
+func (s *Sandbox) Keepalive(ctx context.Context) error {
+	return s.c.doJSON(ctx, http.MethodPost, s.prefix+"/keepalive", nil, nil)
+}
+
+// Close destroys the sandbox.
+func (s *Sandbox) Close(ctx context.Context) error {
+	return s.c.doJSON(ctx, http.MethodDelete, s.prefix, nil, nil)
+}

use_computer-0.0.22/javascript/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.tsbuildinfo

use_computer-0.0.22/javascript/README.md

@@ -0,0 +1,48 @@
+# use-computer — TypeScript SDK
+
+TypeScript/JavaScript client for [use.computer](https://use.computer) — rent dedicated VMs (macOS, iOS/visionOS/tvOS simulators, **Windows**, **Ubuntu**) built for computer-use agents. Parity with the [Python SDK](../python); async-native.
+
+```bash
+npm install use-computer
+export USE_COMPUTER_API_KEY=mk_live_...
+```
+
+```ts
+import { Computer } from "use-computer";
+
+const computer = new Computer(); // baseUrl + apiKey from env, or pass {baseUrl, apiKey}
+
+// macOS (default)
+const mac = await computer.create({ type: "macos" });
+await mac.execSsh("open -a TextEdit");
+await mac.keyboard.type("hello");
+const png = await mac.screenshot.takeFullScreen();
+await mac.close();
+
+// Windows (Beta) — no SSH; exec runs in-guest via PowerShell/cmd
+await using win = await computer.create({ type: "windows", version: "windows-11" });
+console.log((await win.run("$env:COMPUTERNAME")).stdout);
+await win.mouse.click(400, 300);
+await win.keyboard.type("hello from use.computer");
+const tree = await win.uiTree(); // native Windows UIAutomation tree
+
+// iOS simulator
+const ios = await computer.create({ type: "ios", family: "iphone" });
+await ios.tap(120, 300);
+
+// Ubuntu
+const ubuntu = await computer.create({ type: "ubuntu" });
+console.log((await ubuntu.exec("uname -a")).stdout);
+```
+
+## Surface
+
+- `Computer.create({ type, version?, host?, family?, deviceType?, runtime? })` → typed sandbox.
+- All sandboxes: `screenshot.takeFullScreen()/takeCompressed()`, `recording.start()/stop()/listAll()/download()`, `uiTree()`, `displayInfo()`, `upload(bytes, path)`, `download(path)`, `keepalive()`, `close()`.
+- macOS / Windows / Ubuntu: `mouse.move/click/doubleClick/scroll/drag/position`, `keyboard.type/press/hotkey`.
+- macOS: `execSsh(cmd)`. Windows: `run(cmd, "powershell"|"cmd")` (no SSH). Ubuntu: `exec(cmd)`.
+- iOS: `tap`, `pressButton`, `pressRemote`, `launch` (no axe-schema `uiTree`).
+
+`await using` (TS 5.2+) auto-closes the sandbox at scope exit.
+
+Docs: [docs.use.computer](https://docs.use.computer). Windows is **Beta** (admin-only).

use_computer-0.0.22/javascript/package-lock.json

@@ -0,0 +1,51 @@
+{
+  "name": "use-computer",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "use-computer",
+      "version": "0.1.0",
+      "license": "MIT",
+      "devDependencies": {
+        "@types/node": "^20.0.0",
+        "typescript": "^5.6.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "20.19.41",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.41.tgz",
+      "integrity": "sha512-ECymXOukMnOoVkC2bb1Vc/w/836DXncOg5m8Xj1RH7xSHZJWNYY6Zh7EH477vcnD5egKNNfy2RpNOmuChhFPgQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    }
+  }
+}

use_computer-0.0.22/javascript/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "use-computer",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for use.computer — rent dedicated VMs (macOS, iOS/visionOS/tvOS simulators, Windows, Ubuntu) built for computer-use agents.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["use.computer", "computer-use", "agents", "macos", "windows", "ios", "ubuntu", "sandbox", "vnc"],
+  "repository": { "type": "git", "url": "https://github.com/josancamon19/use-computer-sdk.git", "directory": "javascript" },
+  "homepage": "https://docs.use.computer",
+  "devDependencies": { "typescript": "^5.6.0", "@types/node": "^20.0.0" }
+}

use_computer-0.0.22/javascript/src/client.ts

@@ -0,0 +1,82 @@
+import { HttpClient } from "./http.js";
+import {
+  IOSSandbox,
+  MacOSSandbox,
+  type SandboxType,
+  UbuntuSandbox,
+  WindowsSandbox,
+  type AnySandbox,
+} from "./sandbox.js";
+
+export interface ComputerOptions {
+  /** Gateway base URL. Default: $USE_COMPUTER_BASE_URL or https://api.use.computer */
+  baseUrl?: string;
+  /** API key. Default: $USE_COMPUTER_API_KEY */
+  apiKey?: string;
+}
+
+export interface CreateOptions {
+  type?: SandboxType;
+  /** Pin to a specific host machine (e.g. "mm001"). */
+  host?: string;
+  /** iOS: simulator family ("iphone" | "ipad" | "tv" | "watch" | "vision"). */
+  family?: string;
+  /** iOS: exact CoreSimulator device type / runtime identifiers. */
+  deviceType?: string;
+  runtime?: string;
+  /** Windows: image version — "windows-11" (default), "windows-10". */
+  version?: string;
+}
+
+interface CreateResponse {
+  sandbox_id: string;
+  type?: string;
+  vnc_url?: string;
+  ssh_url?: string;
+  vm_ip?: string;
+  host?: string;
+}
+
+export class Computer {
+  private readonly http: HttpClient;
+
+  constructor(opts: ComputerOptions = {}) {
+    const baseUrl = opts.baseUrl ?? process.env.USE_COMPUTER_BASE_URL ?? "https://api.use.computer";
+    const apiKey = opts.apiKey ?? process.env.USE_COMPUTER_API_KEY ?? "";
+    this.http = new HttpClient(baseUrl, apiKey);
+  }
+
+  /** Discover available platforms, images, runtimes, and device types. */
+  platforms(): Promise<unknown> {
+    return this.http.getJSON("/v1/platforms");
+  }
+
+  async create(opts: { type?: "macos"; host?: string }): Promise<MacOSSandbox>;
+  async create(opts: { type: "ios"; family?: string; deviceType?: string; runtime?: string }): Promise<IOSSandbox>;
+  async create(opts: { type: "windows"; version?: string; host?: string }): Promise<WindowsSandbox>;
+  async create(opts: { type: "ubuntu"; host?: string }): Promise<UbuntuSandbox>;
+  async create(opts: CreateOptions = {}): Promise<AnySandbox> {
+    const type = (opts.type ?? "macos") as SandboxType;
+    const body: Record<string, unknown> = { type };
+    if (opts.host) body.host = opts.host;
+    if (type === "windows" && opts.version) body.version = opts.version;
+    if (type === "ios") {
+      if (opts.family) body.family = opts.family;
+      if (opts.deviceType) body.device_type = opts.deviceType;
+      if (opts.runtime) body.runtime = opts.runtime;
+    }
+    const d = await this.http.postJSON<CreateResponse>("/v1/sandboxes", body);
+    const id = d.sandbox_id;
+    const vnc = d.vnc_url ?? "";
+    switch (type) {
+      case "windows":
+        return new WindowsSandbox(id, this.http, vnc);
+      case "ubuntu":
+        return new UbuntuSandbox(id, this.http, vnc);
+      case "ios":
+        return new IOSSandbox(id, this.http, vnc);
+      default:
+        return new MacOSSandbox(id, this.http, vnc, d.ssh_url ?? "", d.vm_ip ?? "");
+    }
+  }
+}

use_computer-0.0.22/javascript/src/http.ts

@@ -0,0 +1,96 @@
+// Thin fetch wrapper: base URL + bearer auth, JSON/binary helpers, typed errors.
+
+export class UseComputerError extends Error {}
+
+export class PlatformNotSupportedError extends UseComputerError {
+  constructor(
+    public action: string,
+    public sandboxType: string,
+    public hint: string,
+  ) {
+    super(`${action} not supported on ${sandboxType} sandbox: ${hint}`);
+  }
+}
+
+export class HttpClient {
+  readonly baseUrl: string;
+  private readonly apiKey: string;
+
+  constructor(baseUrl: string, apiKey: string) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = apiKey;
+  }
+
+  private headers(extra?: Record<string, string>): Record<string, string> {
+    const h: Record<string, string> = { ...extra };
+    if (this.apiKey) h["Authorization"] = `Bearer ${this.apiKey}`;
+    return h;
+  }
+
+  private async check(resp: Response, path: string): Promise<Response> {
+    if (resp.ok) return resp;
+    const body = await resp.text().catch(() => "");
+    throw new UseComputerError(`${resp.status} ${path}: ${body.slice(0, 500)}`);
+  }
+
+  async getJSON<T = unknown>(path: string, params?: Record<string, string>): Promise<T> {
+    const url = new URL(this.baseUrl + path);
+    if (params) for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+    const resp = await this.check(await fetch(url, { headers: this.headers() }), path);
+    return (await resp.json()) as T;
+  }
+
+  async getBytes(path: string, params?: Record<string, string>): Promise<Uint8Array> {
+    const url = new URL(this.baseUrl + path);
+    if (params) for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+    const resp = await this.check(await fetch(url, { headers: this.headers() }), path);
+    return new Uint8Array(await resp.arrayBuffer());
+  }
+
+  async postJSON<T = unknown>(path: string, body?: unknown, timeoutMs = 180_000): Promise<T> {
+    const resp = await this.check(
+      await fetch(this.baseUrl + path, {
+        method: "POST",
+        headers: this.headers({ "Content-Type": "application/json" }),
+        body: body === undefined ? "{}" : JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+      }),
+      path,
+    );
+    const ct = resp.headers.get("content-type") ?? "";
+    if (ct.startsWith("application/json")) return (await resp.json()) as T;
+    return undefined as T;
+  }
+
+  /** POST returning either an image (screenshot) or JSON — used by /act. */
+  async postActionRaw(path: string, body: unknown): Promise<{ image?: Uint8Array; data?: unknown }> {
+    const resp = await this.check(
+      await fetch(this.baseUrl + path, {
+        method: "POST",
+        headers: this.headers({ "Content-Type": "application/json" }),
+        body: JSON.stringify(body),
+      }),
+      path,
+    );
+    const ct = resp.headers.get("content-type") ?? "";
+    if (ct.startsWith("image/")) return { image: new Uint8Array(await resp.arrayBuffer()) };
+    return { data: await resp.json() };
+  }
+
+  async putBytes(path: string, data: Uint8Array, params?: Record<string, string>): Promise<void> {
+    const url = new URL(this.baseUrl + path);
+    if (params) for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+    await this.check(
+      await fetch(url, {
+        method: "PUT",
+        headers: this.headers({ "Content-Type": "application/octet-stream" }),
+        body: data as unknown as BodyInit,
+      }),
+      path,
+    );
+  }
+
+  async delete(path: string): Promise<void> {
+    await this.check(await fetch(this.baseUrl + path, { method: "DELETE", headers: this.headers() }), path);
+  }
+}

use_computer-0.0.22/javascript/src/index.ts

@@ -0,0 +1,11 @@
+export { Computer } from "./client.js";
+export type { ComputerOptions, CreateOptions } from "./client.js";
+export {
+  Sandbox,
+  MacOSSandbox,
+  WindowsSandbox,
+  UbuntuSandbox,
+  IOSSandbox,
+} from "./sandbox.js";
+export type { SandboxType, ExecResult, RecordingInfo, AnySandbox, WindowsShellKind } from "./sandbox.js";
+export { UseComputerError, PlatformNotSupportedError } from "./http.js";

use_computer-0.0.22/javascript/src/sandbox.ts

@@ -0,0 +1,208 @@
+import { HttpClient, PlatformNotSupportedError } from "./http.js";
+
+export type SandboxType = "macos" | "ios" | "windows" | "ubuntu";
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface RecordingInfo {
+  recordingId: string;
+  fileSize?: number;
+}
+
+function execFromJSON(d: Record<string, unknown>): ExecResult {
+  return {
+    stdout: String(d.stdout ?? ""),
+    stderr: String(d.stderr ?? ""),
+    exitCode: Number(d.exit_code ?? d.return_code ?? d.returncode ?? 0),
+  };
+}
+
+// --- action sub-objects (each bound to a sandbox's HTTP prefix) ---
+
+class Screenshot {
+  constructor(private http: HttpClient, private prefix: string) {}
+  takeFullScreen(): Promise<Uint8Array> {
+    return this.http.getBytes(`${this.prefix}/screenshot`);
+  }
+  takeCompressed(): Promise<Uint8Array> {
+    return this.http.getBytes(`${this.prefix}/screenshot/compressed`);
+  }
+}
+
+class Mouse {
+  constructor(private http: HttpClient, private prefix: string) {}
+  move(x: number, y: number): Promise<void> {
+    return this.http.postJSON(`${this.prefix}/mouse/move`, { x, y });
+  }
+  async click(x: number, y: number, button = "left"): Promise<void> {
+    await this.http.postActionRaw(`${this.prefix}/act`, { action: { type: "click", x, y, button } });
+  }
+  async doubleClick(x: number, y: number): Promise<void> {
+    await this.http.postActionRaw(`${this.prefix}/act`, { action: { type: "double_click", x, y } });
+  }
+  async scroll(x: number, y: number, dx: number, dy: number): Promise<void> {
+    await this.http.postActionRaw(`${this.prefix}/act`, { action: { type: "scroll", x, y, scroll_x: dx, scroll_y: dy } });
+  }
+  async drag(path: Array<[number, number]>): Promise<void> {
+    await this.http.postActionRaw(`${this.prefix}/act`, { action: { type: "drag", path } });
+  }
+  position(): Promise<{ x: number; y: number }> {
+    return this.http.getJSON(`${this.prefix}/mouse/position`);
+  }
+}
+
+class Keyboard {
+  constructor(private http: HttpClient, private prefix: string) {}
+  type(text: string): Promise<void> {
+    return this.http.postJSON(`${this.prefix}/keyboard/type`, { text });
+  }
+  press(key: string): Promise<void> {
+    return this.http.postJSON(`${this.prefix}/keyboard/press`, { key });
+  }
+  /** e.g. "ctrl+c" (macOS: "cmd+c", windows: "ctrl+c", "win+d"). */
+  hotkey(combo: string): Promise<void> {
+    return this.http.postJSON(`${this.prefix}/keyboard/hotkey`, { keys: combo });
+  }
+}
+
+class Recording {
+  constructor(private http: HttpClient, private prefix: string) {}
+  async start(): Promise<string> {
+    const d = await this.http.postJSON<Record<string, unknown>>(`${this.prefix}/recording/start`);
+    return String(d.recording_id ?? d.id ?? "");
+  }
+  async stop(recordingId: string): Promise<RecordingInfo> {
+    const d = await this.http.postJSON<Record<string, unknown>>(`${this.prefix}/recording/stop`, { recording_id: recordingId });
+    return { recordingId: String(d.recording_id ?? recordingId), fileSize: Number(d.file_size ?? 0) };
+  }
+  async listAll(): Promise<RecordingInfo[]> {
+    const d = await this.http.getJSON<unknown>(`${this.prefix}/recordings`);
+    const items = Array.isArray(d) ? d : ((d as Record<string, unknown>).recordings as unknown[]) ?? [];
+    return items.map((r) => {
+      const o = r as Record<string, unknown>;
+      return { recordingId: String(o.recording_id ?? o.id ?? ""), fileSize: Number(o.file_size ?? 0) };
+    });
+  }
+  download(recordingId: string): Promise<Uint8Array> {
+    return this.http.getBytes(`${this.prefix}/recordings/${recordingId}/download`);
+  }
+}
+
+// --- sandboxes ---
+
+export class Sandbox {
+  readonly screenshot: Screenshot;
+  readonly recording: Recording;
+  protected readonly http: HttpClient;
+  protected readonly prefix: string;
+
+  constructor(
+    readonly sandboxId: string,
+    readonly type: SandboxType,
+    http: HttpClient,
+    readonly vncUrl = "",
+  ) {
+    this.http = http;
+    this.prefix = `/v1/sandboxes/${sandboxId}`;
+    this.screenshot = new Screenshot(http, this.prefix);
+    this.recording = new Recording(http, this.prefix);
+  }
+
+  /** Native UI tree (macOS axe schema / Windows UIAutomation). */
+  uiTree(): Promise<unknown> {
+    return this.http.getJSON(`${this.prefix}/display/windows`);
+  }
+
+  displayInfo(): Promise<{ width: number; height: number }> {
+    return this.http.getJSON(`${this.prefix}/display/info`);
+  }
+
+  async upload(data: Uint8Array, remotePath: string): Promise<void> {
+    await this.http.putBytes(`${this.prefix}/files`, data, { path: remotePath });
+  }
+
+  download(remotePath: string): Promise<Uint8Array> {
+    return this.http.getBytes(`${this.prefix}/files`, { path: remotePath });
+  }
+
+  async keepalive(): Promise<void> {
+    await this.http.postJSON(`${this.prefix}/keepalive`);
+  }
+
+  async close(): Promise<void> {
+    await this.http.delete(this.prefix);
+  }
+}
+
+export class MacOSSandbox extends Sandbox {
+  readonly mouse: Mouse;
+  readonly keyboard: Keyboard;
+  constructor(sandboxId: string, http: HttpClient, vncUrl = "", readonly sshUrl = "", readonly vmIp = "") {
+    super(sandboxId, "macos", http, vncUrl);
+    this.mouse = new Mouse(http, this.prefix);
+    this.keyboard = new Keyboard(http, this.prefix);
+  }
+  async execSsh(command: string, timeoutMs = 120_000): Promise<ExecResult> {
+    const d = await this.http.postJSON<Record<string, unknown>>(`${this.prefix}/exec`, { command }, timeoutMs);
+    return execFromJSON(d);
+  }
+}
+
+export type WindowsShellKind = "powershell" | "cmd";
+
+export class WindowsSandbox extends Sandbox {
+  readonly mouse: Mouse;
+  readonly keyboard: Keyboard;
+  constructor(sandboxId: string, http: HttpClient, vncUrl = "") {
+    super(sandboxId, "windows", http, vncUrl);
+    this.mouse = new Mouse(http, this.prefix);
+    this.keyboard = new Keyboard(http, this.prefix);
+  }
+  /** Run a command in-guest (no SSH). PowerShell by default. */
+  async run(command: string, shell: WindowsShellKind = "powershell", timeoutMs = 120_000): Promise<ExecResult> {
+    const d = await this.http.postJSON<Record<string, unknown>>(`${this.prefix}/exec`, { command, shell }, timeoutMs);
+    return execFromJSON(d);
+  }
+}
+
+export class UbuntuSandbox extends Sandbox {
+  readonly mouse: Mouse;
+  readonly keyboard: Keyboard;
+  constructor(sandboxId: string, http: HttpClient, vncUrl = "") {
+    super(sandboxId, "ubuntu", http, vncUrl);
+    this.mouse = new Mouse(http, this.prefix);
+    this.keyboard = new Keyboard(http, this.prefix);
+  }
+  async exec(command: string, timeoutMs = 120_000): Promise<ExecResult> {
+    const d = await this.http.postJSON<Record<string, unknown>>(`${this.prefix}/exec`, { command }, timeoutMs);
+    return execFromJSON(d);
+  }
+}
+
+export class IOSSandbox extends Sandbox {
+  constructor(sandboxId: string, http: HttpClient, vncUrl = "") {
+    super(sandboxId, "ios", http, vncUrl);
+  }
+  tap(x: number, y: number): Promise<void> {
+    return this.http.postJSON(`${this.prefix}/tap`, { x, y });
+  }
+  pressButton(button: string): Promise<void> {
+    return this.http.postJSON(`${this.prefix}/button`, { button });
+  }
+  pressRemote(button: string): Promise<void> {
+    return this.http.postJSON(`${this.prefix}/remote`, { button });
+  }
+  launch(bundleId: string): Promise<void> {
+    return this.http.postJSON(`${this.prefix}/launch`, { bundle_id: bundleId });
+  }
+  // axe-schema accessibility is macOS-only.
+  uiTree(): Promise<unknown> {
+    return Promise.reject(new PlatformNotSupportedError("ui_tree", "ios", "use screenshots + tap coordinates"));
+  }
+}
+
+export type AnySandbox = MacOSSandbox | WindowsSandbox | UbuntuSandbox | IOSSandbox;

use_computer-0.0.22/javascript/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"]
+}

{use_computer-0.0.20 → use_computer-0.0.22}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "use-computer"
-version = "0.0.20"
+version = "0.0.22"
 description = "Python SDK for the use.computer macOS and iOS Computer Use API"
 readme = "README.md"
 requires-python = ">=3.10"