This is page 1 of 28. Use http://codebase.md/trycua/cua?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .cursorignore
├── .dockerignore
├── .editorconfig
├── .gitattributes
├── .github
│ ├── FUNDING.yml
│ ├── scripts
│ │ ├── get_pyproject_version.py
│ │ └── tests
│ │ ├── __init__.py
│ │ ├── README.md
│ │ └── test_get_pyproject_version.py
│ └── workflows
│ ├── bump-version.yml
│ ├── ci-lume.yml
│ ├── docker-publish-cua-linux.yml
│ ├── docker-publish-cua-windows.yml
│ ├── docker-publish-kasm.yml
│ ├── docker-publish-xfce.yml
│ ├── docker-reusable-publish.yml
│ ├── link-check.yml
│ ├── lint.yml
│ ├── npm-publish-cli.yml
│ ├── npm-publish-computer.yml
│ ├── npm-publish-core.yml
│ ├── publish-lume.yml
│ ├── pypi-publish-agent.yml
│ ├── pypi-publish-computer-server.yml
│ ├── pypi-publish-computer.yml
│ ├── pypi-publish-core.yml
│ ├── pypi-publish-mcp-server.yml
│ ├── pypi-publish-som.yml
│ ├── pypi-reusable-publish.yml
│ ├── python-tests.yml
│ ├── test-cua-models.yml
│ └── test-validation-script.yml
├── .gitignore
├── .pre-commit-config.yaml
├── .prettierignore
├── .prettierrc.yaml
├── .vscode
│ ├── docs.code-workspace
│ ├── extensions.json
│ ├── launch.json
│ ├── libs-ts.code-workspace
│ ├── lume.code-workspace
│ ├── lumier.code-workspace
│ ├── py.code-workspace
│ └── settings.json
├── blog
│ ├── app-use.md
│ ├── assets
│ │ ├── composite-agents.png
│ │ ├── docker-ubuntu-support.png
│ │ ├── hack-booth.png
│ │ ├── hack-closing-ceremony.jpg
│ │ ├── hack-cua-ollama-hud.jpeg
│ │ ├── hack-leaderboard.png
│ │ ├── hack-the-north.png
│ │ ├── hack-winners.jpeg
│ │ ├── hack-workshop.jpeg
│ │ ├── hud-agent-evals.png
│ │ └── trajectory-viewer.jpeg
│ ├── bringing-computer-use-to-the-web.md
│ ├── build-your-own-operator-on-macos-1.md
│ ├── build-your-own-operator-on-macos-2.md
│ ├── cloud-windows-ga-macos-preview.md
│ ├── composite-agents.md
│ ├── computer-use-agents-for-growth-hacking.md
│ ├── cua-hackathon.md
│ ├── cua-playground-preview.md
│ ├── cua-vlm-router.md
│ ├── hack-the-north.md
│ ├── hud-agent-evals.md
│ ├── human-in-the-loop.md
│ ├── introducing-cua-cli.md
│ ├── introducing-cua-cloud-containers.md
│ ├── lume-to-containerization.md
│ ├── neurips-2025-cua-papers.md
│ ├── sandboxed-python-execution.md
│ ├── training-computer-use-models-trajectories-1.md
│ ├── trajectory-viewer.md
│ ├── ubuntu-docker-support.md
│ └── windows-sandbox.md
├── CONTRIBUTING.md
├── Development.md
├── Dockerfile
├── docs
│ ├── .env.example
│ ├── .gitignore
│ ├── content
│ │ └── docs
│ │ ├── agent-sdk
│ │ │ ├── agent-loops.mdx
│ │ │ ├── benchmarks
│ │ │ │ ├── index.mdx
│ │ │ │ ├── interactive.mdx
│ │ │ │ ├── introduction.mdx
│ │ │ │ ├── meta.json
│ │ │ │ ├── osworld-verified.mdx
│ │ │ │ ├── screenspot-pro.mdx
│ │ │ │ └── screenspot-v2.mdx
│ │ │ ├── callbacks
│ │ │ │ ├── agent-lifecycle.mdx
│ │ │ │ ├── cost-saving.mdx
│ │ │ │ ├── index.mdx
│ │ │ │ ├── logging.mdx
│ │ │ │ ├── meta.json
│ │ │ │ ├── pii-anonymization.mdx
│ │ │ │ └── trajectories.mdx
│ │ │ ├── chat-history.mdx
│ │ │ ├── custom-tools.mdx
│ │ │ ├── customizing-computeragent.mdx
│ │ │ ├── integrations
│ │ │ │ ├── hud.mdx
│ │ │ │ ├── meta.json
│ │ │ │ └── observability.mdx
│ │ │ ├── mcp-server
│ │ │ │ ├── client-integrations.mdx
│ │ │ │ ├── configuration.mdx
│ │ │ │ ├── index.mdx
│ │ │ │ ├── installation.mdx
│ │ │ │ ├── llm-integrations.mdx
│ │ │ │ ├── meta.json
│ │ │ │ ├── tools.mdx
│ │ │ │ └── usage.mdx
│ │ │ ├── message-format.mdx
│ │ │ ├── meta.json
│ │ │ ├── migration-guide.mdx
│ │ │ ├── prompt-caching.mdx
│ │ │ ├── supported-agents
│ │ │ │ ├── composed-agents.mdx
│ │ │ │ ├── computer-use-agents.mdx
│ │ │ │ ├── grounding-models.mdx
│ │ │ │ ├── human-in-the-loop.mdx
│ │ │ │ └── meta.json
│ │ │ ├── supported-model-providers
│ │ │ │ ├── cua-vlm-router.mdx
│ │ │ │ ├── index.mdx
│ │ │ │ └── local-models.mdx
│ │ │ ├── telemetry.mdx
│ │ │ └── usage-tracking.mdx
│ │ ├── cli-playbook
│ │ │ ├── commands.mdx
│ │ │ ├── index.mdx
│ │ │ └── meta.json
│ │ ├── computer-sdk
│ │ │ ├── cloud-vm-management.mdx
│ │ │ ├── commands.mdx
│ │ │ ├── computer-server
│ │ │ │ ├── Commands.mdx
│ │ │ │ ├── index.mdx
│ │ │ │ ├── meta.json
│ │ │ │ ├── REST-API.mdx
│ │ │ │ └── WebSocket-API.mdx
│ │ │ ├── computer-ui.mdx
│ │ │ ├── computers.mdx
│ │ │ ├── custom-computer-handlers.mdx
│ │ │ ├── meta.json
│ │ │ ├── sandboxed-python.mdx
│ │ │ └── tracing-api.mdx
│ │ ├── example-usecases
│ │ │ ├── form-filling.mdx
│ │ │ ├── gemini-complex-ui-navigation.mdx
│ │ │ ├── meta.json
│ │ │ ├── post-event-contact-export.mdx
│ │ │ └── windows-app-behind-vpn.mdx
│ │ ├── get-started
│ │ │ ├── meta.json
│ │ │ └── quickstart.mdx
│ │ ├── index.mdx
│ │ ├── macos-vm-cli-playbook
│ │ │ ├── lume
│ │ │ │ ├── cli-reference.mdx
│ │ │ │ ├── faq.md
│ │ │ │ ├── http-api.mdx
│ │ │ │ ├── index.mdx
│ │ │ │ ├── installation.mdx
│ │ │ │ ├── meta.json
│ │ │ │ └── prebuilt-images.mdx
│ │ │ ├── lumier
│ │ │ │ ├── building-lumier.mdx
│ │ │ │ ├── docker-compose.mdx
│ │ │ │ ├── docker.mdx
│ │ │ │ ├── index.mdx
│ │ │ │ ├── installation.mdx
│ │ │ │ └── meta.json
│ │ │ └── meta.json
│ │ └── meta.json
│ ├── next.config.mjs
│ ├── package-lock.json
│ ├── package.json
│ ├── pnpm-lock.yaml
│ ├── postcss.config.mjs
│ ├── public
│ │ └── img
│ │ ├── agent_gradio_ui.png
│ │ ├── agent.png
│ │ ├── bg-dark.jpg
│ │ ├── bg-light.jpg
│ │ ├── cli.png
│ │ ├── computer.png
│ │ ├── grounding-with-gemini3.gif
│ │ ├── hero.png
│ │ ├── laminar_trace_example.png
│ │ ├── som_box_threshold.png
│ │ └── som_iou_threshold.png
│ ├── README.md
│ ├── source.config.ts
│ ├── src
│ │ ├── app
│ │ │ ├── (home)
│ │ │ │ ├── [[...slug]]
│ │ │ │ │ └── page.tsx
│ │ │ │ └── layout.tsx
│ │ │ ├── api
│ │ │ │ ├── posthog
│ │ │ │ │ └── [...path]
│ │ │ │ │ └── route.ts
│ │ │ │ └── search
│ │ │ │ └── route.ts
│ │ │ ├── favicon.ico
│ │ │ ├── global.css
│ │ │ ├── layout.config.tsx
│ │ │ ├── layout.tsx
│ │ │ ├── llms.mdx
│ │ │ │ └── [[...slug]]
│ │ │ │ └── route.ts
│ │ │ ├── llms.txt
│ │ │ │ └── route.ts
│ │ │ ├── robots.ts
│ │ │ └── sitemap.ts
│ │ ├── assets
│ │ │ ├── discord-black.svg
│ │ │ ├── discord-white.svg
│ │ │ ├── logo-black.svg
│ │ │ └── logo-white.svg
│ │ ├── components
│ │ │ ├── analytics-tracker.tsx
│ │ │ ├── cookie-consent.tsx
│ │ │ ├── doc-actions-menu.tsx
│ │ │ ├── editable-code-block.tsx
│ │ │ ├── footer.tsx
│ │ │ ├── hero.tsx
│ │ │ ├── iou.tsx
│ │ │ ├── mermaid.tsx
│ │ │ └── page-feedback.tsx
│ │ ├── lib
│ │ │ ├── llms.ts
│ │ │ └── source.ts
│ │ ├── mdx-components.tsx
│ │ └── providers
│ │ └── posthog-provider.tsx
│ └── tsconfig.json
├── examples
│ ├── agent_examples.py
│ ├── agent_ui_examples.py
│ ├── browser_tool_example.py
│ ├── cloud_api_examples.py
│ ├── computer_examples_windows.py
│ ├── computer_examples.py
│ ├── computer_ui_examples.py
│ ├── computer-example-ts
│ │ ├── .env.example
│ │ ├── .gitignore
│ │ ├── package-lock.json
│ │ ├── package.json
│ │ ├── pnpm-lock.yaml
│ │ ├── README.md
│ │ ├── src
│ │ │ ├── helpers.ts
│ │ │ └── index.ts
│ │ └── tsconfig.json
│ ├── docker_examples.py
│ ├── evals
│ │ ├── hud_eval_examples.py
│ │ └── wikipedia_most_linked.txt
│ ├── pylume_examples.py
│ ├── sandboxed_functions_examples.py
│ ├── som_examples.py
│ ├── tracing_examples.py
│ ├── utils.py
│ └── winsandbox_example.py
├── img
│ ├── agent_gradio_ui.png
│ ├── agent.png
│ ├── cli.png
│ ├── computer.png
│ ├── logo_black.png
│ └── logo_white.png
├── libs
│ ├── kasm
│ │ ├── Dockerfile
│ │ ├── LICENSE
│ │ ├── README.md
│ │ └── src
│ │ └── ubuntu
│ │ └── install
│ │ └── firefox
│ │ ├── custom_startup.sh
│ │ ├── firefox.desktop
│ │ └── install_firefox.sh
│ ├── lume
│ │ ├── .cursorignore
│ │ ├── CONTRIBUTING.md
│ │ ├── Development.md
│ │ ├── img
│ │ │ └── cli.png
│ │ ├── Package.resolved
│ │ ├── Package.swift
│ │ ├── README.md
│ │ ├── resources
│ │ │ └── lume.entitlements
│ │ ├── scripts
│ │ │ ├── build
│ │ │ │ ├── build-debug.sh
│ │ │ │ ├── build-release-notarized.sh
│ │ │ │ └── build-release.sh
│ │ │ └── install.sh
│ │ ├── src
│ │ │ ├── Commands
│ │ │ │ ├── Clone.swift
│ │ │ │ ├── Config.swift
│ │ │ │ ├── Create.swift
│ │ │ │ ├── Delete.swift
│ │ │ │ ├── Get.swift
│ │ │ │ ├── Images.swift
│ │ │ │ ├── IPSW.swift
│ │ │ │ ├── List.swift
│ │ │ │ ├── Logs.swift
│ │ │ │ ├── Options
│ │ │ │ │ └── FormatOption.swift
│ │ │ │ ├── Prune.swift
│ │ │ │ ├── Pull.swift
│ │ │ │ ├── Push.swift
│ │ │ │ ├── Run.swift
│ │ │ │ ├── Serve.swift
│ │ │ │ ├── Set.swift
│ │ │ │ └── Stop.swift
│ │ │ ├── ContainerRegistry
│ │ │ │ ├── ImageContainerRegistry.swift
│ │ │ │ ├── ImageList.swift
│ │ │ │ └── ImagesPrinter.swift
│ │ │ ├── Errors
│ │ │ │ └── Errors.swift
│ │ │ ├── FileSystem
│ │ │ │ ├── Home.swift
│ │ │ │ ├── Settings.swift
│ │ │ │ ├── VMConfig.swift
│ │ │ │ ├── VMDirectory.swift
│ │ │ │ └── VMLocation.swift
│ │ │ ├── LumeController.swift
│ │ │ ├── Main.swift
│ │ │ ├── Server
│ │ │ │ ├── Handlers.swift
│ │ │ │ ├── HTTP.swift
│ │ │ │ ├── Requests.swift
│ │ │ │ ├── Responses.swift
│ │ │ │ └── Server.swift
│ │ │ ├── Utils
│ │ │ │ ├── CommandRegistry.swift
│ │ │ │ ├── CommandUtils.swift
│ │ │ │ ├── Logger.swift
│ │ │ │ ├── NetworkUtils.swift
│ │ │ │ ├── Path.swift
│ │ │ │ ├── ProcessRunner.swift
│ │ │ │ ├── ProgressLogger.swift
│ │ │ │ ├── String.swift
│ │ │ │ └── Utils.swift
│ │ │ ├── Virtualization
│ │ │ │ ├── DarwinImageLoader.swift
│ │ │ │ ├── DHCPLeaseParser.swift
│ │ │ │ ├── ImageLoaderFactory.swift
│ │ │ │ └── VMVirtualizationService.swift
│ │ │ ├── VM
│ │ │ │ ├── DarwinVM.swift
│ │ │ │ ├── LinuxVM.swift
│ │ │ │ ├── VM.swift
│ │ │ │ ├── VMDetails.swift
│ │ │ │ ├── VMDetailsPrinter.swift
│ │ │ │ ├── VMDisplayResolution.swift
│ │ │ │ └── VMFactory.swift
│ │ │ └── VNC
│ │ │ ├── PassphraseGenerator.swift
│ │ │ └── VNCService.swift
│ │ └── tests
│ │ ├── Mocks
│ │ │ ├── MockVM.swift
│ │ │ ├── MockVMVirtualizationService.swift
│ │ │ └── MockVNCService.swift
│ │ ├── VM
│ │ │ └── VMDetailsPrinterTests.swift
│ │ ├── VMTests.swift
│ │ ├── VMVirtualizationServiceTests.swift
│ │ └── VNCServiceTests.swift
│ ├── lumier
│ │ ├── .dockerignore
│ │ ├── Dockerfile
│ │ ├── README.md
│ │ └── src
│ │ ├── bin
│ │ │ └── entry.sh
│ │ ├── config
│ │ │ └── constants.sh
│ │ ├── hooks
│ │ │ └── on-logon.sh
│ │ └── lib
│ │ ├── utils.sh
│ │ └── vm.sh
│ ├── python
│ │ ├── agent
│ │ │ ├── .bumpversion.cfg
│ │ │ ├── agent
│ │ │ │ ├── __init__.py
│ │ │ │ ├── __main__.py
│ │ │ │ ├── adapters
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── cua_adapter.py
│ │ │ │ │ ├── huggingfacelocal_adapter.py
│ │ │ │ │ ├── human_adapter.py
│ │ │ │ │ ├── mlxvlm_adapter.py
│ │ │ │ │ └── models
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── generic.py
│ │ │ │ │ ├── internvl.py
│ │ │ │ │ ├── opencua.py
│ │ │ │ │ └── qwen2_5_vl.py
│ │ │ │ ├── agent.py
│ │ │ │ ├── callbacks
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── base.py
│ │ │ │ │ ├── budget_manager.py
│ │ │ │ │ ├── image_retention.py
│ │ │ │ │ ├── logging.py
│ │ │ │ │ ├── operator_validator.py
│ │ │ │ │ ├── pii_anonymization.py
│ │ │ │ │ ├── prompt_instructions.py
│ │ │ │ │ ├── telemetry.py
│ │ │ │ │ └── trajectory_saver.py
│ │ │ │ ├── cli.py
│ │ │ │ ├── computers
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── base.py
│ │ │ │ │ ├── cua.py
│ │ │ │ │ └── custom.py
│ │ │ │ ├── decorators.py
│ │ │ │ ├── human_tool
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── __main__.py
│ │ │ │ │ ├── server.py
│ │ │ │ │ └── ui.py
│ │ │ │ ├── integrations
│ │ │ │ │ └── hud
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── agent.py
│ │ │ │ │ └── proxy.py
│ │ │ │ ├── loops
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── anthropic.py
│ │ │ │ │ ├── base.py
│ │ │ │ │ ├── composed_grounded.py
│ │ │ │ │ ├── gelato.py
│ │ │ │ │ ├── gemini.py
│ │ │ │ │ ├── generic_vlm.py
│ │ │ │ │ ├── glm45v.py
│ │ │ │ │ ├── gta1.py
│ │ │ │ │ ├── holo.py
│ │ │ │ │ ├── internvl.py
│ │ │ │ │ ├── model_types.csv
│ │ │ │ │ ├── moondream3.py
│ │ │ │ │ ├── omniparser.py
│ │ │ │ │ ├── openai.py
│ │ │ │ │ ├── opencua.py
│ │ │ │ │ ├── uiins.py
│ │ │ │ │ ├── uitars.py
│ │ │ │ │ └── uitars2.py
│ │ │ │ ├── proxy
│ │ │ │ │ ├── examples.py
│ │ │ │ │ └── handlers.py
│ │ │ │ ├── responses.py
│ │ │ │ ├── tools
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ └── browser_tool.py
│ │ │ │ ├── types.py
│ │ │ │ └── ui
│ │ │ │ ├── __init__.py
│ │ │ │ ├── __main__.py
│ │ │ │ └── gradio
│ │ │ │ ├── __init__.py
│ │ │ │ ├── app.py
│ │ │ │ └── ui_components.py
│ │ │ ├── benchmarks
│ │ │ │ ├── .gitignore
│ │ │ │ ├── contrib.md
│ │ │ │ ├── interactive.py
│ │ │ │ ├── models
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── base.py
│ │ │ │ │ └── gta1.py
│ │ │ │ ├── README.md
│ │ │ │ ├── ss-pro.py
│ │ │ │ ├── ss-v2.py
│ │ │ │ └── utils.py
│ │ │ ├── example.py
│ │ │ ├── pyproject.toml
│ │ │ ├── README.md
│ │ │ └── tests
│ │ │ ├── conftest.py
│ │ │ └── test_computer_agent.py
│ │ ├── bench-ui
│ │ │ ├── bench_ui
│ │ │ │ ├── __init__.py
│ │ │ │ ├── api.py
│ │ │ │ └── child.py
│ │ │ ├── examples
│ │ │ │ ├── folder_example.py
│ │ │ │ ├── gui
│ │ │ │ │ ├── index.html
│ │ │ │ │ ├── logo.svg
│ │ │ │ │ └── styles.css
│ │ │ │ ├── output_overlay.png
│ │ │ │ └── simple_example.py
│ │ │ ├── pyproject.toml
│ │ │ ├── README.md
│ │ │ └── tests
│ │ │ └── test_port_detection.py
│ │ ├── computer
│ │ │ ├── .bumpversion.cfg
│ │ │ ├── computer
│ │ │ │ ├── __init__.py
│ │ │ │ ├── computer.py
│ │ │ │ ├── diorama_computer.py
│ │ │ │ ├── helpers.py
│ │ │ │ ├── interface
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── base.py
│ │ │ │ │ ├── factory.py
│ │ │ │ │ ├── generic.py
│ │ │ │ │ ├── linux.py
│ │ │ │ │ ├── macos.py
│ │ │ │ │ ├── models.py
│ │ │ │ │ └── windows.py
│ │ │ │ ├── logger.py
│ │ │ │ ├── models.py
│ │ │ │ ├── providers
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── base.py
│ │ │ │ │ ├── cloud
│ │ │ │ │ │ ├── __init__.py
│ │ │ │ │ │ └── provider.py
│ │ │ │ │ ├── docker
│ │ │ │ │ │ ├── __init__.py
│ │ │ │ │ │ └── provider.py
│ │ │ │ │ ├── factory.py
│ │ │ │ │ ├── lume
│ │ │ │ │ │ ├── __init__.py
│ │ │ │ │ │ └── provider.py
│ │ │ │ │ ├── lume_api.py
│ │ │ │ │ ├── lumier
│ │ │ │ │ │ ├── __init__.py
│ │ │ │ │ │ └── provider.py
│ │ │ │ │ ├── types.py
│ │ │ │ │ └── winsandbox
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── provider.py
│ │ │ │ │ └── setup_script.ps1
│ │ │ │ ├── tracing_wrapper.py
│ │ │ │ ├── tracing.py
│ │ │ │ ├── ui
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── __main__.py
│ │ │ │ │ └── gradio
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ └── app.py
│ │ │ │ └── utils.py
│ │ │ ├── poetry.toml
│ │ │ ├── pyproject.toml
│ │ │ ├── README.md
│ │ │ └── tests
│ │ │ ├── conftest.py
│ │ │ └── test_computer.py
│ │ ├── computer-server
│ │ │ ├── .bumpversion.cfg
│ │ │ ├── computer_server
│ │ │ │ ├── __init__.py
│ │ │ │ ├── __main__.py
│ │ │ │ ├── browser.py
│ │ │ │ ├── cli.py
│ │ │ │ ├── diorama
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── base.py
│ │ │ │ │ ├── diorama_computer.py
│ │ │ │ │ ├── diorama.py
│ │ │ │ │ ├── draw.py
│ │ │ │ │ ├── macos.py
│ │ │ │ │ └── safezone.py
│ │ │ │ ├── handlers
│ │ │ │ │ ├── base.py
│ │ │ │ │ ├── factory.py
│ │ │ │ │ ├── generic.py
│ │ │ │ │ ├── linux.py
│ │ │ │ │ ├── macos.py
│ │ │ │ │ └── windows.py
│ │ │ │ ├── main.py
│ │ │ │ ├── server.py
│ │ │ │ ├── utils
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ └── wallpaper.py
│ │ │ │ └── watchdog.py
│ │ │ ├── examples
│ │ │ │ ├── __init__.py
│ │ │ │ └── usage_example.py
│ │ │ ├── pyproject.toml
│ │ │ ├── README.md
│ │ │ ├── run_server.py
│ │ │ ├── test_connection.py
│ │ │ └── tests
│ │ │ ├── conftest.py
│ │ │ └── test_server.py
│ │ ├── core
│ │ │ ├── .bumpversion.cfg
│ │ │ ├── core
│ │ │ │ ├── __init__.py
│ │ │ │ └── telemetry
│ │ │ │ ├── __init__.py
│ │ │ │ └── posthog.py
│ │ │ ├── poetry.toml
│ │ │ ├── pyproject.toml
│ │ │ ├── README.md
│ │ │ └── tests
│ │ │ ├── conftest.py
│ │ │ └── test_telemetry.py
│ │ ├── mcp-server
│ │ │ ├── .bumpversion.cfg
│ │ │ ├── build-extension.py
│ │ │ ├── CONCURRENT_SESSIONS.md
│ │ │ ├── desktop-extension
│ │ │ │ ├── cua-extension.mcpb
│ │ │ │ ├── desktop_extension.png
│ │ │ │ ├── manifest.json
│ │ │ │ ├── README.md
│ │ │ │ ├── requirements.txt
│ │ │ │ ├── run_server.sh
│ │ │ │ └── setup.py
│ │ │ ├── mcp_server
│ │ │ │ ├── __init__.py
│ │ │ │ ├── __main__.py
│ │ │ │ ├── server.py
│ │ │ │ └── session_manager.py
│ │ │ ├── pdm.lock
│ │ │ ├── pyproject.toml
│ │ │ ├── QUICK_TEST_COMMANDS.sh
│ │ │ ├── quick_test_local_option.py
│ │ │ ├── README.md
│ │ │ ├── scripts
│ │ │ │ ├── install_mcp_server.sh
│ │ │ │ └── start_mcp_server.sh
│ │ │ ├── test_mcp_server_local_option.py
│ │ │ └── tests
│ │ │ ├── conftest.py
│ │ │ └── test_mcp_server.py
│ │ ├── pylume
│ │ │ └── tests
│ │ │ ├── conftest.py
│ │ │ └── test_pylume.py
│ │ └── som
│ │ ├── .bumpversion.cfg
│ │ ├── LICENSE
│ │ ├── poetry.toml
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ ├── som
│ │ │ ├── __init__.py
│ │ │ ├── detect.py
│ │ │ ├── detection.py
│ │ │ ├── models.py
│ │ │ ├── ocr.py
│ │ │ ├── util
│ │ │ │ └── utils.py
│ │ │ └── visualization.py
│ │ └── tests
│ │ ├── conftest.py
│ │ └── test_omniparser.py
│ ├── qemu-docker
│ │ ├── linux
│ │ │ ├── Dockerfile
│ │ │ ├── README.md
│ │ │ └── src
│ │ │ ├── entry.sh
│ │ │ └── vm
│ │ │ ├── image
│ │ │ │ └── README.md
│ │ │ └── setup
│ │ │ ├── install.sh
│ │ │ ├── setup-cua-server.sh
│ │ │ └── setup.sh
│ │ ├── README.md
│ │ └── windows
│ │ ├── Dockerfile
│ │ ├── README.md
│ │ └── src
│ │ ├── entry.sh
│ │ └── vm
│ │ ├── image
│ │ │ └── README.md
│ │ └── setup
│ │ ├── install.bat
│ │ ├── on-logon.ps1
│ │ ├── setup-cua-server.ps1
│ │ ├── setup-utils.psm1
│ │ └── setup.ps1
│ ├── typescript
│ │ ├── .gitignore
│ │ ├── .nvmrc
│ │ ├── agent
│ │ │ ├── examples
│ │ │ │ ├── playground-example.html
│ │ │ │ └── README.md
│ │ │ ├── package.json
│ │ │ ├── README.md
│ │ │ ├── src
│ │ │ │ ├── client.ts
│ │ │ │ ├── index.ts
│ │ │ │ └── types.ts
│ │ │ ├── tests
│ │ │ │ └── client.test.ts
│ │ │ ├── tsconfig.json
│ │ │ ├── tsdown.config.ts
│ │ │ └── vitest.config.ts
│ │ ├── computer
│ │ │ ├── .editorconfig
│ │ │ ├── .gitattributes
│ │ │ ├── .gitignore
│ │ │ ├── LICENSE
│ │ │ ├── package.json
│ │ │ ├── README.md
│ │ │ ├── src
│ │ │ │ ├── computer
│ │ │ │ │ ├── index.ts
│ │ │ │ │ ├── providers
│ │ │ │ │ │ ├── base.ts
│ │ │ │ │ │ ├── cloud.ts
│ │ │ │ │ │ └── index.ts
│ │ │ │ │ └── types.ts
│ │ │ │ ├── index.ts
│ │ │ │ ├── interface
│ │ │ │ │ ├── base.ts
│ │ │ │ │ ├── factory.ts
│ │ │ │ │ ├── index.ts
│ │ │ │ │ ├── linux.ts
│ │ │ │ │ ├── macos.ts
│ │ │ │ │ └── windows.ts
│ │ │ │ └── types.ts
│ │ │ ├── tests
│ │ │ │ ├── computer
│ │ │ │ │ └── cloud.test.ts
│ │ │ │ ├── interface
│ │ │ │ │ ├── factory.test.ts
│ │ │ │ │ ├── index.test.ts
│ │ │ │ │ ├── linux.test.ts
│ │ │ │ │ ├── macos.test.ts
│ │ │ │ │ └── windows.test.ts
│ │ │ │ └── setup.ts
│ │ │ ├── tsconfig.json
│ │ │ ├── tsdown.config.ts
│ │ │ └── vitest.config.ts
│ │ ├── core
│ │ │ ├── .editorconfig
│ │ │ ├── .gitattributes
│ │ │ ├── .gitignore
│ │ │ ├── LICENSE
│ │ │ ├── package.json
│ │ │ ├── README.md
│ │ │ ├── src
│ │ │ │ ├── index.ts
│ │ │ │ └── telemetry
│ │ │ │ ├── clients
│ │ │ │ │ ├── index.ts
│ │ │ │ │ └── posthog.ts
│ │ │ │ └── index.ts
│ │ │ ├── tests
│ │ │ │ └── telemetry.test.ts
│ │ │ ├── tsconfig.json
│ │ │ ├── tsdown.config.ts
│ │ │ └── vitest.config.ts
│ │ ├── cua-cli
│ │ │ ├── .gitignore
│ │ │ ├── .prettierrc
│ │ │ ├── bun.lock
│ │ │ ├── CLAUDE.md
│ │ │ ├── index.ts
│ │ │ ├── package.json
│ │ │ ├── README.md
│ │ │ ├── src
│ │ │ │ ├── auth.ts
│ │ │ │ ├── cli.ts
│ │ │ │ ├── commands
│ │ │ │ │ ├── auth.ts
│ │ │ │ │ └── sandbox.ts
│ │ │ │ ├── config.ts
│ │ │ │ ├── http.ts
│ │ │ │ ├── storage.ts
│ │ │ │ └── util.ts
│ │ │ └── tsconfig.json
│ │ ├── package.json
│ │ ├── pnpm-lock.yaml
│ │ ├── pnpm-workspace.yaml
│ │ └── README.md
│ └── xfce
│ ├── .dockerignore
│ ├── .gitignore
│ ├── Development.md
│ ├── Dockerfile
│ ├── Dockerfile.dev
│ ├── README.md
│ └── src
│ ├── scripts
│ │ ├── resize-display.sh
│ │ ├── start-computer-server.sh
│ │ ├── start-novnc.sh
│ │ ├── start-vnc.sh
│ │ └── xstartup.sh
│ ├── supervisor
│ │ └── supervisord.conf
│ └── xfce-config
│ ├── helpers.rc
│ ├── xfce4-power-manager.xml
│ └── xfce4-session.xml
├── LICENSE.md
├── Makefile
├── notebooks
│ ├── agent_nb.ipynb
│ ├── blog
│ │ ├── build-your-own-operator-on-macos-1.ipynb
│ │ └── build-your-own-operator-on-macos-2.ipynb
│ ├── composite_agents_docker_nb.ipynb
│ ├── computer_nb.ipynb
│ ├── computer_server_nb.ipynb
│ ├── customizing_computeragent.ipynb
│ ├── eval_osworld.ipynb
│ ├── ollama_nb.ipynb
│ ├── README.md
│ ├── sota_hackathon_cloud.ipynb
│ └── sota_hackathon.ipynb
├── package-lock.json
├── package.json
├── pnpm-lock.yaml
├── pyproject.toml
├── pyrightconfig.json
├── README.md
├── scripts
│ ├── install-cli.ps1
│ ├── install-cli.sh
│ ├── playground-docker.sh
│ ├── playground.sh
│ ├── run-docker-dev.sh
│ └── typescript-typecheck.js
├── TESTING.md
├── tests
│ ├── agent_loop_testing
│ │ ├── agent_test.py
│ │ └── README.md
│ ├── pytest.ini
│ ├── shell_cmd.py
│ ├── test_files.py
│ ├── test_mcp_server_session_management.py
│ ├── test_mcp_server_streaming.py
│ ├── test_shell_bash.py
│ ├── test_telemetry.py
│ ├── test_tracing.py
│ ├── test_venv.py
│ └── test_watchdog.py
└── uv.lock
```
# Files
--------------------------------------------------------------------------------
/libs/typescript/.nvmrc:
--------------------------------------------------------------------------------
```
1 | v24.2.0
2 |
```
--------------------------------------------------------------------------------
/libs/typescript/computer/.gitattributes:
--------------------------------------------------------------------------------
```
1 | * text=auto eol=lf
2 |
```
--------------------------------------------------------------------------------
/libs/typescript/core/.gitattributes:
--------------------------------------------------------------------------------
```
1 | * text=auto eol=lf
2 |
```
--------------------------------------------------------------------------------
/examples/computer-example-ts/.gitignore:
--------------------------------------------------------------------------------
```
1 | node_modules
2 | .DS_Store
3 | .env
```
--------------------------------------------------------------------------------
/libs/xfce/.gitignore:
--------------------------------------------------------------------------------
```
1 | storage/
2 | shared/
3 | *.log
4 | .DS_Store
5 |
```
--------------------------------------------------------------------------------
/.gitattributes:
--------------------------------------------------------------------------------
```
1 | * text=auto
2 | *.sh text eol=lf
```
--------------------------------------------------------------------------------
/libs/xfce/.dockerignore:
--------------------------------------------------------------------------------
```
1 | README.md
2 | .git
3 | .gitignore
4 | *.md
5 | LICENSE
6 |
```
--------------------------------------------------------------------------------
/libs/python/agent/benchmarks/.gitignore:
--------------------------------------------------------------------------------
```
1 | output/
2 | interactive_output/
3 | *_results.md
```
--------------------------------------------------------------------------------
/libs/typescript/.gitignore:
--------------------------------------------------------------------------------
```
1 | node_modules
2 |
3 | *.log
4 | .DS_Store
5 | .eslintcache
6 |
```
--------------------------------------------------------------------------------
/examples/computer-example-ts/.env.example:
--------------------------------------------------------------------------------
```
1 | OPENAI_API_KEY=
2 | CUA_API_KEY=
3 | CUA_CONTAINER_NAME=
```
--------------------------------------------------------------------------------
/libs/typescript/computer/.gitignore:
--------------------------------------------------------------------------------
```
1 | node_modules
2 | dist
3 |
4 | *.log
5 | .DS_Store
6 | .eslintcache
7 |
```
--------------------------------------------------------------------------------
/libs/typescript/core/.gitignore:
--------------------------------------------------------------------------------
```
1 | node_modules
2 | dist
3 |
4 | *.log
5 | .DS_Store
6 | .eslintcache
7 |
```
--------------------------------------------------------------------------------
/docs/.env.example:
--------------------------------------------------------------------------------
```
1 | NEXT_PUBLIC_POSTHOG_API_KEY=
2 | NEXT_PUBLIC_POSTHOG_HOST=
```
--------------------------------------------------------------------------------
/libs/typescript/computer/.editorconfig:
--------------------------------------------------------------------------------
```
1 | root = true
2 |
3 | [*]
4 | indent_size = 2
5 | end_of_line = lf
6 | insert_final_newline = true
7 |
```
--------------------------------------------------------------------------------
/libs/typescript/core/.editorconfig:
--------------------------------------------------------------------------------
```
1 | root = true
2 |
3 | [*]
4 | indent_size = 2
5 | end_of_line = lf
6 | insert_final_newline = true
7 |
```
--------------------------------------------------------------------------------
/libs/typescript/cua-cli/.prettierrc:
--------------------------------------------------------------------------------
```
1 | {
2 | "semi": true,
3 | "trailingComma": "es5",
4 | "singleQuote": true,
5 | "tabWidth": 2,
6 | "useTabs": false
7 | }
8 |
```
--------------------------------------------------------------------------------
/.prettierrc.yaml:
--------------------------------------------------------------------------------
```yaml
1 | semi: true
2 | singleQuote: true
3 | trailingComma: es5
4 | tabWidth: 2
5 | printWidth: 100
6 | arrowParens: always
7 | bracketSpacing: true
8 |
9 | overrides:
10 | - files: "*.{yml,yaml}"
11 | options:
12 | singleQuote: false
13 |
```
--------------------------------------------------------------------------------
/.editorconfig:
--------------------------------------------------------------------------------
```
1 | root = true
2 |
3 | [*]
4 | indent_style = space
5 | indent_size = 4
6 | charset = utf-8
7 | end_of_line = lf
8 | insert_final_newline = false
9 | trim_trailing_whitespace = true
10 |
11 | [*.{js,ts,jsx,tsx,json,css,scss,html,md}]
12 | indent_size = 2
13 |
```
--------------------------------------------------------------------------------
/libs/python/som/.bumpversion.cfg:
--------------------------------------------------------------------------------
```
1 | [bumpversion]
2 | current_version = 0.1.3
3 | commit = True
4 | tag = True
5 | tag_name = som-v{new_version}
6 | message = Bump cua-som to v{new_version}
7 |
8 | [bumpversion:file:pyproject.toml]
9 | search = version = "{current_version}"
10 | replace = version = "{new_version}"
11 |
```
--------------------------------------------------------------------------------
/libs/python/core/.bumpversion.cfg:
--------------------------------------------------------------------------------
```
1 | [bumpversion]
2 | current_version = 0.1.9
3 | commit = True
4 | tag = True
5 | tag_name = core-v{new_version}
6 | message = Bump cua-core to v{new_version}
7 |
8 | [bumpversion:file:pyproject.toml]
9 | search = version = "{current_version}"
10 | replace = version = "{new_version}"
11 |
```
--------------------------------------------------------------------------------
/libs/python/agent/.bumpversion.cfg:
--------------------------------------------------------------------------------
```
1 | [bumpversion]
2 | current_version = 0.5.2
3 | commit = True
4 | tag = True
5 | tag_name = agent-v{new_version}
6 | message = Bump cua-agent to v{new_version}
7 |
8 | [bumpversion:file:pyproject.toml]
9 | search = version = "{current_version}"
10 | replace = version = "{new_version}"
11 |
```
--------------------------------------------------------------------------------
/libs/python/computer/.bumpversion.cfg:
--------------------------------------------------------------------------------
```
1 | [bumpversion]
2 | current_version = 0.4.18
3 | commit = True
4 | tag = True
5 | tag_name = computer-v{new_version}
6 | message = Bump cua-computer to v{new_version}
7 |
8 | [bumpversion:file:pyproject.toml]
9 | search = version = "{current_version}"
10 | replace = version = "{new_version}"
11 |
```
--------------------------------------------------------------------------------
/libs/python/mcp-server/.bumpversion.cfg:
--------------------------------------------------------------------------------
```
1 | [bumpversion]
2 | current_version = 0.1.15
3 | commit = True
4 | tag = True
5 | tag_name = mcp-server-v{new_version}
6 | message = Bump cua-mcp-server to v{new_version}
7 |
8 | [bumpversion:file:pyproject.toml]
9 | search = version = "{current_version}"
10 | replace = version = "{new_version}"
11 |
```
--------------------------------------------------------------------------------
/libs/python/computer-server/.bumpversion.cfg:
--------------------------------------------------------------------------------
```
1 | [bumpversion]
2 | current_version = 0.1.31
3 | commit = True
4 | tag = True
5 | tag_name = computer-server-v{new_version}
6 | message = Bump cua-computer-server to v{new_version}
7 |
8 | [bumpversion:file:pyproject.toml]
9 | search = version = "{current_version}"
10 | replace = version = "{new_version}"
11 |
```
--------------------------------------------------------------------------------
/docs/.gitignore:
--------------------------------------------------------------------------------
```
1 | # deps
2 | /node_modules
3 |
4 | # generated content
5 | .contentlayer
6 | .content-collections
7 | .source
8 |
9 | # test & build
10 | /coverage
11 | /.next/
12 | /out/
13 | /build
14 | *.tsbuildinfo
15 |
16 | # misc
17 | .DS_Store
18 | *.pem
19 | /.pnp
20 | .pnp.js
21 | npm-debug.log*
22 | yarn-debug.log*
23 | yarn-error.log*
24 |
25 | # others
26 | .env*.local
27 | .vercel
28 | next-env.d.ts
```
--------------------------------------------------------------------------------
/libs/lumier/.dockerignore:
--------------------------------------------------------------------------------
```
1 | # Ignore macOS system files and trash
2 | .DS_Store
3 | .Trashes
4 | **/.Trashes
5 | **/.*
6 |
7 | # Ignore Python cache
8 | __pycache__/
9 | *.pyc
10 | *.pyo
11 |
12 | # Ignore virtual environments
13 | .venv/
14 | venv/
15 |
16 | # Ignore editor/project files
17 | .vscode/
18 | .idea/
19 | *.swp
20 |
21 | # Ignore test artifacts
22 | test-results/
23 |
24 | # Ignore anything else you don't want in the Docker build context
25 | ./examples
```
--------------------------------------------------------------------------------
/.dockerignore:
--------------------------------------------------------------------------------
```
1 | # Version control
2 | .git
3 | .github
4 | .gitignore
5 |
6 | # Environment and cache
7 | .venv
8 | .env
9 | .env.local
10 | __pycache__
11 | *.pyc
12 | *.pyo
13 | *.pyd
14 | .Python
15 | .pytest_cache
16 | .pdm-build
17 |
18 | # Distribution / packaging
19 | dist
20 | build
21 | *.egg-info
22 |
23 | # Development
24 | .vscode
25 | .idea
26 | *.swp
27 | *.swo
28 |
29 | # Docs
30 | docs/site
31 |
32 | # Notebooks
33 | notebooks/.ipynb_checkpoints
34 |
35 | # Docker
36 | Dockerfile
37 | .dockerignore
```
--------------------------------------------------------------------------------
/.prettierignore:
--------------------------------------------------------------------------------
```
1 | # Node / JS
2 | node_modules/
3 | dist/
4 | build/
5 | out/
6 | .next/
7 | *.min.js
8 |
9 | # Python
10 | __pycache__/
11 | *.pyc
12 | *.pyo
13 | *.pyd
14 | .venv/
15 | venv/
16 | .env
17 | .env.local
18 |
19 | # Logs
20 | *.log
21 | *.tmp
22 |
23 | # VSCode / editor files
24 | .vscode/
25 | .idea/
26 |
27 | # Other generated files
28 | *.lock
29 | *.db
30 | *.sqlite
31 | pnpm-lock.yaml
32 | uv.lock
33 |
34 | # Docs with complex JSX formatting
35 | docs/content/docs/get-started/quickstart.mdx
```
--------------------------------------------------------------------------------
/libs/typescript/cua-cli/.gitignore:
--------------------------------------------------------------------------------
```
1 | # dependencies (bun install)
2 | node_modules
3 |
4 | # output
5 | out
6 | dist
7 | *.tgz
8 |
9 | # code coverage
10 | coverage
11 | *.lcov
12 |
13 | # logs
14 | logs
15 | _.log
16 | report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
17 |
18 | # dotenv environment variable files
19 | .env
20 | .env.development.local
21 | .env.test.local
22 | .env.production.local
23 | .env.local
24 |
25 | # caches
26 | .eslintcache
27 | .cache
28 | *.tsbuildinfo
29 |
30 | # IntelliJ based IDEs
31 | .idea
32 |
33 | # Finder (MacOS) folder config
34 | .DS_Store
35 |
```
--------------------------------------------------------------------------------
/.pre-commit-config.yaml:
--------------------------------------------------------------------------------
```yaml
1 | repos:
2 | - repo: https://github.com/pre-commit/mirrors-prettier
3 | rev: v3.0.0
4 | hooks:
5 | - id: prettier
6 | name: Prettier (TS/JS/JSON/Markdown/YAML)
7 | entry: prettier --write
8 | language: node
9 | additional_dependencies: ["[email protected]"]
10 | files: \.(ts|tsx|js|jsx|json|md|mdx|yaml|yml)$
11 |
12 | - repo: local
13 | hooks:
14 | - id: tsc
15 | name: TypeScript type check
16 | entry: node ./scripts/typescript-typecheck.js
17 | language: node
18 | files: \.(ts|tsx)$
19 | pass_filenames: false
20 |
21 | - repo: https://github.com/PyCQA/isort
22 | rev: 7.0.0
23 | hooks:
24 | - id: isort
25 | name: isort code formatter
26 | args: ["--profile", "black"]
27 | files: \.(py)$
28 |
29 | - repo: https://github.com/psf/black
30 | rev: 25.9.0
31 | hooks:
32 | - id: black
33 | name: Black code formatter
34 | files: \.(py)$
35 |
36 | - repo: https://github.com/charliermarsh/ruff-pre-commit
37 | rev: v0.14.1
38 | hooks:
39 | - id: ruff
40 | name: ruff linter
41 | args: ["--fix"]
42 | files: \.(py)$
43 |
44 | # Temporarily disabled due to untyped codebase
45 | # - repo: https://github.com/pre-commit/mirrors-mypy
46 | # rev: v1.5.1
47 | # hooks:
48 | # - id: mypy
49 | # name: mypy type checker
50 | # files: \.(py)$
51 |
```
--------------------------------------------------------------------------------
/libs/lume/.cursorignore:
--------------------------------------------------------------------------------
```
1 | # Byte-compiled / optimized / DLL files
2 | __pycache__/
3 | *.py[cod]
4 | *$py.class
5 |
6 | # C extensions
7 | *.so
8 |
9 | # Distribution / packaging
10 | .Python
11 | build/
12 | !libs/lume/scripts/build/
13 | develop-eggs/
14 | dist/
15 | downloads/
16 | eggs/
17 | .eggs/
18 | lib/
19 | lib64/
20 | parts/
21 | sdist/
22 | var/
23 | wheels/
24 | share/python-wheels/
25 | *.egg-info/
26 | .installed.cfg
27 | *.egg
28 | MANIFEST
29 |
30 | # PyInstaller
31 | # Usually these files are written by a python script from a template
32 | # before PyInstaller builds the exe, so as to inject date/other infos into it.
33 | *.manifest
34 | *.spec
35 |
36 | # Installer logs
37 | pip-log.txt
38 | pip-delete-this-directory.txt
39 |
40 | # Unit test / coverage reports
41 | htmlcov/
42 | .tox/
43 | .nox/
44 | .coverage
45 | .coverage.*
46 | .cache
47 | nosetests.xml
48 | coverage.xml
49 | *.cover
50 | *.py,cover
51 | .hypothesis/
52 | .pytest_cache/
53 | cover/
54 |
55 | # Translations
56 | *.mo
57 | *.pot
58 |
59 | # Django stuff:
60 | *.log
61 | local_settings.py
62 | db.sqlite3
63 | db.sqlite3-journal
64 |
65 | # Flask stuff:
66 | instance/
67 | .webassets-cache
68 |
69 | # Scrapy stuff:
70 | .scrapy
71 |
72 | # Sphinx documentation
73 | docs/_build/
74 |
75 | # PyBuilder
76 | .pybuilder/
77 | target/
78 |
79 | # Jupyter Notebook
80 | .ipynb_checkpoints
81 |
82 | # IPython
83 | profile_default/
84 | ipython_config.py
85 |
86 | .pdm.toml
87 | .pdm-python
88 | .pdm-build/
89 |
90 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
91 | __pypackages__/
92 |
93 | # Celery stuff
94 | celerybeat-schedule
95 | celerybeat.pid
96 |
97 | # SageMath parsed files
98 | *.sage.py
99 |
100 | # Environments
101 | .env
102 | .venv
103 | env/
104 | venv/
105 | ENV/
106 | env.bak/
107 | venv.bak/
108 |
109 | # Spyder project settings
110 | .spyderproject
111 | .spyproject
112 |
113 | # Rope project settings
114 | .ropeproject
115 |
116 | # mkdocs documentation
117 | /site
118 |
119 | # mypy
120 | .mypy_cache/
121 | .dmypy.json
122 | dmypy.json
123 |
124 | # Scripts
125 | server/scripts/
126 |
127 | # Pyre type checker
128 | .pyre/
129 |
130 | # pytype static type analyzer
131 | .pytype/
132 |
133 | # Cython debug symbols
134 | cython_debug/
135 |
136 | # Ruff stuff:
137 | .ruff_cache/
138 |
139 | # PyPI configuration file
140 | .pypirc
141 |
142 | # Conda
143 | .conda/
144 |
145 | # Local environment
146 | .env.local
147 |
148 | # macOS DS_Store
149 | .DS_Store
150 |
151 | weights/
152 | weights/icon_detect/
153 | weights/icon_detect/model.pt
154 | weights/icon_detect/model.pt.zip
155 | weights/icon_detect/model.pt.zip.part*
156 |
157 | libs/omniparser/weights/icon_detect/model.pt
158 |
159 | # Example test data and output
160 | examples/test_data/
161 | examples/output/
162 |
163 | /screenshots/
164 |
165 | /experiments/
166 |
167 | /logs/
168 |
169 | # Xcode
170 | #
171 | # gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
172 |
173 | ## User settings
174 | xcuserdata/
175 |
176 | ## Obj-C/Swift specific
177 | *.hmap
178 |
179 | ## App packaging
180 | *.ipa
181 | *.dSYM.zip
182 | *.dSYM
183 |
184 | ## Playgrounds
185 | timeline.xctimeline
186 | playground.xcworkspace
187 |
188 | # Swift Package Manager
189 | #
190 | # Add this line if you want to avoid checking in source code from Swift Package Manager dependencies.
191 | # Packages/
192 | # Package.pins
193 | # Package.resolved
194 | # *.xcodeproj
195 | #
196 | # Xcode automatically generates this directory with a .xcworkspacedata file and xcuserdata
197 | # hence it is not needed unless you have added a package configuration file to your project
198 | .swiftpm/
199 | .build/
200 |
201 | # CocoaPods
202 | #
203 | # We recommend against adding the Pods directory to your .gitignore. However
204 | # you should judge for yourself, the pros and cons are mentioned at:
205 | # https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
206 | #
207 | # Pods/
208 | #
209 | # Add this line if you want to avoid checking in source code from the Xcode workspace
210 | # *.xcworkspace
211 |
212 | # Carthage
213 | #
214 | # Add this line if you want to avoid checking in source code from Carthage dependencies.
215 | # Carthage/Checkouts
216 | Carthage/Build/
217 |
218 | # fastlane
219 | #
220 | # It is recommended to not store the screenshots in the git repo.
221 | # Instead, use fastlane to re-generate the screenshots whenever they are needed.
222 | # For more information about the recommended setup visit:
223 | # https://docs.fastlane.tools/best-practices/source-control/#source-control
224 | fastlane/report.xml
225 | fastlane/Preview.html
226 | fastlane/screenshots/**/*.png
227 | fastlane/test_output
228 |
229 | # Ignore folder
230 | ignore
231 |
232 | # .release
233 | .release/
```
--------------------------------------------------------------------------------
/.cursorignore:
--------------------------------------------------------------------------------
```
1 | # Byte-compiled / optimized / DLL files
2 | __pycache__/
3 | *.py[cod]
4 | *$py.class
5 |
6 | # C extensions
7 | *.so
8 |
9 | # Distribution / packaging
10 | .Python
11 | build/
12 | !libs/lume/scripts/build/
13 | develop-eggs/
14 | dist/
15 | downloads/
16 | eggs/
17 | .eggs/
18 | lib/
19 | lib64/
20 | parts/
21 | sdist/
22 | var/
23 | wheels/
24 | share/python-wheels/
25 | *.egg-info/
26 | .installed.cfg
27 | *.egg
28 | MANIFEST
29 |
30 | # PyInstaller
31 | # Usually these files are written by a python script from a template
32 | # before PyInstaller builds the exe, so as to inject date/other infos into it.
33 | *.manifest
34 | *.spec
35 |
36 | # Installer logs
37 | pip-log.txt
38 | pip-delete-this-directory.txt
39 |
40 | # Unit test / coverage reports
41 | htmlcov/
42 | .tox/
43 | .nox/
44 | .coverage
45 | .coverage.*
46 | .cache
47 | nosetests.xml
48 | coverage.xml
49 | *.cover
50 | *.py,cover
51 | .hypothesis/
52 | .pytest_cache/
53 | cover/
54 |
55 | # Translations
56 | *.mo
57 | *.pot
58 |
59 | # Django stuff:
60 | *.log
61 | local_settings.py
62 | db.sqlite3
63 | db.sqlite3-journal
64 |
65 | # Flask stuff:
66 | instance/
67 | .webassets-cache
68 |
69 | # Scrapy stuff:
70 | .scrapy
71 |
72 | # Sphinx documentation
73 | docs/_build/
74 |
75 | # PyBuilder
76 | .pybuilder/
77 | target/
78 |
79 | # Jupyter Notebook
80 | .ipynb_checkpoints
81 |
82 | # IPython
83 | profile_default/
84 | ipython_config.py
85 |
86 | .pdm.toml
87 | .pdm-python
88 | .pdm-build/
89 |
90 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
91 | __pypackages__/
92 |
93 | # Celery stuff
94 | celerybeat-schedule
95 | celerybeat.pid
96 |
97 | # SageMath parsed files
98 | *.sage.py
99 |
100 | # Environments
101 | .env
102 | .venv
103 | env/
104 | venv/
105 | ENV/
106 | env.bak/
107 | venv.bak/
108 |
109 | # Spyder project settings
110 | .spyderproject
111 | .spyproject
112 |
113 | # Rope project settings
114 | .ropeproject
115 |
116 | # mkdocs documentation
117 | /site
118 |
119 | # mypy
120 | .mypy_cache/
121 | .dmypy.json
122 | dmypy.json
123 |
124 | # Scripts
125 | server/scripts/
126 |
127 | # Pyre type checker
128 | .pyre/
129 |
130 | # pytype static type analyzer
131 | .pytype/
132 |
133 | # Cython debug symbols
134 | cython_debug/
135 |
136 | # Ruff stuff:
137 | .ruff_cache/
138 |
139 | # PyPI configuration file
140 | .pypirc
141 |
142 | # Conda
143 | .conda/
144 |
145 | # Local environment
146 | .env.local
147 |
148 | # macOS DS_Store
149 | .DS_Store
150 |
151 | weights/
152 | weights/icon_detect/
153 | weights/icon_detect/model.pt
154 | weights/icon_detect/model.pt.zip
155 | weights/icon_detect/model.pt.zip.part*
156 |
157 | libs/python/omniparser/weights/icon_detect/model.pt
158 |
159 | # Example test data and output
160 | examples/test_data/
161 | examples/output/
162 |
163 | /screenshots/
164 |
165 | /experiments/
166 |
167 | /logs/
168 |
169 | # Xcode
170 | #
171 | # gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
172 |
173 | ## User settings
174 | xcuserdata/
175 |
176 | ## Obj-C/Swift specific
177 | *.hmap
178 |
179 | ## App packaging
180 | *.ipa
181 | *.dSYM.zip
182 | *.dSYM
183 |
184 | ## Playgrounds
185 | timeline.xctimeline
186 | playground.xcworkspace
187 |
188 | # Swift Package Manager
189 | #
190 | # Add this line if you want to avoid checking in source code from Swift Package Manager dependencies.
191 | # Packages/
192 | # Package.pins
193 | # Package.resolved
194 | # *.xcodeproj
195 | #
196 | # Xcode automatically generates this directory with a .xcworkspacedata file and xcuserdata
197 | # hence it is not needed unless you have added a package configuration file to your project
198 | .swiftpm/
199 | .build/
200 |
201 | # CocoaPods
202 | #
203 | # We recommend against adding the Pods directory to your .gitignore. However
204 | # you should judge for yourself, the pros and cons are mentioned at:
205 | # https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
206 | #
207 | # Pods/
208 | #
209 | # Add this line if you want to avoid checking in source code from the Xcode workspace
210 | # *.xcworkspace
211 |
212 | # Carthage
213 | #
214 | # Add this line if you want to avoid checking in source code from Carthage dependencies.
215 | # Carthage/Checkouts
216 | Carthage/Build/
217 |
218 | # fastlane
219 | #
220 | # It is recommended to not store the screenshots in the git repo.
221 | # Instead, use fastlane to re-generate the screenshots whenever they are needed.
222 | # For more information about the recommended setup visit:
223 | # https://docs.fastlane.tools/best-practices/source-control/#source-control
224 | fastlane/report.xml
225 | fastlane/Preview.html
226 | fastlane/screenshots/**/*.png
227 | fastlane/test_output
228 |
229 | # Ignore folder
230 | ignore
231 |
232 | # .release
233 | .release/
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | **/image/setup.iso
2 | # Byte-compiled / optimized / DLL files
3 | __pycache__/
4 | *.py[cod]
5 | *$py.class
6 | # C extensions
7 | *.so
8 | node_modules/*
9 | */node_modules
10 | **/node_modules
11 | # Distribution / packaging
12 | .Python
13 | build/
14 | !libs/lume/scripts/build/
15 | develop-eggs/
16 | dist/
17 | downloads/
18 | eggs/
19 | .eggs/
20 | lib/*
21 | !libs/lumier/src/lib/
22 | lib64/
23 | parts/
24 | sdist/
25 | var/
26 | wheels/
27 | share/python-wheels/
28 | *.egg-info/
29 | .installed.cfg
30 | *.egg
31 | MANIFEST
32 | # PyInstaller
33 | # Usually these files are written by a python script from a template
34 | # before PyInstaller builds the exe, so as to inject date/other infos into it.
35 | *.manifest
36 | *.spec
37 | # Installer logs
38 | pip-log.txt
39 | pip-delete-this-directory.txt
40 | # Unit test / coverage reports
41 | htmlcov/
42 | .tox/
43 | .nox/
44 | .coverage
45 | .coverage.*
46 | .cache
47 | nosetests.xml
48 | coverage.xml
49 | *.cover
50 | *.py,cover
51 | .hypothesis/
52 | .pytest_cache/
53 | cover/
54 | # Translations
55 | *.mo
56 | *.pot
57 | # Django stuff:
58 | *.log
59 | local_settings.py
60 | db.sqlite3
61 | db.sqlite3-journal
62 | # Flask stuff:
63 | instance/
64 | .webassets-cache
65 | # Scrapy stuff:
66 | .scrapy
67 | # Sphinx documentation
68 | docs/_build/
69 | # PyBuilder
70 | .pybuilder/
71 | target/
72 | # Jupyter Notebook
73 | .ipynb_checkpoints
74 | # IPython
75 | profile_default/
76 | ipython_config.py
77 | .pdm.toml
78 | .pdm-python
79 | .pdm-build/
80 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
81 | __pypackages__/
82 | # Celery stuff
83 | celerybeat-schedule
84 | celerybeat.pid
85 | # SageMath parsed files
86 | *.sage.py
87 | # Environments
88 | .env
89 | .venv
90 | env/
91 | venv/
92 | ENV/
93 | env.bak/
94 | venv.bak/
95 | # Git worktrees
96 | .worktrees/
97 | # Spyder project settings
98 | .spyderproject
99 | .spyproject
100 | # Rope project settings
101 | .ropeproject
102 | # mkdocs documentation
103 | /site
104 | # mypy
105 | .mypy_cache/
106 | .dmypy.json
107 | dmypy.json
108 | # Scripts
109 | server/scripts/
110 | # Pyre type checker
111 | .pyre/
112 | # pytype static type analyzer
113 | .pytype/
114 | # Cython debug symbols
115 | cython_debug/
116 | # Ruff stuff:
117 | .ruff_cache/
118 | # PyPI configuration file
119 | .pypirc
120 | # Conda
121 | .conda/
122 | # Local environment
123 | .env.local
124 | # macOS DS_Store
125 | .DS_Store
126 | weights/
127 | weights/icon_detect/
128 | weights/icon_detect/model.pt
129 | weights/icon_detect/model.pt.zip
130 | weights/icon_detect/model.pt.zip.part*
131 | libs/python/omniparser/weights/icon_detect/model.pt
132 | # Example test data and output
133 | examples/test_data/
134 | examples/output/
135 | /screenshots/
136 | /experiments/
137 | /logs/
138 | # Xcode
139 | #
140 | # gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
141 | ## User settings
142 | xcuserdata/
143 | ## Obj-C/Swift specific
144 | *.hmap
145 | ## App packaging
146 | *.ipa
147 | *.dSYM.zip
148 | *.dSYM
149 | ## Playgrounds
150 | timeline.xctimeline
151 | playground.xcworkspace
152 | # Swift Package Manager
153 | #
154 | # Add this line if you want to avoid checking in source code from Swift Package Manager dependencies.
155 | # Packages/
156 | # Package.pins
157 | # Package.resolved
158 | # *.xcodeproj
159 | #
160 | # Xcode automatically generates this directory with a .xcworkspacedata file and xcuserdata
161 | # hence it is not needed unless you have added a package configuration file to your project
162 | .swiftpm/
163 | .build/
164 | # CocoaPods
165 | #
166 | # We recommend against adding the Pods directory to your .gitignore. However
167 | # you should judge for yourself, the pros and cons are mentioned at:
168 | # https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
169 | #
170 | # Pods/
171 | #
172 | # Add this line if you want to avoid checking in source code from the Xcode workspace
173 | # *.xcworkspace
174 | # Carthage
175 | #
176 | # Add this line if you want to avoid checking in source code from Carthage dependencies.
177 | # Carthage/Checkouts
178 | Carthage/Build/
179 | # fastlane
180 | #
181 | # It is recommended to not store the screenshots in the git repo.
182 | # Instead, use fastlane to re-generate the screenshots whenever they are needed.
183 | # For more information about the recommended setup visit:
184 | # https://docs.fastlane.tools/best-practices/source-control/#source-control
185 | fastlane/report.xml
186 | fastlane/Preview.html
187 | fastlane/screenshots/**/*.png
188 | fastlane/test_output
189 | # Ignore folder
190 | ignore
191 | # .release
192 | .release/
193 | # Shared folder
194 | shared
195 | # Trajectories
196 | trajectories/
197 | # Installation ID Storage
198 | .storage/
199 | # Gradio settings
200 | .gradio_settings.json
201 | # Lumier Storage
202 | storage/
203 | # Trashes
204 | .Trashes
205 | .Trash-1000/
206 | post-provision
207 | # Local secrets for act
208 | .secrets
```
--------------------------------------------------------------------------------
/libs/qemu-docker/linux/src/vm/image/README.md:
--------------------------------------------------------------------------------
```markdown
1 | > Add your Ubuntu 22.04 live server setup.iso to this folder
2 |
3 | **Download Ubuntu 22.04 LTS Server ISO:**
4 |
5 | 1. Visit & download the [server ISO](https://releases.ubuntu.com/22.04/ubuntu-22.04.5-live-server-amd64.iso)
6 | 2. After downloading, rename the file to `setup.iso`
7 | 3. Copy it to the current directory.
8 |
```
--------------------------------------------------------------------------------
/libs/qemu-docker/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # QEMU Docker Containers
2 |
3 | Docker containers running desktop operating systems via QEMU/KVM for Computer-Using Agents (CUA).
4 |
5 | ## Structure
6 |
7 | ```
8 | qemu-docker/
9 | └── windows/ # Windows 11 container with CUA computer-server
10 | ```
11 |
12 | ## Windows Container
13 |
14 | See [windows/README.md](windows/README.md) for complete documentation on the Windows 11 QEMU container.
15 |
```
--------------------------------------------------------------------------------
/libs/qemu-docker/windows/src/vm/image/README.md:
--------------------------------------------------------------------------------
```markdown
1 | > Add your Win11E setup.iso to this folder
2 |
3 | **Download Windows 11 Evaluation ISO:**
4 |
5 | 1. Visit [Microsoft Evaluation Center](https://info.microsoft.com/ww-landing-windows-11-enterprise.html)
6 | 2. Accept the Terms of Service
7 | 3. Download **Windows 11 Enterprise Evaluation (90-day trial, English, United States)** ISO file [~6GB]
8 | 4. After downloading, rename the file to `setup.iso`
9 | 5. Copy it to the current directory.
10 |
```
--------------------------------------------------------------------------------
/libs/python/bench-ui/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # CUA Bench UI
2 |
3 | Lightweight webUI window controller for CUA bench environments using pywebview
4 |
5 | ## Usage
6 |
7 | ```python
8 | from bench_ui import launch_window, get_element_rect, execute_javascript
9 |
10 | # Launch a window with inline HTML content
11 | pid = launch_window(html="<html><body><h1>Hello</h1></body></html>")
12 |
13 | # Get element rect in screen space
14 | rect = get_element_rect(pid, "h1", space="screen")
15 | print(rect)
16 |
17 | # Execute arbitrary JavaScript
18 | text = execute_javascript(pid, "document.querySelector('h1')?.textContent")
19 | print(text)
20 | ```
21 |
22 | ## Installation
23 |
24 | ```bash
25 | pip install cua-bench-ui
26 | ```
27 |
```
--------------------------------------------------------------------------------
/examples/computer-example-ts/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # cua-cloud-openai Example
2 |
3 | This example demonstrates how to control a Cua Cloud Sandbox using the OpenAI `computer-use-preview` model and the `@trycua/computer` TypeScript library.
4 |
5 | ## Overview
6 |
7 | - Connects to a Cua Cloud Sandbox via the `@trycua/computer` library
8 | - Sends screenshots and instructions to OpenAI's computer-use model
9 | - Executes AI-generated actions (clicks, typing, etc.) inside the sandbox
10 | - Designed for Linux sandboxes, but can be adapted for other OS types
11 |
12 | ## Getting Started
13 |
14 | 1. **Install dependencies:**
15 |
16 | ```bash
17 | npm install
18 | ```
19 |
20 | 2. **Set up environment variables:**
21 | Create a `.env` file with the following variables:
22 | - `OPENAI_API_KEY` — your OpenAI API key
23 | - `CUA_API_KEY` — your Cua Cloud API key
24 | - `CUA_CONTAINER_NAME` — the name of your provisioned sandbox
25 |
26 | 3. **Run the example:**
27 |
28 | ```bash
29 | npx tsx src/index.ts
30 | ```
31 |
32 | ## Files
33 |
34 | - `src/index.ts` — Main example script
35 | - `src/helpers.ts` — Helper for executing actions on the container
36 |
37 | ---
38 |
39 | If you have questions or issues, please open an issue or contact the maintainers.
40 |
```
--------------------------------------------------------------------------------
/notebooks/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # CUA Notebooks
2 |
3 | This folder contains Jupyter notebooks that demonstrate the core functionality of the CUA (Computer Use Automation) system. These notebooks serve as interactive examples and quickstart guides for different components of the CUA platform.
4 |
5 | ## Available Notebooks
6 |
7 | ### Core Components
8 |
9 | - **`computer_nb.ipynb`** - Demonstrates the Computer API for programmatically operating sandbox VMs using either Cua Cloud Sandbox or local Lume VMs on Apple Silicon macOS systems
10 | - **`agent_nb.ipynb`** - Shows how to use CUA's Agent to run automated workflows in virtual sandboxes with various AI models (OpenAI, Anthropic, local models)
11 | - **`computer_server_nb.ipynb`** - Demonstrates how to host and configure the Computer server that powers the Computer API
12 |
13 | ### Evaluation & Benchmarking
14 |
15 | - **`eval_osworld.ipynb`** - Shows ComputerAgent integration with HUD for OSWorld benchmarking, supporting both Claude and OpenAI models
16 |
17 | ### Tutorials
18 |
19 | - **`blog/`** - Tutorial notebooks from blog posts:
20 | - `build-your-own-operator-on-macos-1.ipynb` - Part 1: Building a CUA operator using OpenAI's computer-use-preview model
21 | - `build-your-own-operator-on-macos-2.ipynb` - Part 2: Using the cua-agent package for more advanced automation
22 |
```
--------------------------------------------------------------------------------
/libs/python/core/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 | <h1>
3 | <div class="image-wrapper" style="display: inline-block;">
4 | <picture>
5 | <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
6 | <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
7 | <img alt="Shows my svg">
8 | </picture>
9 | </div>
10 |
11 | [](#)
12 | [](#)
13 | [](https://discord.com/invite/mVnXXpdE85)
14 | [](https://pypi.org/project/cua-core/)
15 |
16 | </h1>
17 | </div>
18 |
19 | **Cua Core** provides essential shared functionality and utilities used across the Cua ecosystem:
20 |
21 | - Privacy-focused telemetry system for transparent usage analytics
22 | - Common helper functions and utilities used by other Cua packages
23 | - Core infrastructure components shared between modules
24 |
25 | ## Installation
26 |
27 | ```bash
28 | pip install cua-core
29 | ```
30 |
```
--------------------------------------------------------------------------------
/tests/agent_loop_testing/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # CUA Agent Test
2 |
3 | Simple test for CUA ComputerAgent SDK with mock computer.
4 |
5 | ## Run Test
6 |
7 | ```bash
8 | python tests/agent_loop_testing/agent_test.py --model anthropic/claude-sonnet-4-20250514
9 | ```
10 |
11 | ## What It Does
12 |
13 | - Tests real CUA ComputerAgent SDK
14 | - Uses mock computer (only screenshots, no real actions)
15 | - Agent tries to "Open Safari browser"
16 | - Runs up to 5 iterations
17 | - Shows agent responses and tool calls
18 |
19 | ## What Passes ✅
20 |
21 | - Agent initializes
22 | - Takes screenshots
23 | - Analyzes images
24 | - Makes tool calls
25 | - Runs multiple iterations
26 |
27 | ## What Fails ❌
28 |
29 | - Missing dependencies
30 | - Invalid API keys
31 | - Agent crashes
32 | - Import errors
33 |
34 | ## Install
35 |
36 | ```bash
37 | pip install -e libs/python/agent -e libs/python/computer
38 | export ANTHROPIC_API_KEY="your-key"
39 | ```
40 |
41 | ## Example Output
42 |
43 | ```
44 | 🤖 Testing CUA Agent: anthropic/claude-sonnet-4-20250514
45 | ==================================================
46 | ✅ CUA Agent created
47 | ✅ Mock computer ready
48 | 🚀 Running agent...
49 |
50 | Iteration 1:
51 | Agent: I'll click on Safari to open it.
52 | Tool: click {'x': 125, 'y': 975}
53 |
54 | Iteration 2:
55 | Agent: Safari didn't open, let me try again.
56 | Tool: click {'x': 125, 'y': 975}
57 |
58 | Iteration 3:
59 | Agent: This appears to be a static test environment.
60 |
61 | 🏁 Stopping after 5 iterations (safety limit)
62 |
63 | ==================================================
64 | 🎉 TEST COMPLETE!
65 | ==================================================
66 | ✅ Model: anthropic/claude-sonnet-4-20250514
67 | ✅ Iterations: 3
68 | ✅ Screenshots: 3
69 | ✅ Agent executed successfully
70 | ```
71 |
```
--------------------------------------------------------------------------------
/libs/typescript/core/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 | <h1>
3 | <div class="image-wrapper" style="display: inline-block;">
4 | <picture>
5 | <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
6 | <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
7 | <img alt="Shows my svg">
8 | </picture>
9 | </div>
10 |
11 | [](#)
12 | [](#)
13 | [](https://discord.com/invite/mVnXXpdE85)
14 | [](https://www.npmjs.com/package/@trycua/core)
15 |
16 | </h1>
17 | </div>
18 |
19 | **Cua Core** provides essential shared functionality and utilities used across the Cua ecosystem:
20 |
21 | - Privacy-focused telemetry system for transparent usage analytics
22 | - Common helper functions and utilities used by other Cua packages
23 | - Core infrastructure components shared between modules
24 |
25 | ## Installation
26 |
27 | ```bash
28 | pnpm install @trycua/core
29 | ```
30 |
31 | ## Development
32 |
33 | Install dependencies:
34 |
35 | ```bash
36 | pnpm install
37 | ```
38 |
39 | Run the unit tests:
40 |
41 | ```bash
42 | pnpm test
43 | ```
44 |
45 | Build the library:
46 |
47 | ```bash
48 | pnpm build
49 | ```
50 |
51 | ## License
52 |
53 | [MIT](./LICENSE) License 2025 [CUA](https://github.com/trycua)
54 |
```
--------------------------------------------------------------------------------
/docs/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # docs
2 |
3 | This is a Next.js application generated with
4 | [Create Fumadocs](https://github.com/fuma-nama/fumadocs).
5 |
6 | Run development server:
7 |
8 | ```bash
9 | npm run dev
10 | # or
11 | pnpm dev
12 | # or
13 | yarn dev
14 | ```
15 |
16 | Open http://localhost:3000 with your browser to see the result.
17 |
18 | ## Explore
19 |
20 | In the project, you can see:
21 |
22 | - `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
23 | - `app/layout.config.tsx`: Shared options for layouts, optional but preferred to keep.
24 |
25 | | Route | Description |
26 | | ------------------------- | ------------------------------------------------------ |
27 | | `app/(home)` | The route group for your landing page and other pages. |
28 | | `app/docs` | The documentation layout and pages. |
29 | | `app/api/search/route.ts` | The Route Handler for search. |
30 |
31 | ### Fumadocs MDX
32 |
33 | A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
34 |
35 | Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
36 |
37 | ## Setup Telemetry
38 |
39 | We use PostHog for telemetry to improve the clarity and structure of our documentation. Start by copying the `.env.example` and adding in your PostHog API key and host.
40 |
41 | ```bash
42 | cp .env.example .env
43 | ```
44 |
45 | ## Learn More
46 |
47 | To learn more about Next.js and Fumadocs, take a look at the following
48 | resources:
49 |
50 | - [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
51 | features and API.
52 | - [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
53 | - [Fumadocs](https://fumadocs.vercel.app) - learn about Fumadocs
54 |
```
--------------------------------------------------------------------------------
/libs/typescript/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # CUA TypeScript Libraries
2 |
3 | This repository contains TypeScript implementations of the CUA libraries:
4 |
5 | - `@trycua/core`: Core functionality including telemetry and logging
6 | - `@trycua/computer`: Computer interaction SDK for VM management and control
7 |
8 | ## Project Structure
9 |
10 | ```text
11 | libs/typescript/
12 | ├── computer/ # Computer SDK package
13 | ├── core/ # Core functionality package
14 | ├── package.json # Root package configuration
15 | └── pnpm-workspace.yaml # Workspace configuration
16 | ```
17 |
18 | ## Prerequisites
19 |
20 | - [Node.js](https://nodejs.org/) (v18 or later)
21 | - [pnpm](https://pnpm.io/) (v10 or later)
22 |
23 | ## Setup and Installation
24 |
25 | 1. Install dependencies for all packages:
26 |
27 | ```bash
28 | pnpm install
29 | ```
30 |
31 | 1. Build all packages:
32 |
33 | ```bash
34 | pnpm build:all
35 | ```
36 |
37 | ## Development Workflow
38 |
39 | ### Building Packages
40 |
41 | Build all packages in the correct dependency order:
42 |
43 | ```bash
44 | pnpm build:all
45 | ```
46 |
47 | Build specific packages:
48 |
49 | ```bash
50 | # Build core package
51 | pnpm --filter @trycua/core build
52 |
53 | # Build computer package
54 | pnpm --filter @trycua/computer build
55 | ```
56 |
57 | ### Running Tests
58 |
59 | Run tests for all packages:
60 |
61 | ```bash
62 | pnpm test:all
63 | ```
64 |
65 | Run tests for specific packages:
66 |
67 | ```bash
68 | # Test core package
69 | pnpm --filter @trycua/core test
70 |
71 | # Test computer package
72 | pnpm --filter @trycua/computer test
73 | ```
74 |
75 | ### Linting
76 |
77 | Lint all packages:
78 |
79 | ```bash
80 | pnpm lint:all
81 | ```
82 |
83 | Fix linting issues:
84 |
85 | ```bash
86 | pnpm lint:fix:all
87 | ```
88 |
89 | ## Package Details
90 |
91 | ### @trycua/core
92 |
93 | Core functionality for CUA libraries including:
94 |
95 | - Telemetry with PostHog integration
96 | - Common utilities and types
97 |
98 | ### @trycua/computer
99 |
100 | Computer interaction SDK for managing and controlling virtual machines:
101 |
102 | - VM provider system (Cloud)
103 | - Interface system for OS-specific interactions
104 | - Screenshot, keyboard, and mouse control
105 | - Command execution
106 |
107 | ## Publishing
108 |
109 | Prepare packages for publishing:
110 |
111 | ```bash
112 | pnpm -r build
113 | ```
114 |
115 | Publish packages:
116 |
117 | ```bash
118 | pnpm -r publish
119 | ```
120 |
```
--------------------------------------------------------------------------------
/libs/typescript/agent/examples/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # CUA Agent Client Examples
2 |
3 | This directory contains examples demonstrating how to use the `@trycua/agent` client library.
4 |
5 | ## Browser Example
6 |
7 | ### `browser-example.html`
8 |
9 | A simple HTML page that demonstrates using the CUA Agent Client in a browser environment.
10 |
11 | **Features:**
12 |
13 | - Connect to HTTP/HTTPS or P2P (peer://) agent proxies
14 | - Send text messages to any supported model
15 | - View responses in real-time
16 | - Health check functionality
17 | - Clear, simple interface with no external dependencies
18 |
19 | **Usage:**
20 |
21 | 1. **Build the library first:**
22 |
23 | ```bash
24 | cd ../
25 | pnpm build
26 | ```
27 |
28 | 2. **Start a local web server** (required for ES modules):
29 |
30 | ```bash
31 | # Option 1: Using Python
32 | python -m http.server 8080
33 |
34 | # Option 2: Using Node.js (if you have http-server installed)
35 | npx http-server -p 8080
36 |
37 | # Option 3: Using any other local server
38 | ```
39 |
40 | 3. **Open in browser:**
41 | Navigate to `http://localhost:8080/examples/playground-example.html`
42 |
43 | 4. **Configure and test:**
44 | - Enter an agent URL (e.g., `https://localhost:8000` or `peer://some-peer-id`)
45 | - Enter a model name (e.g., `anthropic/claude-sonnet-4-5-20250929`)
46 | - Type a message and click "Send Message" or press Enter
47 | - View the response in the output textarea
48 |
49 | **Supported URLs:**
50 |
51 | - **HTTP/HTTPS**: `https://localhost:8000`, `http://my-agent-server.com:8080`
52 | - **Peer-to-Peer**: `peer://computer-agent-proxy`, `peer://any-peer-id`
53 |
54 | **Example Models:**
55 |
56 | - `anthropic/claude-sonnet-4-5-20250929`
57 | - `openai/gpt-4`
58 | - `huggingface-local/microsoft/UI-TARS-7B`
59 |
60 | **Note:** Make sure you have a CUA agent proxy server running at the specified URL before testing.
61 |
62 | ## Running Agent Proxy Server
63 |
64 | To test the examples, you'll need a CUA agent proxy server running:
65 |
66 | ```bash
67 | # HTTP server (default port 8000)
68 | python -m agent.proxy.cli
69 |
70 | # P2P server
71 | python -m agent.proxy.cli --mode p2p
72 |
73 | # Both HTTP and P2P
74 | python -m agent.proxy.cli --mode both
75 | ```
76 |
```
--------------------------------------------------------------------------------
/libs/python/mcp-server/desktop-extension/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # CUA Desktop Extension
2 |
3 | This directory contains the build artifacts for the CUA Desktop Extension (`.mcpb` file).
4 |
5 | ## Building the Extension
6 |
7 | To build the extension, run the build script from the parent directory:
8 |
9 | ```bash
10 | cd /path/to/libs/python/mcp-server
11 | python3 build-extension.py
12 | ```
13 |
14 | This will:
15 |
16 | 1. Copy the MCP server code from `mcp_server/` directory
17 | 2. Copy static files (manifest, icons, scripts)
18 | 3. Create a `.mcpb` zip archive in `desktop-extension/cua-extension.mcpb`
19 | 4. Set custom file icon (platform-specific):
20 | - macOS: Uses `fileicon` (install with `brew install fileicon`)
21 | - Windows/Linux: Not yet supported
22 |
23 | ## Directory Structure
24 |
25 | ```
26 | desktop-extension/
27 | ├── README.md # This file
28 | ├── manifest.json # Extension manifest
29 | ├── desktop_extension.png # Extension icon
30 | ├── requirements.txt # Python dependencies
31 | ├── run_server.sh # Server launcher script
32 | ├── setup.py # Dependency installer
33 | └── cua-extension.mcpb # Generated extension archive
34 | ```
35 |
36 | ## Source Files
37 |
38 | The actual MCP server code lives in `../mcp_server/`:
39 |
40 | - `server.py` - Main MCP server implementation
41 | - `session_manager.py` - Session management and resource pooling
42 |
43 | ## Static Files
44 |
45 | These files are maintained in this directory:
46 |
47 | - `manifest.json` - Extension metadata and configuration
48 | - `desktop_extension.png` - Extension icon
49 | - `requirements.txt` - Python package dependencies
50 | - `run_server.sh` - Shell script to launch the server
51 | - `setup.py` - Python script to install dependencies
52 |
53 | ## Generated Files
54 |
55 | The `.mcpb` file is generated by the build script and is gitignored.
56 |
57 | ## Installing the Extension
58 |
59 | Once built, you can install the extension in Claude Desktop by:
60 |
61 | 1. Opening Claude Desktop Settings
62 | 2. Going to the Extensions section
63 | 3. Dropping the `cua-extension.mcpb` file into the window
64 | 4. Following the installation prompts
65 |
66 | For more information, see the [Anthropic Desktop Extensions documentation](https://www.anthropic.com/engineering/desktop-extensions).
67 |
```
--------------------------------------------------------------------------------
/libs/python/computer-server/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 | <h1>
3 | <div class="image-wrapper" style="display: inline-block;">
4 | <picture>
5 | <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
6 | <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
7 | <img alt="Shows my svg">
8 | </picture>
9 | </div>
10 |
11 | [](#)
12 | [](#)
13 | [](https://discord.com/invite/mVnXXpdE85)
14 | [](https://pypi.org/project/cua-computer-server/)
15 |
16 | </h1>
17 | </div>
18 |
19 | **Computer Server** is the server component for the Computer-Use Interface (CUI) framework powering Cua for interacting with local macOS and Linux sandboxes, PyAutoGUI-compatible, and pluggable with any AI agent systems (Cua, Langchain, CrewAI, AutoGen).
20 |
21 | ## Features
22 |
23 | - WebSocket API for computer-use
24 | - Cross-platform support (macOS, Linux)
25 | - Integration with CUA computer library for screen control, keyboard/mouse automation, and accessibility
26 |
27 | ## Install
28 |
29 | To install the Computer-Use Interface (CUI):
30 |
31 | ```bash
32 | pip install cua-computer-server
33 | ```
34 |
35 | ## Run
36 |
37 | Refer to this notebook for a step-by-step guide on how to use the Computer-Use Server on the host system or VM:
38 |
39 | - [Computer-Use Server](../../../notebooks/computer_server_nb.ipynb)
40 |
41 | ## Docs
42 |
43 | - [Commands](https://cua.ai/docs/computer-sdk/computer-server/Commands)
44 | - [REST-API](https://cua.ai/docs/computer-sdk/computer-server/REST-API)
45 | - [WebSocket-API](https://cua.ai/docs/computer-sdk/computer-server/WebSocket-API)
46 | - [Index](https://cua.ai/docs/computer-sdk/computer-server)
47 |
```
--------------------------------------------------------------------------------
/libs/python/agent/benchmarks/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Computer Agent Benchmarks
2 |
3 | This directory contains benchmarks designed to test agent providers in the Computer Agent SDK against reference agent implementations.
4 |
5 | ## Overview
6 |
7 | The benchmark system evaluates models on GUI grounding tasks, specifically click prediction accuracy. It supports both:
8 |
9 | - **Computer Agent SDK providers** (using model strings like `"huggingface-local/HelloKKMe/GTA1-7B"`)
10 | - **Reference agent implementations** (custom model classes implementing the `ModelProtocol`)
11 |
12 | ## Available Benchmarks
13 |
14 | ### 1. ScreenSpot-v2 (`ss-v2.py`)
15 |
16 | - **Dataset**: ScreenSpot-v2 (click-only GUI grounding)
17 | - **Format**: Standard resolution screenshots
18 | - **Task**: Predict click coordinates given an instruction and image
19 | - **Metrics**: Accuracy, Error Rate, Timing, VRAM usage
20 |
21 | ### 2. ScreenSpot-Pro (`ss-pro.py`)
22 |
23 | - **Dataset**: ScreenSpot-Pro (high-resolution click-only GUI grounding)
24 | - **Format**: High-resolution screenshots
25 | - **Task**: Predict click coordinates given an instruction and image
26 | - **Metrics**: Accuracy, Error Rate, Timing, VRAM usage
27 |
28 | ### 3. Interactive Testing (`interactive.py`)
29 |
30 | - **Real-time testing**: Take screenshots and visualize model predictions
31 | - **Commands**:
32 | - Type instruction → test all models on last screenshot
33 | - `screenshot` → take screenshot
34 | - `models` → list available models
35 | - `quit`/`exit` → exit tool
36 | - **Output**: Visual predictions with crosshairs for each model
37 |
38 | ## Running Benchmarks
39 |
40 | ### 1. Configure Models
41 |
42 | Edit `utils.py` to specify which models you want to test in `get_available_models()`.
43 |
44 | ### 2. Run Benchmark
45 |
46 | ```bash
47 | # ScreenSpot-v2 benchmark
48 | python ss-v2.py --samples 50
49 |
50 | # ScreenSpot-Pro benchmark
51 | python ss-pro.py --samples 50
52 |
53 | # Interactive testing
54 | python interactive.py
55 | ```
56 |
57 | ## Output
58 |
59 | ### Console Output
60 |
61 | ```
62 | Model Results:
63 | Accuracy: 85.50% (171/200)
64 | Avg Time: 1.23s (0.89s - 2.45s)
65 | VRAM Usage: 4.5GB (max) / 3.4GB (avg)
66 | ```
67 |
68 | ### Generated Files
69 |
70 | - **Markdown Report**: `*_results.md` with detailed results tables
71 | - **Visualizations**: `output/` directory with prediction visualizations
72 | - **Interactive Output**: `interactive_output/` for interactive session results
73 |
74 | ## Contributing
75 |
76 | To add a new reference model, follow the instructions in [contrib.md](contrib.md).
77 |
```
--------------------------------------------------------------------------------
/libs/python/computer/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 | <h1>
3 | <div class="image-wrapper" style="display: inline-block;">
4 | <picture>
5 | <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
6 | <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
7 | <img alt="Shows my svg">
8 | </picture>
9 | </div>
10 |
11 | [](#)
12 | [](#)
13 | [](https://discord.com/invite/mVnXXpdE85)
14 | [](https://pypi.org/project/cua-computer/)
15 |
16 | </h1>
17 | </div>
18 |
19 | **cua-computer** is a Computer-Use Interface (CUI) framework powering Cua for interacting with local macOS and Linux sandboxes, PyAutoGUI-compatible, and pluggable with any AI agent systems (Cua, Langchain, CrewAI, AutoGen). Computer relies on [Lume](https://github.com/trycua/lume) for creating and managing sandbox environments.
20 |
21 | ### Get started with Computer
22 |
23 | <div align="center">
24 | <img src="https://raw.githubusercontent.com/trycua/cua/main/img/computer.png"/>
25 | </div>
26 |
27 | ```python
28 | from computer import Computer
29 |
30 | computer = Computer(os_type="macos", display="1024x768", memory="8GB", cpu="4")
31 | try:
32 | await computer.run()
33 |
34 | screenshot = await computer.interface.screenshot()
35 | with open("screenshot.png", "wb") as f:
36 | f.write(screenshot)
37 |
38 | await computer.interface.move_cursor(100, 100)
39 | await computer.interface.left_click()
40 | await computer.interface.right_click(300, 300)
41 | await computer.interface.double_click(400, 400)
42 |
43 | await computer.interface.type_text("Hello, World!")
44 | await computer.interface.press_key("enter")
45 |
46 | await computer.interface.set_clipboard("Test clipboard")
47 | content = await computer.interface.copy_to_clipboard()
48 | print(f"Clipboard content: {content}")
49 | finally:
50 | await computer.stop()
51 | ```
52 |
53 | ## Install
54 |
55 | To install the Computer-Use Interface (CUI):
56 |
57 | ```bash
58 | pip install "cua-computer[all]"
59 | ```
60 |
61 | The `cua-computer` PyPi package pulls automatically the latest executable version of Lume through [pylume](https://github.com/trycua/pylume).
62 |
63 | ## Run
64 |
65 | Refer to this notebook for a step-by-step guide on how to use the Computer-Use Interface (CUI):
66 |
67 | - [Computer-Use Interface (CUI)](https://github.com/trycua/cua/blob/main/notebooks/computer_nb.ipynb)
68 |
69 | ## Docs
70 |
71 | - [Computers](https://cua.ai/docs/computer-sdk/computers)
72 | - [Commands](https://cua.ai/docs/computer-sdk/commands)
73 | - [Computer UI](https://cua.ai/docs/computer-sdk/computer-ui)
74 | - [Sandboxed Python](https://cua.ai/docs/computer-sdk/sandboxed-python)
75 |
```
--------------------------------------------------------------------------------
/libs/typescript/computer/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 | <h1>
3 | <div class="image-wrapper" style="display: inline-block;">
4 | <picture>
5 | <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
6 | <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
7 | <img alt="Shows my svg">
8 | </picture>
9 | </div>
10 |
11 | [](#)
12 | [](#)
13 | [](https://discord.com/invite/mVnXXpdE85)
14 | [](https://www.npmjs.com/package/@trycua/computer)
15 |
16 | </h1>
17 | </div>
18 |
19 | **@trycua/computer** is a Computer-Use Interface (CUI) framework powering Cua for interacting with local macOS and Linux sandboxes, Playwright-compatible, and pluggable with any AI agent systems (Cua, Langchain, CrewAI, AutoGen). Computer relies on [Lume](https://github.com/trycua/lume) for creating and managing sandbox environments.
20 |
21 | ### Get started with Computer
22 |
23 | <div align="center">
24 | <img src="https://raw.githubusercontent.com/trycua/cua/main/img/computer.png"/>
25 | </div>
26 |
27 | ```typescript
28 | import { Computer, OSType } from '@trycua/computer';
29 |
30 | // Create a new computer instance
31 | const computer = new Computer({
32 | osType: OSType.LINUX,
33 | name: 's-linux-vm_id',
34 | apiKey: 'your-api-key',
35 | });
36 |
37 | // Start the computer
38 | await computer.run();
39 |
40 | // Get the computer interface for interaction
41 | const computerInterface = computer.interface;
42 |
43 | // Take a screenshot
44 | const screenshot = await computerInterface.getScreenshot();
45 | // In a Node.js environment, you might save it like this:
46 | // import * as fs from 'fs';
47 | // fs.writeFileSync('screenshot.png', Buffer.from(screenshot));
48 |
49 | // Click at coordinates
50 | await computerInterface.click(500, 300);
51 |
52 | // Type text
53 | await computerInterface.typeText('Hello, world!');
54 |
55 | // Stop the computer
56 | await computer.stop();
57 | ```
58 |
59 | ## Install
60 |
61 | To install the Computer-Use Interface (CUI):
62 |
63 | ```bash
64 | npm install @trycua/computer
65 | # or
66 | pnpm add @trycua/computer
67 | ```
68 |
69 | The `@trycua/computer` package provides the TypeScript library for interacting with computer interfaces.
70 |
71 | ## Run
72 |
73 | Refer to this example for a step-by-step guide on how to use the Computer-Use Interface (CUI):
74 |
75 | - [Computer-Use Interface (CUI)](https://github.com/trycua/cua/tree/main/examples/computer-example-ts)
76 |
77 | ## Docs
78 |
79 | - [Computers](https://cua.ai/docs/computer-sdk/computers)
80 | - [Commands](https://cua.ai/docs/computer-sdk/commands)
81 | - [Computer UI](https://cua.ai/docs/computer-sdk/computer-ui)
82 |
83 | ## License
84 |
85 | [MIT](./LICENSE) License 2025 [CUA](https://github.com/trycua)
86 |
```
--------------------------------------------------------------------------------
/libs/lume/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 | <h1>
3 | <div class="image-wrapper" style="display: inline-block;">
4 | <picture>
5 | <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="../../img/logo_white.png" style="display: block; margin: auto;">
6 | <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="../../img/logo_black.png" style="display: block; margin: auto;">
7 | <img alt="Shows my svg">
8 | </picture>
9 | </div>
10 |
11 | [](#)
12 | [](#)
13 | [](https://discord.com/invite/mVnXXpdE85)
14 |
15 | </h1>
16 | </div>
17 |
18 | **lume** is a lightweight Command Line Interface and local API server to create, run and manage macOS and Linux virtual machines (VMs) with near-native performance on Apple Silicon, using Apple's `Virtualization.Framework`.
19 |
20 | ### Run prebuilt macOS images in just 1 step
21 |
22 | <div align="center">
23 | <img src="../../img/cli.png" alt="lume cli">
24 | </div>
25 |
26 | ```bash
27 | lume run macos-sequoia-vanilla:latest
28 | ```
29 |
30 | ## Quickstart
31 |
32 | Install and run a prebuilt macOS VM in two commands:
33 |
34 | ```bash
35 | # Install Lume
36 | /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
37 | # Pull & start a macOS image
38 | lume run macos-sequoia-vanilla:latest
39 | ```
40 |
41 | <Callout title="Security Note">
42 | All prebuilt images use the default password `lume`. Change this immediately after your first login using the `passwd` command.
43 | </Callout>
44 |
45 | **System Requirements**:
46 |
47 | - Apple Silicon Mac (M1, M2, M3, etc.)
48 | - macOS 13.0 or later
49 | - At least 8GB of RAM (16GB recommended)
50 | - At least 50GB of free disk space
51 |
52 | ## Development
53 |
54 | To get set up with Lume for development, read [these instructions](Development.md).
55 |
56 | ## Docs
57 |
58 | - [Installation](https://cua.ai/docs/macos-vm-cli-playbook/lume/installation)
59 | - [Prebuilt Images](https://cua.ai/docs/macos-vm-cli-playbook/lume/prebuilt-images)
60 | - [CLI Reference](https://cua.ai/docs/macos-vm-cli-playbook/lume/cli-reference)
61 | - [HTTP API](https://cua.ai/docs/macos-vm-cli-playbook/lume/http-api)
62 | - [FAQ](https://cua.ai/docs/macos-vm-cli-playbook/lume/faq)
63 |
64 | ## Contributing
65 |
66 | We welcome and greatly appreciate contributions to lume! Whether you're improving documentation, adding new features, fixing bugs, or adding new VM images, your efforts help make lume better for everyone. For detailed instructions on how to contribute, please refer to our [Contributing Guidelines](CONTRIBUTING.md).
67 |
68 | Join our [Discord community](https://discord.com/invite/mVnXXpdE85) to discuss ideas or get assistance.
69 |
70 | ## License
71 |
72 | lume is open-sourced under the MIT License - see the [LICENSE](LICENSE) file for details.
73 |
74 | ## Trademarks
75 |
76 | Apple, macOS, and Apple Silicon are trademarks of Apple Inc. Ubuntu and Canonical are registered trademarks of Canonical Ltd. This project is not affiliated with, endorsed by, or sponsored by Apple Inc. or Canonical Ltd.
77 |
```
--------------------------------------------------------------------------------
/libs/typescript/cua-cli/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # CUA CLI (Bun)
2 |
3 | ## Install
4 |
5 | ```bash
6 | bun install
7 | bun link # register package globally
8 | bun link cua-cli # install the global binary `cua`
9 | ```
10 |
11 | If you want to run without linking:
12 |
13 | ```bash
14 | bun run ./index.ts -- --help
15 | ```
16 |
17 | ## Commands
18 |
19 | - **Auth**
20 |
21 | The CLI supports both **flat** and **grouped** command styles:
22 |
23 | ```bash
24 | # Grouped style (explicit)
25 | cua auth login
26 | cua auth env
27 | cua auth logout
28 |
29 | # Flat style (quick)
30 | cua login
31 | cua env
32 | cua logout
33 | ```
34 |
35 | **Available Commands:**
36 | - `login` – opens browser to authorize; stores API key locally
37 | - `--api-key sk-...` – stores provided key directly
38 | - `env` – writes/updates `.env` with `CUA_API_KEY`
39 | - `logout` – clears stored API key
40 |
41 | - **Sandboxes**
42 |
43 | The CLI supports both **flat** and **grouped** command styles:
44 |
45 | ```bash
46 | # Flat style (quick & concise)
47 | cua list
48 | cua create --os linux --size small --region north-america
49 | cua start <name>
50 | cua stop <name>
51 |
52 | # Grouped style (explicit & clear)
53 | cua sb list # or: cua sandbox list
54 | cua sb create # or: cua sandbox create
55 | cua sb start # or: cua sandbox start
56 | cua sb stop # or: cua sandbox stop
57 | ```
58 |
59 | **Available Commands:**
60 | - `list` (aliases: `ls`, `ps`) – list all sandboxes
61 | - `--show-passwords` – include passwords in output
62 | - `create` – create a new sandbox
63 | - `--os`: `linux`, `windows`, `macos`
64 | - `--size`: `small`, `medium`, `large`
65 | - `--region`: `north-america`, `europe`, `asia-pacific`, `south-america`
66 | - `get <name>` – get detailed information about a specific sandbox
67 | - `--json` – output in JSON format
68 | - `--show-passwords` – include password in output
69 | - `--show-vnc-url` – include computed NoVNC URL
70 | - `delete <name>` – delete a sandbox
71 | - `start <name>` – start a stopped sandbox
72 | - `stop <name>` – stop a running sandbox
73 | - `restart <name>` – restart a sandbox
74 | - `suspend <name>` – suspend a sandbox (preserves memory state)
75 | - `vnc <name>` (alias: `open`) – open VNC desktop in your browser
76 |
77 | ## Auth Flow (Dynamic Callback Port)
78 |
79 | - CLI starts a small local HTTP server using `Bun.serve({ port: 0 })` which picks an available port.
80 | - Browser is opened to `https://cua.ai/cli-auth?callback_url=http://127.0.0.1:<port>/callback`.
81 | - After you click "Authorize CLI", the browser redirects to the local server with `?token=...`.
82 | - The CLI saves the API key in `~/.config/cua/cli.sqlite`.
83 |
84 | > Note: If the browser cannot be opened automatically, copy/paste the printed URL.
85 |
86 | ## Project Structure
87 |
88 | - `index.ts` – entry point (shebang + start CLI)
89 | - `src/cli.ts` – yargs bootstrapping
90 | - `src/commands/auth.ts` – auth/login/pull/logout commands
91 | - `src/commands/sandbox.ts` – sandbox list/start/stop/restart commands
92 | - `src/auth.ts` – browser flow + local callback server (dynamic port)
93 | - `src/http.ts` – HTTP helper
94 | - `src/storage.ts` – SQLite-backed key-value storage
95 | - `src/config.ts` – constants and paths
96 | - `src/util.ts` – table printing, .env writer
97 |
98 | ## Notes
99 |
100 | - Stored API key lives at `~/.config/cua/cli.sqlite` under `kv(api_key)`.
101 | - Public API base defaults to `https://api.cua.ai`.
102 | - Website base defaults to `https://cua.ai`.
103 | - Authorization header: `Authorization: Bearer <api_key>`.
104 |
```
--------------------------------------------------------------------------------
/libs/kasm/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # CUA Ubuntu Container
2 |
3 | Containerized virtual desktop for Computer-Using Agents (CUA). Utilizes Kasm's MIT-licensed Ubuntu XFCE container as a base with computer-server pre-installed.
4 |
5 | ## Features
6 |
7 | - Ubuntu 22.04 (Jammy) with XFCE desktop environment
8 | - Pre-installed computer-server for remote computer control
9 | - VNC access for visual desktop interaction
10 | - Python 3.11 with necessary libraries
11 | - Screen capture tools (gnome-screenshot, wmctrl, ffmpeg)
12 | - Clipboard utilities (xclip, socat)
13 |
14 | ## Usage
15 |
16 | ### Build and Push (multi-arch)
17 |
18 | Use Docker Buildx to build and push a multi-architecture image for both `linux/amd64` and `linux/arm64` in a single command. Replace `trycua` with your Docker Hub username or your registry namespace as needed.
19 |
20 | ```bash
21 | # Login to your registry first (Docker Hub shown here)
22 | docker login
23 |
24 | # Build and push for amd64 and arm64 in one step
25 | docker buildx build \
26 | --platform linux/amd64,linux/arm64 \
27 | -t trycua/cua-ubuntu:latest \
28 | --push \
29 | .
30 | ```
31 |
32 | ### Running the Container Manually
33 |
34 | ```bash
35 | docker run --rm -it --shm-size=512m -p 6901:6901 -p 8000:8000 -e VNCOPTIONS=-disableBasicAuth cua-ubuntu:latest
36 | ```
37 |
38 | - **VNC Access**: Available at `http://localhost:6901`
39 | - **Computer Server API**: Available at `http://localhost:8000`
40 |
41 | ### Using with CUA Docker Provider
42 |
43 | This container is designed to work with the CUA Docker provider for automated container management:
44 |
45 | ```python
46 | from computer.providers.factory import VMProviderFactory
47 |
48 | # Create docker provider
49 | provider = VMProviderFactory.create_provider(
50 | provider_type="docker",
51 | image="cua-ubuntu:latest",
52 | port=8000, # computer-server API port
53 | noVNC_port=6901 # VNC port
54 | )
55 |
56 | # Run a container
57 | async with provider:
58 | vm_info = await provider.run_vm(
59 | image="cua-ubuntu:latest",
60 | name="my-cua-container",
61 | run_opts={
62 | "memory": "4GB",
63 | "cpu": 2,
64 | "vnc_port": 6901,
65 | "api_port": 8000
66 | }
67 | )
68 | ```
69 |
70 | ## Container Configuration
71 |
72 | ### Ports
73 |
74 | - **6901**: VNC web interface (noVNC)
75 | - **8080**: Computer-server API endpoint
76 |
77 | ### Environment Variables
78 |
79 | - `VNC_PW`: VNC password (default: "password")
80 | - `DISPLAY`: X11 display (set to ":0")
81 |
82 | ### Volumes
83 |
84 | - `/home/kasm-user/storage`: Persistent storage mount point
85 | - `/home/kasm-user/shared`: Shared folder mount point
86 |
87 | ## Creating Filesystem Snapshots
88 |
89 | You can create a filesystem snapshot of the container at any time:
90 |
91 | ```bash
92 | docker commit <container_id> cua-ubuntu-snapshot:latest
93 | ```
94 |
95 | Then run the snapshot:
96 |
97 | ```bash
98 | docker run --rm -it --shm-size=512m -p 6901:6901 -p 8080:8080 -e VNCOPTIONS=-disableBasicAuth cua-ubuntu-snapshot:latest
99 | ```
100 |
101 | Memory snapshots are available using the experimental `docker checkpoint` command. [Docker Checkpoint Documentation](https://docs.docker.com/reference/cli/docker/checkpoint/)
102 |
103 | ## Integration with CUA System
104 |
105 | This container integrates seamlessly with the CUA computer provider system:
106 |
107 | - **Automatic Management**: Use the Docker provider for lifecycle management
108 | - **Resource Control**: Configure memory, CPU, and storage limits
109 | - **Network Access**: Automatic port mapping and IP detection
110 | - **Storage Persistence**: Mount host directories for persistent data
111 | - **Monitoring**: Real-time container status and health checking
112 |
```
--------------------------------------------------------------------------------
/libs/python/som/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 | <h1>
3 | <div class="image-wrapper" style="display: inline-block;">
4 | <picture>
5 | <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
6 | <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
7 | <img alt="Shows my svg">
8 | </picture>
9 | </div>
10 |
11 | [](#)
12 | [](#)
13 | [](https://discord.com/invite/mVnXXpdE85)
14 | [](https://pypi.org/project/cua-computer/)
15 |
16 | </h1>
17 | </div>
18 |
19 | **Som** (Set-of-Mark) is a visual grounding component for the Computer-Use Agent (CUA) framework powering Cua, for detecting and analyzing UI elements in screenshots. Optimized for macOS Silicon with Metal Performance Shaders (MPS), it combines YOLO-based icon detection with EasyOCR text recognition to provide comprehensive UI element analysis.
20 |
21 | ## Features
22 |
23 | - Optimized for Apple Silicon with MPS acceleration
24 | - Icon detection using YOLO with multi-scale processing
25 | - Text recognition using EasyOCR (GPU-accelerated)
26 | - Automatic hardware detection (MPS → CUDA → CPU)
27 | - Smart detection parameters tuned for UI elements
28 | - Detailed visualization with numbered annotations
29 | - Performance benchmarking tools
30 |
31 | ## System Requirements
32 |
33 | - **Recommended**: macOS with Apple Silicon
34 | - Uses Metal Performance Shaders (MPS)
35 | - Multi-scale detection enabled
36 | - ~0.4s average detection time
37 | - **Supported**: Any Python 3.11+ environment
38 | - Falls back to CPU if no GPU available
39 | - Single-scale detection on CPU
40 | - ~1.3s average detection time
41 |
42 | ## Installation
43 |
44 | ```bash
45 | # Using PDM (recommended)
46 | pdm install
47 |
48 | # Using pip
49 | pip install -e .
50 | ```
51 |
52 | ## Quick Start
53 |
54 | ```python
55 | from som import OmniParser
56 | from PIL import Image
57 |
58 | # Initialize parser
59 | parser = OmniParser()
60 |
61 | # Process an image
62 | image = Image.open("screenshot.png")
63 | result = parser.parse(
64 | image,
65 | box_threshold=0.3, # Confidence threshold
66 | iou_threshold=0.1, # Overlap threshold
67 | use_ocr=True # Enable text detection
68 | )
69 |
70 | # Access results
71 | for elem in result.elements:
72 | if elem.type == "icon":
73 | print(f"Icon: confidence={elem.confidence:.3f}, bbox={elem.bbox.coordinates}")
74 | else: # text
75 | print(f"Text: '{elem.content}', confidence={elem.confidence:.3f}")
76 | ```
77 |
78 | ## Docs
79 |
80 | - [Configuration](http://localhost:8090/docs/libraries/som/configuration)
81 |
82 | ## Development
83 |
84 | ### Test Data
85 |
86 | - Place test screenshots in `examples/test_data/`
87 | - Not tracked in git to keep repository size manageable
88 | - Default test image: `test_screen.png` (1920x1080)
89 |
90 | ### Running Tests
91 |
92 | ```bash
93 | # Run benchmark with no OCR
94 | python examples/omniparser_examples.py examples/test_data/test_screen.png --runs 5 --ocr none
95 |
96 | # Run benchmark with OCR
97 | python examples/omniparser_examples.py examples/test_data/test_screen.png --runs 5 --ocr easyocr
98 | ```
99 |
100 | ## License
101 |
102 | MIT License - See LICENSE file for details.
103 |
```
--------------------------------------------------------------------------------
/libs/lumier/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 | <h1>
3 | <div class="image-wrapper" style="display: inline-block;">
4 | <picture>
5 | <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="../../img/logo_white.png" style="display: block; margin: auto;">
6 | <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="../../img/logo_black.png" style="display: block; margin: auto;">
7 | <img alt="Shows my svg">
8 | </picture>
9 | </div>
10 |
11 | [](#)
12 | [](#)
13 | [](https://discord.com/invite/mVnXXpdE85)
14 |
15 | </h1>
16 | </div>
17 |
18 | macOS and Linux virtual machines in a Docker container.
19 |
20 | <div align="center">
21 | <video src="https://github.com/user-attachments/assets/2ecca01c-cb6f-4c35-a5a7-69bc58bd94e2" width="800" controls></video>
22 | </div>
23 |
24 | ## What is Lumier?
25 |
26 | **Lumier** is an interface for running macOS virtual machines with minimal setup. It uses Docker as a packaging system to deliver a pre-configured environment that connects to the `lume` virtualization service running on your host machine. With Lumier, you get:
27 |
28 | - A ready-to-use macOS or Linux virtual machine in minutes
29 | - Browser-based VNC access to your VM
30 | - Easy file sharing between your host and VM
31 | - Simple configuration through environment variables
32 |
33 | ## Requirements
34 |
35 | Before using Lumier, make sure you have:
36 |
37 | 1. **Docker for Apple Silicon** - download it [here](https://desktop.docker.com/mac/main/arm64/Docker.dmg) and follow the installation instructions.
38 |
39 | 2. **Lume** - This is the virtualization CLI that powers Lumier. Install it with this command:
40 |
41 | ```bash
42 | /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
43 | ```
44 |
45 | ## Getting Started
46 |
47 | ```bash
48 | # Run the container with temporary storage (using pre-built image from Docker Hub)
49 | docker run -it --rm \
50 | --name macos-vm \
51 | -p 8006:8006 \
52 | -e VM_NAME=macos-vm \
53 | -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \
54 | -e CPU_CORES=4 \
55 | -e RAM_SIZE=8192 \
56 | trycua/lumier:latest
57 | ```
58 |
59 | After running the command above, you can access your macOS VM through a web browser (e.g., http://localhost:8006).
60 |
61 | > **Note:** With the basic setup above, your VM will be reset when you stop the container (ephemeral mode). This means any changes you make inside the macOS VM will be lost. See [the documentation](https://cua.ai/docs/macos-vm-cli-playbook/lumier/docker) for how to save your VM state.
62 |
63 | ## Docs
64 |
65 | - [Installation](https://cua.ai/docs/macos-vm-cli-playbook/lumier/installation)
66 | - [Docker](https://cua.ai/docs/macos-vm-cli-playbook/lumier/docker)
67 | - [Docker Compose](https://cua.ai/docs/macos-vm-cli-playbook/lumier/docker-compose)
68 | - [Building Lumier](https://cua.ai/docs/macos-vm-cli-playbook/lumier/building-lumier)
69 |
70 | ## Credits
71 |
72 | This project was inspired by [dockur/windows](https://github.com/dockur/windows) and [dockur/macos](https://github.com/dockur/macos), which pioneered the approach of running Windows and macOS VMs in Docker containers.
73 |
74 | Main differences with dockur/macos:
75 |
76 | - Lumier is specifically designed for macOS virtualization
77 | - Lumier supports Apple Silicon (M1/M2/M3/M4) while dockur/macos only supports Intel
78 | - Lumier uses the Apple Virtualization Framework (Vz) through the `lume` CLI to create true virtual machines, while dockur relies on KVM.
79 | - Image specification is different, with Lumier and Lume relying on Apple Vz spec (disk.img and nvram.bin)
80 |
```
--------------------------------------------------------------------------------
/libs/python/agent/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 | <h1>
3 | <div class="image-wrapper" style="display: inline-block;">
4 | <picture>
5 | <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
6 | <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
7 | <img alt="Shows my svg">
8 | </picture>
9 | </div>
10 |
11 | [](#)
12 | [](#)
13 | [](https://discord.com/invite/mVnXXpdE85)
14 | [](https://pypi.org/project/cua-computer/)
15 |
16 | </h1>
17 | </div>
18 |
19 | **cua-agent** is a general Computer-Use framework with liteLLM integration for running agentic workflows on macOS, Windows, and Linux sandboxes. It provides a unified interface for computer-use agents across multiple LLM providers with advanced callback system for extensibility.
20 |
21 | ## Features
22 |
23 | - **Safe Computer-Use/Tool-Use**: Using Computer SDK for sandboxed desktops
24 | - **Multi-Agent Support**: Anthropic Claude, OpenAI computer-use-preview, UI-TARS, Omniparser + any LLM
25 | - **Multi-API Support**: Take advantage of liteLLM supporting 100+ LLMs / model APIs, including local models (`huggingface-local/`, `ollama_chat/`, `mlx/`)
26 | - **Cross-Platform**: Works on Windows, macOS, and Linux with cloud and local computer instances
27 | - **Extensible Callbacks**: Built-in support for image retention, cache control, PII anonymization, budget limits, and trajectory tracking
28 |
29 | ## Install
30 |
31 | ```bash
32 | pip install "cua-agent[all]"
33 | ```
34 |
35 | ## Quick Start
36 |
37 | ```python
38 | import asyncio
39 | import os
40 | from agent import ComputerAgent
41 | from computer import Computer
42 |
43 | async def main():
44 | # Set up computer instance
45 | async with Computer(
46 | os_type="linux",
47 | provider_type="cloud",
48 | name=os.getenv("CUA_CONTAINER_NAME"),
49 | api_key=os.getenv("CUA_API_KEY")
50 | ) as computer:
51 |
52 | # Create agent
53 | agent = ComputerAgent(
54 | model="anthropic/claude-sonnet-4-5-20250929",
55 | tools=[computer],
56 | only_n_most_recent_images=3,
57 | trajectory_dir="trajectories",
58 | max_trajectory_budget=5.0 # $5 budget limit
59 | )
60 |
61 | # Run agent
62 | messages = [{"role": "user", "content": "Take a screenshot and tell me what you see"}]
63 |
64 | async for result in agent.run(messages):
65 | for item in result["output"]:
66 | if item["type"] == "message":
67 | print(item["content"][0]["text"])
68 |
69 | if __name__ == "__main__":
70 | asyncio.run(main())
71 | ```
72 |
73 | ## Docs
74 |
75 | - [Agent Loops](https://cua.ai/docs/agent-sdk/agent-loops)
76 | - [Supported Agents](https://cua.ai/docs/agent-sdk/supported-agents/computer-use-agents)
77 | - [Supported Models](https://cua.ai/docs/agent-sdk/supported-model-providers)
78 | - [Chat History](https://cua.ai/docs/agent-sdk/chat-history)
79 | - [Callbacks](https://cua.ai/docs/agent-sdk/callbacks)
80 | - [Custom Tools](https://cua.ai/docs/agent-sdk/custom-tools)
81 | - [Custom Computer Handlers](https://cua.ai/docs/computer-sdk/custom-computer-handlers)
82 | - [Prompt Caching](https://cua.ai/docs/agent-sdk/prompt-caching)
83 | - [Usage Tracking](https://cua.ai/docs/agent-sdk/usage-tracking)
84 | - [Benchmarks](https://cua.ai/docs/agent-sdk/benchmarks)
85 |
86 | ## License
87 |
88 | MIT License - see LICENSE file for details.
89 |
```
--------------------------------------------------------------------------------
/libs/typescript/agent/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # @trycua/agent
2 |
3 | TypeScript SDK for CUA agent interaction. Connect to CUA agent proxies via HTTP/HTTPS or peer-to-peer (WebRTC) connections.
4 |
5 | ## Installation
6 |
7 | ```bash
8 | npm install @trycua/agent
9 | # or
10 | pnpm add @trycua/agent
11 | # or
12 | yarn add @trycua/agent
13 | ```
14 |
15 | ## Usage
16 |
17 | ### Basic Usage
18 |
19 | ```typescript
20 | import AgentClient from '@trycua/agent';
21 |
22 | // Connect to local HTTP server
23 | const client = new AgentClient('https://localhost:8000');
24 |
25 | // Connect to a cloud container (port 8443 over HTTPS)
26 | const cloud = new AgentClient('https://m-linux-96lcxd2c2k.containers.cloud.trycua.com:8443', {
27 | apiKey: process.env.NEXT_PUBLIC_CUA_API_KEY || '',
28 | });
29 |
30 | // Connect to peer
31 | const peerClient = new AgentClient('peer://my-agent-proxy');
32 |
33 | // Send a simple text request
34 | const response = await client.responses.create({
35 | model: 'anthropic/claude-sonnet-4-5-20250929',
36 | input: 'Write a one-sentence bedtime story about a unicorn.',
37 | // Optional per-request env overrides
38 | env: {
39 | OPENAI_API_KEY: 'sk-...',
40 | },
41 | });
42 |
43 | console.log(response.output);
44 | ```
45 |
46 | ### Multi-modal Requests
47 |
48 | ```typescript
49 | const response = await client.responses.create({
50 | model: 'anthropic/claude-sonnet-4-5-20250929',
51 | input: [
52 | {
53 | role: 'user',
54 | content: [
55 | { type: 'input_text', text: 'What is in this image?' },
56 | {
57 | type: 'input_image',
58 | image_url: 'https://example.com/image.jpg',
59 | },
60 | ],
61 | },
62 | ],
63 | env: { OPENROUTER_API_KEY: 'sk-...' },
64 | });
65 | ```
66 |
67 | ### Advanced Configuration
68 |
69 | ```typescript
70 | const client = new AgentClient('https://localhost:8000', {
71 | timeout: 60000, // 60 second timeout
72 | retries: 5, // 5 retry attempts
73 | apiKey: 'cua_...', // sent as X-API-Key header when using HTTP/HTTPS
74 | });
75 |
76 | const response = await client.responses.create({
77 | model: 'anthropic/claude-sonnet-4-5-20250929',
78 | input: 'Hello, world!',
79 | agent_kwargs: {
80 | save_trajectory: true,
81 | verbosity: 20,
82 | },
83 | computer_kwargs: {
84 | os_type: 'linux',
85 | provider_type: 'cloud',
86 | },
87 | // Per-request env overrides
88 | env: {
89 | ANTHROPIC_API_KEY: 'sk-...',
90 | OPENROUTER_API_KEY: 'sk-...',
91 | },
92 | });
93 | ```
94 |
95 | ### Health Check
96 |
97 | ```typescript
98 | const health = await client.health();
99 | console.log(health.status); // 'healthy', 'unhealthy', 'unreachable', 'connected', 'disconnected'
100 | ```
101 |
102 | ### Cleanup
103 |
104 | ```typescript
105 | // Clean up peer connections when done
106 | await client.disconnect();
107 | ```
108 |
109 | ## API Reference
110 |
111 | ### AgentClient
112 |
113 | #### Constructor
114 |
115 | ```typescript
116 | new AgentClient(url: string, options?: AgentClientOptions)
117 | ```
118 |
119 | - `url`: Connection URL. Supports `http://`, `https://`, or `peer://` protocols
120 | - `options`: Optional configuration object
121 |
122 | #### Methods
123 |
124 | ##### responses.create(request: AgentRequest): Promise<AgentResponse>
125 |
126 | Send a request to the agent and get a response.
127 |
128 | ##### health(): Promise<{status: string}>
129 |
130 | Check the health/connection status of the agent.
131 |
132 | ##### disconnect(): Promise<void>
133 |
134 | Clean up resources and close connections.
135 |
136 | ### Types
137 |
138 | #### AgentRequest
139 |
140 | ```typescript
141 | interface AgentRequest {
142 | model: string;
143 | input: string | AgentMessage[];
144 | agent_kwargs?: {
145 | save_trajectory?: boolean;
146 | verbosity?: number;
147 | [key: string]: any;
148 | };
149 | computer_kwargs?: {
150 | os_type?: string;
151 | provider_type?: string;
152 | [key: string]: any;
153 | };
154 | // Optional per-request environment overrides
155 | env?: Record<string, string>;
156 | }
157 | ```
158 |
159 | #### AgentResponse
160 |
161 | ```typescript
162 | interface AgentResponse {
163 | output: AgentMessage[];
164 | usage: Usage;
165 | }
166 |
167 | interface Usage {
168 | prompt_tokens: number;
169 | completion_tokens: number;
170 | total_tokens: number;
171 | response_cost: number;
172 | }
173 | ```
174 |
175 | The `output` array contains the conversation history including:
176 |
177 | - User messages
178 | - Agent reasoning/thinking
179 | - Computer actions and their results
180 | - Final agent responses
181 |
182 | The `usage` object provides token counts and cost information for the request.
183 |
184 | ## Connection Types
185 |
186 | ### HTTP/HTTPS
187 |
188 | Connect to a CUA agent proxy server:
189 |
190 | ```typescript
191 | // Local
192 | const client = new AgentClient('https://my-agent-server.com:8000', { apiKey: 'cua_...' });
193 |
194 | // Cloud container (port 8443)
195 | const cloud = new AgentClient('https://m-linux-96lcxd2c2k.containers.cloud.trycua.com:8443', {
196 | apiKey: 'cua_...',
197 | });
198 | ```
199 |
200 | Notes:
201 |
202 | - The client sends the API key as `X-API-Key` for HTTP/HTTPS connections.
203 | - Cloud containers listen on `:8443` with HTTPS.
204 |
205 | ### Peer-to-Peer (WebRTC)
206 |
207 | Connect directly to another peer using WebRTC:
208 |
209 | ```typescript
210 | const client = new AgentClient('peer://agent-proxy-peer-id');
211 | ```
212 |
213 | The client uses PeerJS with default configuration for peer connections.
214 |
215 | ## License
216 |
217 | MIT
218 |
```
--------------------------------------------------------------------------------
/libs/python/mcp-server/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 | <h1>
3 | <div class="image-wrapper" style="display: inline-block;">
4 | <picture>
5 | <source media="(prefers-color-scheme: dark)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_white.png" style="display: block; margin: auto;">
6 | <source media="(prefers-color-scheme: light)" alt="logo" height="150" srcset="https://raw.githubusercontent.com/trycua/cua/main/img/logo_black.png" style="display: block; margin: auto;">
7 | <img alt="Shows my svg">
8 | </picture>
9 | </div>
10 |
11 | [](#)
12 | [](#)
13 | [](https://discord.com/invite/mVnXXpdE85)
14 | [](https://pypi.org/project/cua-computer/)
15 |
16 | </h1>
17 | </div>
18 |
19 | # cua-mcp-server
20 |
21 | cua-mcp-server is an MCP server for the Computer-Use Agent (CUA). It enables CUA to run through MCP clients such as Claude Desktop and Cursor.
22 |
23 | ## Prerequisites
24 |
25 | - Install lume: https://github.com/trycua/cua/blob/main/libs/lume/README.md#install
26 | - Python 3.10+
27 | - pip, venv, setuptools
28 |
29 | ## Install
30 |
31 | Download and run the installation script:
32 |
33 | ```bash
34 | curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/python/mcp-server/scripts/install_mcp_server.sh | bash
35 | ```
36 |
37 | Add this to your MCP client configuration:
38 |
39 | ```json
40 | {
41 | "mcpServers": {
42 | "cua-agent": {
43 | "command": "/usr/bin/env",
44 | "args": [
45 | "bash",
46 | "-lc",
47 | "export CUA_MODEL_NAME='anthropic/claude-sonnet-4-5-20250929'; ~/.cua/start_mcp_server.sh"
48 | ]
49 | }
50 | }
51 | }
52 | ```
53 |
54 | ## Development (run from a local checkout)
55 |
56 | Use an absolute path to the repository root in the arguments below.
57 |
58 | ```json
59 | {
60 | "mcpServers": {
61 | "cua-agent": {
62 | "command": "/usr/bin/env",
63 | "args": [
64 | "bash",
65 | "-lc",
66 | "export CUA_MODEL_NAME='huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B'; /Users/your-username/Documents/GitHub/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"
67 | ]
68 | }
69 | }
70 | }
71 | ```
72 |
73 | Notes:
74 |
75 | - Replace `/Users/your-username/Documents/GitHub/cua` with the absolute path to your clone.
76 | - The script sets `PYTHONPATH` for local libs and runs the server module.
77 |
78 | ## Quick Start
79 |
80 | After configuring your MCP client, restart it and invoke one of these tools:
81 |
82 | - Take a screenshot
83 |
84 | ```json
85 | {
86 | "tool": "screenshot_cua",
87 | "args": {}
88 | }
89 | ```
90 |
91 | - Run a task
92 |
93 | ```json
94 | {
95 | "tool": "run_cua_task",
96 | "args": { "task": "Open Safari and search for University of Toronto" }
97 | }
98 | ```
99 |
100 | Expected results:
101 |
102 | - Assistant messages streamed during execution
103 | - A final screenshot image
104 |
105 | ## Desktop Extension
106 |
107 | CUA also provides a Claude Desktop Extension (`.mcpb` file) for easy one-click installation.
108 |
109 | ### Building the Desktop Extension
110 |
111 | To build the desktop extension from source:
112 |
113 | ```bash
114 | cd libs/python/mcp-server
115 | python3 build-extension.py
116 | ```
117 |
118 | This creates `desktop-extension/cua-extension.mcpb` which can be installed directly in Claude Desktop.
119 |
120 | ### Installing the Desktop Extension
121 |
122 | 1. Build the extension (see above)
123 | 2. Open Claude Desktop Settings
124 | 3. Go to Extensions
125 | 4. Drop the `cua-extension.mcpb` file into the window
126 | 5. Follow the installation prompts
127 |
128 | See [desktop-extension/README.md](desktop-extension/README.md) for more details.
129 |
130 | ## Documentation
131 |
132 | - Installation: https://cua.ai/docs/agent-sdk/mcp-server/installation
133 | - Configuration: https://cua.ai/docs/agent-sdk/mcp-server/configuration
134 | - Usage: https://cua.ai/docs/agent-sdk/mcp-server/usage
135 | - Tools: https://cua.ai/docs/agent-sdk/mcp-server/tools
136 | - Client Integrations: https://cua.ai/docs/agent-sdk/mcp-server/client-integrations
137 | - LLM Integrations: https://cua.ai/docs/agent-sdk/mcp-server/llm-integrations
138 |
139 | ## Troubleshooting
140 |
141 | Server reports disconnected in MCP client:
142 |
143 | - Use an absolute path in the `args` command.
144 | - Launch via `/usr/bin/env bash -lc` so the shell initializes and expands paths.
145 | - Run the script manually to verify:
146 | ```bash
147 | /usr/bin/env bash -lc '/Users/your-username/Documents/GitHub/cua/libs/python/mcp-server/scripts/start_mcp_server.sh'
148 | ```
149 |
150 | pip not found in venv:
151 |
152 | ```bash
153 | python3 -m ensurepip --upgrade
154 | python3 -m pip install -U pip setuptools wheel
155 | ```
156 |
157 | Pydantic schema error related to Image:
158 |
159 | ```bash
160 | python3 -m pip install -U "mcp>=1.2.0" "fastmcp>=0.4.7" "pydantic>=2.7,<2.12"
161 | ```
162 |
163 | If issues persist, capture logs from your MCP client and the server startup script for diagnosis.
164 |
```
--------------------------------------------------------------------------------
/libs/qemu-docker/windows/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # CUA Windows Container
2 |
3 | Containerized Windows 11 virtual desktop for Computer-Using Agents (CUA). Utilizes QEMU/KVM with Windows 11 and computer-server pre-installed for remote computer control.
4 |
5 | ## Features
6 |
7 | - Windows 11 Enterprise running in QEMU/KVM
8 | - Pre-installed CUA computer-server for remote computer control
9 | - Caddy reverse proxy (port 9222 → 1337) for browser automation
10 | - noVNC access for visual desktop interaction
11 | - Automated setup via unattended installation
12 | - Support for both dev (shared folder) and azure (OEM folder) deployment modes
13 | - Python 3.12 with isolated virtual environment for CUA computer-server
14 | - Services run hidden in background via Windows scheduled tasks
15 | - Essential tools pre-installed (Chrome, LibreOffice, VLC, GIMP, VSCode, Thunderbird)
16 |
17 | ## Quick Start
18 |
19 | ### 1. Download and Prepare setup.iso
20 |
21 | **Download Windows 11 Evaluation ISO:**
22 |
23 | 1. Visit [Microsoft Evaluation Center](https://info.microsoft.com/ww-landing-windows-11-enterprise.html)
24 | 2. Accept the Terms of Service
25 | 3. Download **Windows 11 Enterprise Evaluation (90-day trial, English, United States)** ISO file [~6GB]
26 | 4. After downloading, rename the file to `setup.iso`
27 | 5. Copy it to the directory `src/vm/image/`
28 |
29 | This ISO is used for automated Windows installation on first run.
30 |
31 | ### 2. Build the Image
32 |
33 | ```bash
34 | docker build -t cua-windows:dev .
35 | ```
36 |
37 | ### 3. First Run - Create Golden Image
38 |
39 | On first run, the container will install Windows from scratch and create a golden image. This takes 15-30 minutes.
40 |
41 | ```bash
42 | # Create storage directory
43 | mkdir -p ./storage
44 |
45 | # Run with setup.iso to create golden image
46 | docker run -it --rm \
47 | --device=/dev/kvm \
48 | --platform linux/amd64 \
49 | --name cua-windows \
50 | --mount type=bind,source=$(pwd)/src/vm/image/setup.iso,target=/custom.iso \
51 | --cap-add NET_ADMIN \
52 | -v $(pwd)/storage:/storage \
53 | -p 8006:8006 \
54 | -p 5000:5000 \
55 | -e RAM_SIZE=8G \
56 | -e CPU_CORES=4 \
57 | -e DISK_SIZE=20G \
58 | cua-windows:dev
59 | ```
60 |
61 | **What happens during first run:**
62 |
63 | 1. Windows 11 installs automatically using unattended configuration
64 | 2. Setup scripts install Python 3.12, Git, and CUA computer-server in isolated venv
65 | 3. Windows scheduled tasks created for CUA server and Caddy proxy (run hidden in background)
66 | 4. Golden image is saved to `/storage` directory
67 | 5. Container exits after setup completes
68 |
69 | ### 4. Subsequent Runs - Use Golden Image
70 |
71 | After the golden image is created, subsequent runs boot much faster (30 sec - 2 min):
72 |
73 | ```bash
74 | # Run without setup.iso - uses existing golden image
75 | docker run -it --rm \
76 | --device=/dev/kvm \
77 | --platform linux/amd64 \
78 | --name cua-windows \
79 | --cap-add NET_ADMIN \
80 | -v $(pwd)/storage:/storage \
81 | -p 8006:8006 \
82 | -p 5000:5000 \
83 | -e RAM_SIZE=8G \
84 | -e CPU_CORES=4 \
85 | cua-windows:dev
86 | ```
87 |
88 | **Access points:**
89 |
90 | - **Computer Server API**: `http://localhost:5000`
91 | - **noVNC Browser**: `http://localhost:8006`
92 |
93 | ## Container Configuration
94 |
95 | ### Ports
96 |
97 | - **5000**: CUA computer-server API endpoint
98 | - **8006**: noVNC web interface for visual desktop access
99 |
100 | ### Environment Variables
101 |
102 | - `RAM_SIZE`: RAM allocated to Windows VM (default: "8G", recommended: "8G" for WSL2)
103 | - `CPU_CORES`: CPU cores allocated to VM (default: "8")
104 | - `DISK_SIZE`: VM disk size (default: "30G", minimum: "20G")
105 | - `VERSION`: Windows version (default: "win11x64-enterprise-eval")
106 |
107 | ### Volumes
108 |
109 | - `/storage`: Persistent VM storage (golden image, disk, firmware)
110 | - `/custom.iso`: Mount point for setup.iso (only needed for first run)
111 |
112 | ## Architecture
113 |
114 | ```
115 | ┌─────────────────────────────────────────────────────────┐
116 | │ Docker Container (Linux host) │
117 | │ │
118 | │ • Port forwarding: localhost:5000 → EMULATOR_IP:5000 │
119 | │ • Exposes: 5000 (API), 8006 (noVNC) │
120 | │ │
121 | │ ┌────────────────────────────────────────────────────┐ │
122 | │ │ QEMU VM (Windows 11) │ │
123 | │ │ │ │
124 | │ │ • CUA computer-server listens on 5000 │ │
125 | │ │ │ │
126 | │ └────────────────────────────────────────────────────┘ │
127 | │ │
128 | └─────────────────────────────────────────────────────────┘
129 | ```
130 |
131 | **Communication Flow:**
132 |
133 | 1. External client → `localhost:5000` (host)
134 | 2. Docker port mapping → Container's `localhost:5000`
135 | 3. socat port forwarding → `20.20.20.21:5000` (VM)
136 | 4. CUA computer-server in Windows VM processes request
137 |
138 | ## Development
139 |
140 | ### Modifying Setup Scripts
141 |
142 | Setup scripts are in `src/vm/setup/`:
143 |
144 | - `install.bat`: Entry point called by Windows setup
145 | - `setup.ps1`: Main setup orchestration (installs software, configures Windows)
146 | - `setup-cua-server.ps1`: CUA server installation with isolated venv
147 | - `on-logon.ps1`: Runs on user logon (starts scheduled tasks)
148 | - `setup-utils.psm1`: Helpers functions for setup
149 |
150 | After modifying, rebuild the image:
151 |
152 | ```bash
153 | docker build -t cua-windows:dev .
154 | ```
155 |
156 | ## Credits
157 |
158 | - Built on [Dockur Windows](https://github.com/dockur/windows) base image
159 | - Inspired by [Windows Agent Arena](https://github.com/microsoft/WindowsAgentArena)
160 |
```
--------------------------------------------------------------------------------
/.github/scripts/tests/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Tests for .github/scripts
2 |
3 | This directory contains comprehensive tests for the GitHub workflow scripts using Python's built-in testing framework.
4 |
5 | ## Requirements
6 |
7 | **No external dependencies required!**
8 |
9 | This test suite uses:
10 |
11 | - `unittest` - Python's built-in testing framework
12 | - `tomllib` - Python 3.11+ built-in TOML parser
13 |
14 | For Python < 3.11, the `toml` package is used as a fallback.
15 |
16 | ## Running Tests
17 |
18 | ### Run all tests
19 |
20 | ```bash
21 | cd .github/scripts/tests
22 | python3 -m unittest discover -v
23 | ```
24 |
25 | ### Run a specific test file
26 |
27 | ```bash
28 | python3 -m unittest test_get_pyproject_version -v
29 | ```
30 |
31 | ### Run a specific test class
32 |
33 | ```bash
34 | python3 -m unittest test_get_pyproject_version.TestGetPyprojectVersion -v
35 | ```
36 |
37 | ### Run a specific test method
38 |
39 | ```bash
40 | python3 -m unittest test_get_pyproject_version.TestGetPyprojectVersion.test_matching_versions -v
41 | ```
42 |
43 | ### Run tests directly from the test file
44 |
45 | ```bash
46 | python3 test_get_pyproject_version.py
47 | ```
48 |
49 | ## Test Structure
50 |
51 | ### test_get_pyproject_version.py
52 |
53 | Comprehensive tests for `get_pyproject_version.py` covering:
54 |
55 | - ✅ **Version matching**: Tests successful version validation
56 | - ✅ **Version mismatch**: Tests error handling when versions don't match
57 | - ✅ **Missing version**: Tests handling of pyproject.toml without version field
58 | - ✅ **Missing project section**: Tests handling of pyproject.toml without project section
59 | - ✅ **File not found**: Tests handling of non-existent files
60 | - ✅ **Malformed TOML**: Tests handling of invalid TOML syntax
61 | - ✅ **Argument validation**: Tests proper argument count validation
62 | - ✅ **Semantic versioning**: Tests various semantic version formats
63 | - ✅ **Pre-release tags**: Tests versions with alpha, beta, rc tags
64 | - ✅ **Build metadata**: Tests versions with build metadata
65 | - ✅ **Edge cases**: Tests empty versions and other edge cases
66 |
67 | **Total Tests**: 17+ test cases covering all functionality
68 |
69 | ## Best Practices Implemented
70 |
71 | 1. **Fixture Management**: Uses `setUp()` and `tearDown()` for clean test isolation
72 | 2. **Helper Methods**: Provides reusable helpers for creating test fixtures
73 | 3. **Temporary Files**: Uses `tempfile` for file creation with proper cleanup
74 | 4. **Comprehensive Coverage**: Tests happy paths, error conditions, and edge cases
75 | 5. **Clear Documentation**: Each test has a descriptive docstring
76 | 6. **Output Capture**: Uses `unittest.mock.patch` and `StringIO` to test stdout/stderr
77 | 7. **Exit Code Validation**: Properly tests script exit codes with `assertRaises(SystemExit)`
78 | 8. **Type Hints**: Uses type hints in helper methods for clarity
79 | 9. **PEP 8 Compliance**: Follows Python style guidelines
80 | 10. **Zero External Dependencies**: Uses only Python standard library
81 |
82 | ## Continuous Integration
83 |
84 | These tests can be integrated into GitHub Actions workflows with no additional dependencies:
85 |
86 | ```yaml
87 | - name: Run .github scripts tests
88 | run: |
89 | cd .github/scripts/tests
90 | python3 -m unittest discover -v
91 | ```
92 |
93 | ## Test Output Example
94 |
95 | ```
96 | test_empty_version_string (test_get_pyproject_version.TestGetPyprojectVersion)
97 | Test handling of empty version string. ... ok
98 | test_file_not_found (test_get_pyproject_version.TestGetPyprojectVersion)
99 | Test handling of non-existent pyproject.toml file. ... ok
100 | test_malformed_toml (test_get_pyproject_version.TestGetPyprojectVersion)
101 | Test handling of malformed TOML file. ... ok
102 | test_matching_versions (test_get_pyproject_version.TestGetPyprojectVersion)
103 | Test that matching versions result in success. ... ok
104 | test_missing_project_section (test_get_pyproject_version.TestGetPyprojectVersion)
105 | Test handling of pyproject.toml without a project section. ... ok
106 | test_missing_version_field (test_get_pyproject_version.TestGetPyprojectVersion)
107 | Test handling of pyproject.toml without a version field. ... ok
108 | test_no_arguments (test_get_pyproject_version.TestGetPyprojectVersion)
109 | Test that providing no arguments results in usage error. ... ok
110 | test_semantic_version_0_0_1 (test_get_pyproject_version.TestGetPyprojectVersion)
111 | Test semantic version 0.0.1. ... ok
112 | test_semantic_version_1_0_0 (test_get_pyproject_version.TestGetPyprojectVersion)
113 | Test semantic version 1.0.0. ... ok
114 | test_semantic_version_10_20_30 (test_get_pyproject_version.TestGetPyprojectVersion)
115 | Test semantic version 10.20.30. ... ok
116 | test_semantic_version_alpha (test_get_pyproject_version.TestGetPyprojectVersion)
117 | Test semantic version with alpha tag. ... ok
118 | test_semantic_version_beta (test_get_pyproject_version.TestGetPyprojectVersion)
119 | Test semantic version with beta tag. ... ok
120 | test_semantic_version_rc_with_build (test_get_pyproject_version.TestGetPyprojectVersion)
121 | Test semantic version with rc and build metadata. ... ok
122 | test_too_few_arguments (test_get_pyproject_version.TestGetPyprojectVersion)
123 | Test that providing too few arguments results in usage error. ... ok
124 | test_too_many_arguments (test_get_pyproject_version.TestGetPyprojectVersion)
125 | Test that providing too many arguments results in usage error. ... ok
126 | test_version_mismatch (test_get_pyproject_version.TestGetPyprojectVersion)
127 | Test that mismatched versions result in failure with appropriate error message. ... ok
128 | test_version_with_build_metadata (test_get_pyproject_version.TestGetPyprojectVersion)
129 | Test matching versions with build metadata. ... ok
130 | test_version_with_prerelease_tags (test_get_pyproject_version.TestGetPyprojectVersion)
131 | Test matching versions with pre-release tags like alpha, beta, rc. ... ok
132 |
133 | ----------------------------------------------------------------------
134 | Ran 18 tests in 0.XXXs
135 |
136 | OK
137 | ```
138 |
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 | <a href="https://cua.ai" target="_blank" rel="noopener noreferrer">
3 | <picture>
4 | <source media="(prefers-color-scheme: dark)" alt="Cua logo" width="150" srcset="img/logo_white.png">
5 | <source media="(prefers-color-scheme: light)" alt="Cua logo" width="150" srcset="img/logo_black.png">
6 | <img alt="Cua logo" width="500" src="img/logo_black.png">
7 | </picture>
8 | </a>
9 |
10 | <p align="center">Build and deploy AI agents that can reason, plan and act on any Computers</p>
11 |
12 | <p align="center">
13 | <a href="https://cua.ai" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/cua.ai-0ea5e9" alt="cua.ai"></a>
14 | <a href="https://discord.com/invite/cua-ai" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Discord-Join%20Server-10b981?logo=discord&logoColor=white" alt="Discord"></a>
15 | <a href="https://x.com/trycua" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/twitter/follow/trycua?style=social" alt="Twitter"></a>
16 | <a href="https://cua.ai/docs" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Docs-0ea5e9.svg" alt="Documentation"></a>
17 | <br>
18 | <a href="https://trendshift.io/repositories/13685" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13685" alt="trycua%2Fcua | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
19 | </p>
20 |
21 | </div>
22 |
23 | **Cua** ("koo-ah") is an open-source framework for Computer-Use Agents - enabling AI systems to autonomously operate computers through visual understanding and action execution. Used for research, evaluation, and production deployment of desktop, browser, and mobile automation agents.
24 |
25 | ## What are Computer-Use Agents?
26 |
27 | Computer-Use Agents (CUAs) are AI systems that can autonomously interact with computer interfaces through visual understanding and action execution. Unlike traditional automation tools that rely on brittle selectors or APIs, CUAs use vision-language models to perceive screen content and reason about interface interactions - enabling them to adapt to UI changes and handle complex, multi-step workflows across applications.
28 |
29 | <div align="center">
30 | <video src="https://github.com/user-attachments/assets/c619b4ea-bb8e-4382-860e-f3757e36af20" width="600" controls></video>
31 | </div>
32 |
33 | With the [Computer SDK](#computer-sdk), you can:
34 |
35 | - automate Windows, Linux, and macOS VMs with a consistent, [pyautogui-like API](https://cua.ai/docs/computer-sdk/commands)
36 | - create & manage VMs [locally](https://cua.ai/docs/quickstart-devs#using-computer) or using [Cua cloud](https://www.cua.ai/)
37 |
38 | With the [Agent SDK](#agent-sdk), you can:
39 |
40 | - run computer-use models with a [consistent schema](https://cua.ai/docs/agent-sdk/message-format)
41 | - benchmark on OSWorld-Verified (369 tasks), SheetBench-V2, and ScreenSpot [with a single line of code using HUD](https://cua.ai/docs/agent-sdk/integrations/hud) - see [benchmark results](#research--benchmarks) ([Notebook](https://github.com/trycua/cua/blob/main/notebooks/eval_osworld.ipynb))
42 | - combine UI grounding models with any LLM using [composed agents](https://cua.ai/docs/agent-sdk/supported-agents/composed-agents)
43 | - use new UI agent models and UI grounding models from the Model Zoo below with just a model string (e.g., `ComputerAgent(model="openai/computer-use-preview")`)
44 | - use API or local inference by changing a prefix (e.g., `openai/`, `openrouter/`, `ollama/`, `huggingface-local/`, `mlx/`, [etc.](https://docs.litellm.ai/docs/providers))
45 |
46 | # Modules
47 |
48 | <table>
49 | <tr>
50 | <td width="25%" align="center" valign="top">
51 |
52 | [**Agent**](#agent-sdk)<br />
53 | AI agent framework for automating tasks
54 |
55 | </td>
56 | <td width="25%" align="center" valign="top">
57 |
58 | **[Computer](#computer-sdk)**<br />
59 | TypeScript/Python SDK for controlling Cua environments
60 |
61 | </td>
62 | <td width="25%" align="center" valign="top">
63 |
64 | **[MCP Server](#mcp-server)**<br />
65 | MCP server for using Cua agents and computers
66 |
67 | </td>
68 | <td width="25%" align="center" valign="top">
69 |
70 | **[Computer Server](#computer-server)**<br />
71 | Server component that runs on Cua environments
72 |
73 | </td>
74 | </tr>
75 | </table>
76 |
77 | <table>
78 | <tr>
79 | <td width="25%" align="center" valign="top">
80 |
81 | **[Lume](#lume)**<br />
82 | VM management for macOS
83 |
84 | </td>
85 | <td width="25%" align="center" valign="top">
86 |
87 | **[Lumier](#lumier)**<br />
88 | Docker interface for macOS/Linux VMs
89 |
90 | </td>
91 | <td width="25%" align="center" valign="top">
92 |
93 | **[SOM](#som)**<br />
94 | Set-of-Mark library for Agent
95 |
96 | </td>
97 | <td width="25%" align="center" valign="top">
98 |
99 | **[Core](#core)**<br />
100 | Core utilities for Cua
101 |
102 | </td>
103 | </tr>
104 | </table>
105 |
106 | # Quick Start
107 |
108 | - [Clone a starter template and run the code in <1 min](https://github.com/trycua/agent-template)
109 | - [Get started with the Cua SDKs](https://cua.ai/docs/quickstart-devs)
110 | - [Get started with the Cua CLI](https://cua.ai/docs/quickstart-cli)
111 |
112 | ## Python Version Compatibility
113 |
114 | Cua packages require **Python 3.12 or 3.13**. Python 3.14 is not currently supported due to dependency compatibility issues (pydantic-core/PyO3 compatibility). If you encounter build errors on Python 3.14, please use Python 3.13 or earlier.
115 |
116 | # Agent SDK
117 |
118 | Install the agent SDK:
119 |
120 | ```bash
121 | pip install cua-agent[all]
122 | ```
123 |
124 | Initialize a computer agent using a [model configuration string](#model-configuration) and a [computer instance](#computer-usage):
125 |
126 | ```python
127 | from agent import ComputerAgent
128 |
129 | # ComputerAgent works with any computer initialized with the Computer SDK
130 |
131 | agent = ComputerAgent(
132 | model="anthropic/claude-sonnet-4-5-20250929",
133 | tools=[computer],
134 | max_trajectory_budget=5.0
135 | )
136 |
137 | messages = [{"role": "user", "content": "Take a screenshot and tell me what you see"}]
138 |
139 | async for result in agent.run(messages):
140 | for item in result["output"]:
141 | if item["type"] == "message":
142 | print(item["content"][0]["text"])
143 | ```
144 |
145 | ## Output format
146 |
147 | Cua uses the OpenAI Agent response format.
148 |
149 | <details>
150 | <summary>Example</summary>
151 |
152 | ```json
153 | {
154 | "output": [
155 | {
156 | "role": "user",
157 | "content": "go to trycua on gh"
158 | },
159 | {
160 | "summary": [
161 | {
162 | "text": "Searching Firefox for Trycua GitHub",
163 | "type": "summary_text"
164 | }
165 | ],
166 | "type": "reasoning"
167 | },
168 | {
169 | "action": {
170 | "text": "Trycua GitHub",
171 | "type": "type"
172 | },
173 | "call_id": "call_QI6OsYkXxl6Ww1KvyJc4LKKq",
174 | "status": "completed",
175 | "type": "computer_call"
176 | },
177 | {
178 | "type": "computer_call_output",
179 | "call_id": "call_QI6OsYkXxl6Ww1KvyJc4LKKq",
180 | "output": {
181 | "type": "input_image",
182 | "image_url": "data:image/png;base64,..."
183 | }
184 | },
185 | {
186 | "type": "message",
187 | "role": "assistant",
188 | "content": [
189 | {
190 | "text": "Success! The Trycua GitHub page has been opened.",
191 | "type": "output_text"
192 | }
193 | ]
194 | }
195 | ],
196 | "usage": {
197 | "prompt_tokens": 150,
198 | "completion_tokens": 75,
199 | "total_tokens": 225,
200 | "response_cost": 0.01
201 | }
202 | }
203 | ```
204 |
205 | </details>
206 |
207 | ## Model Configuration
208 |
209 | These are the valid model configurations for `ComputerAgent(model="...")`:
210 |
211 | | Configuration | Description |
212 | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
213 | | `{computer-use-model}` | A single model to perform all computer-use tasks |
214 | | `{grounding-model}+{any-vlm-with-tools}` | [Composed](https://cua.ai/docs/agent-sdk/supported-agents/composed-agents) with VLM for captioning and grounding LLM for element detection |
215 | | `moondream3+{any-llm-with-tools}` | [Composed](https://cua.ai/docs/agent-sdk/supported-agents/composed-agents) with Moondream3 for captioning and UI element detection |
216 | | `human/human` | A [human-in-the-loop](https://cua.ai/docs/agent-sdk/supported-agents/human-in-the-loop) in place of a model |
217 |
218 | ### Model Capabilities
219 |
220 | The following table shows which capabilities are supported by each model:
221 |
222 | | Model | Computer-Use | Grounding | Tools | VLM | Cloud |
223 | | -------------------------------------------------------------------------------------------------------------------------------- | :----------: | :-------: | :---: | :-: | :---: |
224 | | [Claude Sonnet/Haiku](https://docs.claude.com/en/docs/agents-and-tools/tool-use/computer-use-tool#how-to-implement-computer-use) | 🖥️ | 🎯 | 🛠️ | 👁️ | ☁️ |
225 | | [Claude Opus](https://docs.claude.com/en/docs/agents-and-tools/tool-use/computer-use-tool#how-to-implement-computer-use) | 🖥️ | 🎯 | 🛠️ | 👁️ | ☁️ |
226 | | [OpenAI CU Preview](https://platform.openai.com/docs/models/computer-use-preview) | 🖥️ | 🎯 | | 👁️ | |
227 | | [Qwen3 VL](https://huggingface.co/collections/Qwen/qwen3-vl) | 🖥️ | 🎯 | 🛠️ | 👁️ | ☁️ |
228 | | [GLM-V](https://huggingface.co/THUDM/glm-4v-9b) | 🖥️ | 🎯 | 🛠️ | 👁️ | |
229 | | [Gemini CU Preview](https://ai.google.dev/gemini-api/docs/computer-use) | 🖥️ | 🎯 | | 👁️ | |
230 | | [InternVL](https://huggingface.co/OpenGVLab/InternVL3_5-1B) | 🖥️ | 🎯 | 🛠️ | 👁️ | |
231 | | [UI-TARS](https://huggingface.co/ByteDance-Seed/UI-TARS-1.5-7B) | 🖥️ | 🎯 | 🛠️ | 👁️ | |
232 | | [UI-TARS-2](https://cua.ai/dashboard/vlm-router) | 🖥️ | 🎯 | 🛠️ | 👁️ | ☁️ |
233 | | [OpenCUA](https://huggingface.co/xlangai/OpenCUA-7B) | | 🎯 | | | |
234 | | [GTA](https://huggingface.co/HelloKKMe/GTA1-7B) | | 🎯 | | | |
235 | | [Holo](https://huggingface.co/Hcompany/Holo1.5-3B) | | 🎯 | | | |
236 | | [Moondream](https://huggingface.co/moondream/moondream3-preview) | | 🎯 | | | |
237 | | [OmniParser](https://github.com/microsoft/OmniParser) | | 🎯 | | | |
238 |
239 | **Legend:**
240 |
241 | - 🖥️ **Computer-Use**: Full agentic loop with planning and execution
242 | - 🎯 **Grounding**: UI element detection and click coordinate prediction
243 | - 🛠️ **Tools**: Support for function calling beyond screen interaction
244 | - 👁️ **VLM**: Vision-language understanding
245 | - ☁️ **Cloud**: Supported on Cua VLM
246 |
247 | **Composition Examples:**
248 |
249 | See more examples on our [composition docs](https://cua.ai/docs/agent-sdk/supported-agents/composed-agents).
250 |
251 | ```python
252 | # Use OpenAI's GPT-5 for planning with specialized grounding
253 | agent = ComputerAgent(model="huggingface-local/HelloKKMe/GTA1-7B+openai/gpt-5")
254 |
255 | # Composition via OmniParser
256 | agent = ComputerAgent(model="omniparser+openai/gpt-4o")
257 |
258 | # Combine state-of-the-art grounding with powerful reasoning
259 | agent = ComputerAgent(model="huggingface-local/HelloKKMe/GTA1-7B+anthropic/claude-sonnet-4-5-20250929")
260 |
261 | # Combine two different vision models for enhanced capabilities
262 | agent = ComputerAgent(model="huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B+openai/gpt-4o")
263 |
264 | # Use the built-in Moondream3 grounding with any planning mode.
265 | agent = ComputerAgent(model="moondream3+openai/gpt-4o")
266 | ```
267 |
268 | ### Model IDs
269 |
270 | <details>
271 | <summary>Examples of valid model IDs</summary>
272 |
273 | | Model | Model IDs |
274 | | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
275 | | [Claude Sonnet/Haiku](https://docs.claude.com/en/docs/agents-and-tools/tool-use/computer-use-tool#how-to-implement-computer-use) | `anthropic/claude-sonnet-4-5`, `anthropic/claude-haiku-4-5` |
276 | | [OpenAI CU Preview](https://platform.openai.com/docs/models/computer-use-preview) | `openai/computer-use-preview` |
277 | | [GLM-V](https://huggingface.co/THUDM/glm-4v-9b) | `openrouter/z-ai/glm-4.5v`, `huggingface-local/zai-org/GLM-4.5V` |
278 | | [Qwen3 VL](https://huggingface.co/collections/Qwen/qwen3-vl) | `openrouter/qwen/qwen3-vl-235b-a22b-instruct` |
279 | | [Gemini CU Preview](https://ai.google.dev/gemini-api/docs/computer-use) | `gemini-2.5-computer-use-preview` |
280 | | [InternVL](https://huggingface.co/OpenGVLab/InternVL3_5-1B) | `huggingface-local/OpenGVLab/InternVL3_5-{1B,2B,4B,8B,...}` |
281 | | [UI-TARS](https://huggingface.co/ByteDance-Seed/UI-TARS-1.5-7B) | `huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B` |
282 | | [UI-TARS-2](https://cua.ai/dashboard/vlm-router) | `cua/bytedance/ui-tars-2` |
283 | | [OpenCUA](https://huggingface.co/xlangai/OpenCUA-7B) | `huggingface-local/xlangai/OpenCUA-{7B,32B}` |
284 | | [GTA](https://huggingface.co/HelloKKMe/GTA1-7B) | `huggingface-local/HelloKKMe/GTA1-{7B,32B,72B}` |
285 | | [Holo](https://huggingface.co/Hcompany/Holo1.5-3B) | `huggingface-local/Hcompany/Holo1.5-{3B,7B,72B}` |
286 | | [Moondream](https://huggingface.co/moondream/moondream3-preview) | `moondream3` |
287 | | [OmniParser](https://github.com/microsoft/OmniParser) | `omniparser` |
288 |
289 | </details>
290 |
291 | Missing a model? Create a [feature request](https://github.com/trycua/cua/issues/new?assignees=&labels=enhancement&projects=&title=%5BAgent%5D%3A+Add+model+support+for+) or [contribute](https://github.com/trycua/cua/blob/main/CONTRIBUTING.md)!
292 |
293 | Learn more in the [Agent SDK documentation](./libs/python/agent/README.md).
294 |
295 | # Computer SDK
296 |
297 | Install the computer SDK:
298 |
299 | ```bash
300 | pip install cua-computer
301 | ```
302 |
303 | Initialize a computer:
304 |
305 | ```python
306 | from computer import Computer
307 |
308 | computer = Computer(
309 | os_type="linux", # or "macos", "windows"
310 | provider_type="cloud", # or "lume", "docker", "windows_sandbox"
311 | name="your-sandbox-name",
312 | api_key="your-api-key" # only for cloud
313 | # or use_host_computer_server=True for host desktop
314 | )
315 |
316 | try:
317 | await computer.run()
318 |
319 | # Take a screenshot
320 | screenshot = await computer.interface.screenshot()
321 |
322 | # Click and type
323 | await computer.interface.left_click(100, 100)
324 | await computer.interface.type_text("Hello!")
325 | finally:
326 | await computer.close()
327 | ```
328 |
329 | Learn more in the [Computer SDK documentation](./libs/python/computer/README.md).
330 |
331 | # MCP Server
332 |
333 | Install the MCP server:
334 |
335 | ```bash
336 | pip install cua-mcp-server
337 | ```
338 |
339 | Learn more in the [MCP Server documentation](./libs/python/mcp-server/README.md).
340 |
341 | # Computer Server
342 |
343 | Install the Computer Server:
344 |
345 | ```bash
346 | pip install cua-computer-server
347 | python -m computer_server
348 | ```
349 |
350 | Learn more in the [Computer Server documentation](./libs/python/computer-server/README.md).
351 |
352 | # Lume
353 |
354 | Install Lume:
355 |
356 | ```bash
357 | curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh | bash
358 | ```
359 |
360 | Learn more in the [Lume documentation](./libs/lume/README.md).
361 |
362 | # Lumier
363 |
364 | Install Lumier:
365 |
366 | ```bash
367 | docker pull trycua/lumier:latest
368 | ```
369 |
370 | Learn more in the [Lumier documentation](./libs/lumier/README.md).
371 |
372 | # SOM
373 |
374 | Install SOM:
375 |
376 | ```bash
377 | pip install cua-som
378 | ```
379 |
380 | Learn more in the [SOM documentation](./libs/python/som/README.md).
381 |
382 | # Recent Updates
383 |
384 | ## 2025
385 |
386 | ### December 2025
387 |
388 | - **Cloud VLM Platform**: Support for Claude Opus, Qwen3 VL 235B, and UI-TARS-2 on Cua VLM cloud infrastructure
389 | - **QEMU Container Support**: Native Linux and Windows container execution via QEMU virtualization
390 |
391 | ### November 2025
392 |
393 | - **Generic VLM Provider**: Expanded support for custom VLM providers and model configurations
394 | - **NeurIPS 2025**: Coverage of computer-use agent research papers and developments ([Blog Post](https://cua.ai/blog/neurips-2025-cua-papers))
395 |
396 | ### October 2025
397 |
398 | - **Agent SDK Improvements**: Enhanced model support and configuration options
399 |
400 | ### September 2025
401 |
402 | - **Hack the North Competition**: First benchmark-driven hackathon track with guaranteed YC interview prize. Winner achieved 68.3% on OSWorld-Tiny ([Blog Post](https://www.cua.ai/blog/hack-the-north))
403 | - **Global Hackathon Launch**: Ollama × Cua global online competition for creative local/hybrid agents
404 |
405 | ### August 2025
406 |
407 | - **v0.4 Release - Composite Agents**: Mix grounding + planning models with `+` operator (e.g., `"GTA-7B+GPT-4o"`) ([Blog Post](https://www.cua.ai/blog/composite-agents))
408 | - **HUD Integration**: One-line benchmarking on OSWorld-Verified with live trace visualization ([Blog Post](https://www.cua.ai/blog/hud-agent-evals))
409 | - **Human-in-the-Loop**: Interactive agent mode with `human/human` model string
410 | - **Web-Based Computer Use**: Browser-based agent execution ([Blog Post](https://www.cua.ai/blog/bringing-computer-use-to-the-web))
411 |
412 | ### June 2025
413 |
414 | - **Windows Sandbox Support**: Native Windows agent execution ([Blog Post](https://www.cua.ai/blog/windows-sandbox))
415 | - **Containerization Evolution**: From Lume to full Docker support ([Blog Post](https://www.cua.ai/blog/lume-to-containerization))
416 | - **Sandboxed Python Execution**: Secure code execution in agent workflows
417 |
418 | ### May 2025
419 |
420 | - **Cua Cloud Containers**: Production-ready cloud deployment with elastic scaling ([Blog Post](https://www.cua.ai/blog/introducing-cua-cloud-containers))
421 | - **Trajectory Viewer**: Visual debugging tool for agent actions ([Blog Post](https://www.cua.ai/blog/trajectory-viewer))
422 | - **Training Data Collection**: Tools for creating computer-use training datasets ([Blog Post](https://www.cua.ai/blog/training-computer-use-models-trajectories-1))
423 | - **App-Use Framework**: Mobile and desktop app automation capabilities
424 |
425 | ### April 2025
426 |
427 | - **Agent Framework v0.4**: Unified API for 100+ model configurations
428 | - **UI-TARS Integration**: Local inference support for ByteDance's desktop-optimized model
429 | - **Blog Series**: "Build Your Own Operator" tutorials ([Part 1](https://www.cua.ai/blog/build-your-own-operator-on-macos-1) | [Part 2](https://www.cua.ai/blog/build-your-own-operator-on-macos-2))
430 |
431 | ### March 2025
432 |
433 | - **Initial Public Release**: Core Agent SDK and Computer SDK
434 | - **Lume VM Manager**: macOS VM management tool for local development
435 |
436 | # Resources
437 |
438 | - [Cua Blog](https://www.cua.ai/blog)
439 | - [Cua Docs](https://cua.ai/docs)
440 |
441 | # Community and Contributions
442 |
443 | We welcome contributions to Cua! Please refer to our [Contributing Guidelines](CONTRIBUTING.md) for details.
444 |
445 | Join our [Discord community](https://discord.com/invite/mVnXXpdE85) to discuss ideas, get assistance, or share your demos!
446 |
447 | # License
448 |
449 | Cua is open-sourced under the MIT License - see the [LICENSE](LICENSE.md) file for details.
450 |
451 | Portions of this project, specifically components adapted from Kasm Technologies Inc., are also licensed under the MIT License. See [libs/kasm/LICENSE](libs/kasm/LICENSE) for details.
452 |
453 | Microsoft's OmniParser, which is used in this project, is licensed under the Creative Commons Attribution 4.0 International License (CC-BY-4.0). See the [OmniParser LICENSE](https://github.com/microsoft/OmniParser/blob/master/LICENSE) for details.
454 |
455 | ## Third-Party Licenses and Optional Components
456 |
457 | Some optional extras for this project depend on third-party packages that are licensed under terms different from the MIT License.
458 |
459 | - The optional "omni" extra (installed via `pip install "cua-agent[omni]"`) installs the `cua-som` module, which includes `ultralytics` and is licensed under the AGPL-3.0.
460 |
461 | When you choose to install and use such optional extras, your use, modification, and distribution of those third-party components are governed by their respective licenses (e.g., AGPL-3.0 for `ultralytics`).
462 |
463 | ## Trademarks
464 |
465 | Apple, macOS, and Apple Silicon are trademarks of Apple Inc.
466 | Ubuntu and Canonical are registered trademarks of Canonical Ltd.
467 | Microsoft is a registered trademark of Microsoft Corporation.
468 |
469 | This project is not affiliated with, endorsed by, or sponsored by Apple Inc., Canonical Ltd., Microsoft Corporation, or Kasm Technologies.
470 |
471 | # Stargazers
472 |
473 | Thank you to all our supporters!
474 |
475 | [](https://starchart.cc/trycua/cua)
476 |
477 | # Sponsors
478 |
479 | Thank you to all our [GitHub Sponsors](https://github.com/sponsors/trycua)!
480 |
481 | <img width="300" alt="coderabbit-cli" src="https://github.com/user-attachments/assets/23a98e38-7897-4043-8ef7-eb990520dccc" />
482 |
```
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
```markdown
1 | MIT License
2 |
3 | Copyright (c) 2025 Cua AI, Inc.
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
```
--------------------------------------------------------------------------------
/libs/lume/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
1 | # Contributing to lume
2 |
3 | We deeply appreciate your interest in contributing to lume! Whether you're reporting bugs, suggesting enhancements, improving docs, or submitting pull requests, your contributions help improve the project for everyone.
4 |
5 | ## Reporting Bugs
6 |
7 | If you've encountered a bug in the project, we encourage you to report it. Please follow these steps:
8 |
9 | 1. **Check the Issue Tracker**: Before submitting a new bug report, please check our issue tracker to see if the bug has already been reported.
10 | 2. **Create a New Issue**: If the bug hasn't been reported, create a new issue with:
11 | - A clear title and detailed description
12 | - Steps to reproduce the issue
13 | - Expected vs actual behavior
14 | - Your environment (macOS version, lume version)
15 | - Any relevant logs or error messages
16 | 3. **Label Your Issue**: Label your issue as a `bug` to help maintainers identify it quickly.
17 |
18 | ## Suggesting Enhancements
19 |
20 | We're always looking for suggestions to make lume better. If you have an idea:
21 |
22 | 1. **Check Existing Issues**: See if someone else has already suggested something similar.
23 | 2. **Create a New Issue**: If your enhancement is new, create an issue describing:
24 | - The problem your enhancement solves
25 | - How your enhancement would work
26 | - Any potential implementation details
27 | - Why this enhancement would benefit lume users
28 |
29 | ## Documentation
30 |
31 | Documentation improvements are always welcome. You can:
32 |
33 | - Fix typos or unclear explanations
34 | - Add examples and use cases
35 | - Improve API documentation
36 | - Add tutorials or guides
37 |
38 | For detailed instructions on setting up your development environment and submitting code contributions, please see our [Development.md](docs/Development.md) guide.
39 |
40 | Feel free to join our [Discord community](https://discord.com/invite/mVnXXpdE85) to discuss ideas or get help with your contributions.
41 |
```