mirror of
https://github.com/trycua/computer.git
synced 2026-02-14 01:29:22 -06:00
feat: auto-generated SDK docs, Python CLI, and docs improvements (#1040)
* feat: auto-generated SDK docs, Python CLI, and docs improvements
- Add auto-generated SDK reference pages (computer-sdk, agent-sdk) with version selector
- Add Python CLI package (cua-cli) with auth, sandbox, image, MCP commands
- Deprecate TypeScript CLI in favor of Python CLI
- Add versioned docs (agent-sdk v0.3-v0.7, computer-sdk v0.3-v0.5)
- Rename cloud-cli to cli in docs
- Add mobile header fix with sidebar toggle
- Restructure guide pages (quickstart, self-hosted-sandboxes)
- Add redirects for old /api URLs
- Update workflows, lume docs, cuabench docs, desktop sandbox docs
* refactor: auto-generate CLI index page like computer/agent SDKs
Change CLI docs to use the same auto-generated index.mdx pattern as
computer-sdk and agent-sdk. Removes hand-written index page that could
become stale, and deletes the separate api.mdx.
* fix: rename "Cua Bench API Reference" to "API Reference" in menu
* fix: update lume examples to macos-tahoe-vanilla and shorten page titles
- Replace macos-sequoia-vanilla:latest with macos-tahoe-vanilla:latest
in lume docs and generator
- Rename "Lume CLI Reference" to "CLI Reference"
- Rename "Lume HTTP API Reference" to "API Reference"
* feat: rename CuaBot to Cua-Bot and add to dropdown selector
- Rename CuaBot to Cua-Bot in docs meta.json and content pages
- Add Cua-Bot entry to the header dropdown selector
* refactor: restructure Cua-Bot docs to match Cua/Cua-Bench pattern
Reorganize cuabot docs from flat structure into guide/getting-started/
hierarchy matching other collections:
- cuabot.mdx → guide/getting-started/introduction.mdx
- install.mdx → guide/getting-started/installation.mdx
- Add meta.json files with proper icons and structure
- Update dropdown selector href to new path
* feat(docs): add auto-generated API reference, changelog, and versioning for Cua-Bot
Add TypeScript SDK doc generator (regex-based, no compiler dependency) and
configure cuabot for changelog generation and versioned docs snapshots.
* feat(ci): add cuabot to docs drift check and improve failure message
Wire cuabot into CI path triggers, runner config, and changed-file
detection. Add --check mode to typescript-sdk.ts for drift comparison.
Update failure banner with per-library and versioning commands.
* fix: resolve Python lint issues (black, ruff)
Run black formatting on 12 files, fix ruff F841 (unused variables) in
tests, and add TYPE_CHECKING import for FastMCP forward references.
* fix: resolve TS typecheck and Lume Swift 6 CI failures
- typescript-typecheck.js: build @trycua/core before running typecheck
so its dist/ type declarations are available for @trycua/computer
- SSHClient.swift: avoid crossing Sendable boundary with NIOSSHHandler
by keeping handler access + createChannel within flatMap on the event
loop, fixing Swift 6 strict concurrency errors
* fix: TS typecheck pnpm version strict mode and Lume mock conformance
- Set COREPACK_ENABLE_STRICT=0 in typecheck script to allow pnpm 9.x
to run commands in workspace packages declaring pnpm 10.x
- Update MockVNCService.sendText signature to match protocol (add
delayMs parameter)
* fix: run prettier formatting and ignore auto-generated docs files
Format all files to pass prettier 3.8.1 check. Add docs/.source/ and
docs/next-env.d.ts to .prettierignore (auto-generated, not editable).
* fix: restore MDX comment syntax broken by prettier
Prettier 3.8.1 converts {/* */} to {/_ _/} in MDX files, which breaks
the acorn parser. Restore all comments and add *.mdx to .prettierignore.
* fix: regenerate docs to pass drift check after prettier revert
* fix: CI docs check fetch-depth, regenerate Lume docs, fix header layout shift
- Use fetch-depth: 0 in CI checkout so git tags are available for
version discovery (was using fetch-depth: 2, causing version fallback)
- Regenerate Lume docs from local Swift build (0.2.75 → 0.2.76)
- Fix header product selector layout shift with consistent icon/text sizing
* fix: format custom-header.tsx with prettier
* fix: use arch-agnostic JAVA_HOME for arm64 Docker build
The openjdk package writes the arch-specific path (e.g. java-17-openjdk-amd64)
to /etc/environment, which sdkmanager sources, overriding the Dockerfile ENV.
Create an arch-agnostic symlink and re-export JAVA_HOME in the sdkmanager RUN
step to ensure it works on both amd64 and arm64.
* fix: skip emulator package on arm64 (not available for that arch)
The Android emulator SDK package is only published for amd64.
Conditionally install it based on dpkg --print-architecture.
* ci: retrigger cuabot docker build
This commit is contained in:
Francesco Bonacci
committed by
GitHub
GitHub
parent
229d5e5103
commit
174ae253ba
21
.github/workflows/cd-py-agent.yml
vendored
21
.github/workflows/cd-py-agent.yml
vendored
@@ -181,23 +181,4 @@ jobs:
|
||||
release_name: "cua-agent v${{ needs.prepare.outputs.version }}"
|
||||
module_path: "libs/python/agent"
|
||||
body: |
|
||||
## Dependencies
|
||||
* cua-computer: ${{ needs.prepare.outputs.computer_version }}
|
||||
* cua-som: ${{ needs.prepare.outputs.som_version }}
|
||||
|
||||
## Installation Options
|
||||
|
||||
### Basic installation with Anthropic
|
||||
```bash
|
||||
pip install cua-agent[anthropic]==${{ needs.prepare.outputs.version }}
|
||||
```
|
||||
|
||||
### With SOM (recommended)
|
||||
```bash
|
||||
pip install cua-agent[som]==${{ needs.prepare.outputs.version }}
|
||||
```
|
||||
|
||||
### All features
|
||||
```bash
|
||||
pip install cua-agent[all]==${{ needs.prepare.outputs.version }}
|
||||
```
|
||||
**Dependencies:** cua-computer ${{ needs.prepare.outputs.computer_version }}, cua-som ${{ needs.prepare.outputs.som_version }}
|
||||
|
||||
9
.github/workflows/cd-py-bench-ui.yml
vendored
9
.github/workflows/cd-py-bench-ui.yml
vendored
@@ -70,11 +70,4 @@ jobs:
|
||||
with:
|
||||
tag_name: "bench-ui-v${{ needs.prepare.outputs.version }}"
|
||||
release_name: "cua-bench-ui v${{ needs.prepare.outputs.version }}"
|
||||
body: |
|
||||
## Lightweight webUI window controller for Cua bench
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install cua-bench-ui==${{ needs.prepare.outputs.version }}
|
||||
```
|
||||
body: ""
|
||||
|
||||
9
.github/workflows/cd-py-bench.yml
vendored
9
.github/workflows/cd-py-bench.yml
vendored
@@ -70,11 +70,4 @@ jobs:
|
||||
with:
|
||||
tag_name: "bench-v${{ needs.prepare.outputs.version }}"
|
||||
release_name: "cua-bench v${{ needs.prepare.outputs.version }}"
|
||||
body: |
|
||||
## Toolkit for computer-use RL environments and benchmarks
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install cua-bench==${{ needs.prepare.outputs.version }}
|
||||
```
|
||||
body: ""
|
||||
|
||||
74
.github/workflows/cd-py-cli.yml
vendored
Normal file
74
.github/workflows/cd-py-cli.yml
vendored
Normal file
@@ -0,0 +1,74 @@
|
||||
name: "CD: cua-cli (PyPI)"
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "cli-v*"
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: "Version to publish (without v prefix)"
|
||||
required: true
|
||||
default: "0.1.0"
|
||||
workflow_call:
|
||||
inputs:
|
||||
version:
|
||||
description: "Version to publish"
|
||||
required: true
|
||||
type: string
|
||||
|
||||
# Adding permissions at workflow level
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
prepare:
|
||||
runs-on: macos-latest
|
||||
outputs:
|
||||
version: ${{ steps.get-version.outputs.version }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Determine version
|
||||
id: get-version
|
||||
run: |
|
||||
# Check inputs.version first (set by workflow_call)
|
||||
if [ -n "${{ inputs.version }}" ]; then
|
||||
VERSION=${{ inputs.version }}
|
||||
elif [ "${{ github.event_name }}" == "push" ]; then
|
||||
# Extract version from tag (for package-specific tags)
|
||||
if [[ "${{ github.ref }}" =~ ^refs/tags/cli-v([0-9]+\.[0-9]+\.[0-9]+) ]]; then
|
||||
VERSION=${BASH_REMATCH[1]}
|
||||
else
|
||||
echo "Invalid tag format for cli"
|
||||
exit 1
|
||||
fi
|
||||
elif [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
|
||||
# Use version from workflow dispatch
|
||||
VERSION=${{ github.event.inputs.version }}
|
||||
else
|
||||
echo "No version provided"
|
||||
exit 1
|
||||
fi
|
||||
echo "VERSION=$VERSION"
|
||||
echo "version=$VERSION" >> $GITHUB_OUTPUT
|
||||
|
||||
publish:
|
||||
needs: prepare
|
||||
uses: ./.github/workflows/py-reusable-publish.yml
|
||||
with:
|
||||
package_name: "cli"
|
||||
package_dir: "libs/python/cua-cli"
|
||||
version: ${{ needs.prepare.outputs.version }}
|
||||
base_package_name: "cua-cli"
|
||||
secrets:
|
||||
PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
|
||||
|
||||
create-release:
|
||||
needs: [prepare, publish]
|
||||
uses: ./.github/workflows/release-github-reusable.yml
|
||||
with:
|
||||
tag_name: "cli-v${{ needs.prepare.outputs.version }}"
|
||||
release_name: "cua-cli v${{ needs.prepare.outputs.version }}"
|
||||
module_path: "libs/python/cua-cli"
|
||||
body: ""
|
||||
18
.github/workflows/cd-py-computer-server.yml
vendored
18
.github/workflows/cd-py-computer-server.yml
vendored
@@ -88,20 +88,4 @@ jobs:
|
||||
tag_name: "computer-server-v${{ needs.prepare.outputs.version }}"
|
||||
release_name: "cua-computer-server v${{ needs.prepare.outputs.version }}"
|
||||
module_path: "libs/python/computer-server"
|
||||
body: |
|
||||
## Computer Server for the Computer Universal Automation (Cua) project
|
||||
|
||||
A FastAPI-based server implementation for computer control.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install cua-computer-server==${{ needs.prepare.outputs.version }}
|
||||
```
|
||||
body: ""
|
||||
|
||||
9
.github/workflows/cd-py-computer.yml
vendored
9
.github/workflows/cd-py-computer.yml
vendored
@@ -163,11 +163,4 @@ jobs:
|
||||
tag_name: "computer-v${{ needs.prepare.outputs.version }}"
|
||||
release_name: "cua-computer v${{ needs.prepare.outputs.version }}"
|
||||
module_path: "libs/python/computer"
|
||||
body: |
|
||||
## Computer control library for the Computer Universal Automation (Cua) project
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install cua-computer==${{ needs.prepare.outputs.version }}
|
||||
```
|
||||
body: ""
|
||||
|
||||
9
.github/workflows/cd-py-core.yml
vendored
9
.github/workflows/cd-py-core.yml
vendored
@@ -71,11 +71,4 @@ jobs:
|
||||
tag_name: "core-v${{ needs.prepare.outputs.version }}"
|
||||
release_name: "cua-core v${{ needs.prepare.outputs.version }}"
|
||||
module_path: "libs/python/core"
|
||||
body: |
|
||||
## Base package for Cua project with telemetry and core utilities
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install cua-core==${{ needs.prepare.outputs.version }}
|
||||
```
|
||||
body: ""
|
||||
|
||||
38
.github/workflows/cd-py-mcp-server.yml
vendored
38
.github/workflows/cd-py-mcp-server.yml
vendored
@@ -165,40 +165,4 @@ jobs:
|
||||
tag_name: "mcp-server-v${{ needs.prepare.outputs.version }}"
|
||||
release_name: "cua-mcp-server v${{ needs.prepare.outputs.version }}"
|
||||
module_path: "libs/python/mcp-server"
|
||||
body: |
|
||||
## MCP Server for the Computer-Use Agent (Cua)
|
||||
|
||||
This package provides MCP (Model Context Protocol) integration for Cua agents, allowing them to be used with Claude Desktop, Cursor, and other MCP clients.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Run the MCP server directly
|
||||
cua-mcp-server
|
||||
```
|
||||
|
||||
## Claude Desktop Integration
|
||||
|
||||
Add to your Claude Desktop configuration (~/.config/claude-desktop/claude_desktop_config.json or OS-specific location):
|
||||
|
||||
```json
|
||||
"mcpServers": {
|
||||
"cua-agent": {
|
||||
"command": "cua-mcp-server",
|
||||
"args": [],
|
||||
"env": {
|
||||
"CUA_AGENT_LOOP": "OMNI",
|
||||
"CUA_MODEL_PROVIDER": "ANTHROPIC",
|
||||
"CUA_MODEL_NAME": "claude-3-opus-20240229",
|
||||
"ANTHROPIC_API_KEY": "your-api-key",
|
||||
"PYTHONIOENCODING": "utf-8"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install cua-mcp-server==${{ needs.prepare.outputs.version }}
|
||||
```
|
||||
body: ""
|
||||
|
||||
11
.github/workflows/cd-py-som.yml
vendored
11
.github/workflows/cd-py-som.yml
vendored
@@ -75,13 +75,4 @@ jobs:
|
||||
tag_name: "som-v${{ needs.determine-version.outputs.version }}"
|
||||
release_name: "cua-som v${{ needs.determine-version.outputs.version }}"
|
||||
module_path: "libs/python/som"
|
||||
body: |
|
||||
## Computer Vision and OCR library for detecting and analyzing UI elements
|
||||
|
||||
This package provides enhanced UI understanding capabilities through computer vision and OCR.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install cua-som==${{ needs.determine-version.outputs.version }}
|
||||
```
|
||||
body: ""
|
||||
|
||||
4
.github/workflows/cd-swift-lume.yml
vendored
4
.github/workflows/cd-swift-lume.yml
vendored
@@ -53,9 +53,9 @@ jobs:
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Select Xcode 16.2
|
||||
- name: Select Xcode 16
|
||||
run: |
|
||||
sudo xcode-select -s /Applications/Xcode_16.2.app
|
||||
sudo xcode-select -s /Applications/Xcode_16.app
|
||||
xcodebuild -version
|
||||
|
||||
- name: Install dependencies
|
||||
|
||||
70
.github/workflows/ci-check-docs.yml
vendored
70
.github/workflows/ci-check-docs.yml
vendored
@@ -10,13 +10,16 @@ on:
|
||||
# MCP Server (Python)
|
||||
- "libs/python/mcp-server/src/**"
|
||||
# Computer SDK
|
||||
- "libs/python/computer/src/**"
|
||||
- "libs/python/computer/computer/**"
|
||||
- "libs/typescript/computer/src/**"
|
||||
# Agent SDK
|
||||
- "libs/python/agent/src/**"
|
||||
- "libs/python/agent/agent/**"
|
||||
- "libs/typescript/agent/src/**"
|
||||
# Cua-Bot
|
||||
- "libs/cuabot/src/**"
|
||||
# Documentation files themselves
|
||||
- "docs/content/docs/cua/reference/**"
|
||||
- "docs/content/docs/cuabot/reference/**"
|
||||
# Generator scripts
|
||||
- "scripts/docs-generators/**"
|
||||
|
||||
@@ -28,7 +31,7 @@ jobs:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 2 # Need history for changed file detection
|
||||
fetch-depth: 0 # Need full history for git tags (version discovery) and changed file detection
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
@@ -42,6 +45,14 @@ jobs:
|
||||
run: pnpm install
|
||||
working-directory: docs
|
||||
|
||||
- name: Setup Python
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.11"
|
||||
|
||||
- name: Install Python doc dependencies
|
||||
run: pip install -r scripts/docs-generators/requirements.txt
|
||||
|
||||
- name: Determine changed generators
|
||||
id: changed
|
||||
run: |
|
||||
@@ -68,14 +79,14 @@ jobs:
|
||||
GENERATORS="$GENERATORS mcp-server"
|
||||
fi
|
||||
|
||||
# Computer SDK changes
|
||||
if echo "$CHANGED_FILES" | grep -q "^libs/python/computer/src/\|^libs/typescript/computer/src/"; then
|
||||
GENERATORS="$GENERATORS computer-sdk"
|
||||
# Python SDK changes (Computer and Agent)
|
||||
if echo "$CHANGED_FILES" | grep -q "^libs/python/computer/computer/\|^libs/python/agent/agent/"; then
|
||||
GENERATORS="$GENERATORS python-sdk"
|
||||
fi
|
||||
|
||||
# Agent SDK changes
|
||||
if echo "$CHANGED_FILES" | grep -q "^libs/python/agent/src/\|^libs/typescript/agent/src/"; then
|
||||
GENERATORS="$GENERATORS agent-sdk"
|
||||
# Cua-Bot changes
|
||||
if echo "$CHANGED_FILES" | grep -q "^libs/cuabot/src/"; then
|
||||
GENERATORS="$GENERATORS cuabot"
|
||||
fi
|
||||
|
||||
# Generator changes should run all
|
||||
@@ -113,20 +124,27 @@ jobs:
|
||||
if: failure()
|
||||
run: |
|
||||
echo ""
|
||||
echo "╔══════════════════════════════════════════════════════════════════╗"
|
||||
echo "║ Documentation Out of Sync! ║"
|
||||
echo "╠══════════════════════════════════════════════════════════════════╣"
|
||||
echo "║ ║"
|
||||
echo "║ The documentation has drifted from the source code. ║"
|
||||
echo "║ ║"
|
||||
echo "║ To fix this, run from the repository root: ║"
|
||||
echo "║ ║"
|
||||
echo "║ npx tsx scripts/docs-generators/runner.ts ║"
|
||||
echo "║ ║"
|
||||
echo "║ Or for a specific library: ║"
|
||||
echo "║ ║"
|
||||
echo "║ npx tsx scripts/docs-generators/runner.ts --library lume ║"
|
||||
echo "║ ║"
|
||||
echo "║ Then commit the updated documentation files. ║"
|
||||
echo "║ ║"
|
||||
echo "╚══════════════════════════════════════════════════════════════════╝"
|
||||
echo "╔═══════════════════════════════════════════════════════════════════════╗"
|
||||
echo "║ Documentation Out of Sync! ║"
|
||||
echo "╠═══════════════════════════════════════════════════════════════════════╣"
|
||||
echo "║ ║"
|
||||
echo "║ The documentation has drifted from the source code. ║"
|
||||
echo "║ ║"
|
||||
echo "║ To regenerate all docs, run from the repository root: ║"
|
||||
echo "║ ║"
|
||||
echo "║ npx tsx scripts/docs-generators/runner.ts ║"
|
||||
echo "║ ║"
|
||||
echo "║ Or for a specific library: ║"
|
||||
echo "║ ║"
|
||||
echo "║ npx tsx scripts/docs-generators/runner.ts --library lume ║"
|
||||
echo "║ npx tsx scripts/docs-generators/runner.ts --library python-sdk ║"
|
||||
echo "║ npx tsx scripts/docs-generators/runner.ts --library cuabot ║"
|
||||
echo "║ ║"
|
||||
echo "║ For versioned docs and changelogs (after tagging a new release): ║"
|
||||
echo "║ ║"
|
||||
echo "║ npx tsx scripts/docs-generators/generate-versioned-docs.ts ║"
|
||||
echo "║ npx tsx scripts/docs-generators/generate-changelog.ts ║"
|
||||
echo "║ ║"
|
||||
echo "║ Then commit the updated documentation files. ║"
|
||||
echo "║ ║"
|
||||
echo "╚═══════════════════════════════════════════════════════════════════════╝"
|
||||
|
||||
4
.github/workflows/ci-swift-lume.yml
vendored
4
.github/workflows/ci-swift-lume.yml
vendored
@@ -18,7 +18,7 @@ jobs:
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: uname -a
|
||||
- run: sudo xcode-select -s /Applications/Xcode_16.2.app # Swift 6.2
|
||||
- run: sudo xcode-select -s /Applications/Xcode_16.app # Swift 6.0
|
||||
- run: swift test
|
||||
working-directory: ./libs/lume
|
||||
build:
|
||||
@@ -27,6 +27,6 @@ jobs:
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: uname -a
|
||||
- run: sudo xcode-select -s /Applications/Xcode_16.2.app # Swift 6.2
|
||||
- run: sudo xcode-select -s /Applications/Xcode_16.app # Swift 6.0
|
||||
- run: swift build --configuration release
|
||||
working-directory: ./libs/lume
|
||||
|
||||
12
.github/workflows/release-github-reusable.yml
vendored
12
.github/workflows/release-github-reusable.yml
vendored
@@ -83,6 +83,11 @@ jobs:
|
||||
|
||||
# Get commits and process each one to fetch GitHub username
|
||||
while IFS='|' read -r sha subject; do
|
||||
# Skip automated bump commits (e.g., "Bump cua-agent to v0.7.22")
|
||||
if [[ "$subject" =~ ^Bump\ cua- ]]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
# Try to get GitHub username via API
|
||||
USERNAME=$(gh api repos/${{ github.repository }}/commits/${sha} --jq '.author.login' 2>/dev/null || echo "")
|
||||
|
||||
@@ -98,12 +103,15 @@ jobs:
|
||||
fi
|
||||
fi
|
||||
|
||||
# Link PR numbers: (#123) -> ([#123](https://github.com/REPO/pull/123))
|
||||
LINKED_SUBJECT=$(echo "$subject" | sed 's/(#\([0-9]*\))/([#\1](https:\/\/github.com\/${{ github.repository }}\/pull\/\1))/g')
|
||||
|
||||
SHORT_SHA=$(echo ${sha} | cut -c1-7)
|
||||
NOTES="${NOTES}* ${subject} (${SHORT_SHA}) by @${USERNAME}"$'\n'
|
||||
NOTES="${NOTES}* ${LINKED_SUBJECT} (${SHORT_SHA}) by @${USERNAME}"$'\n'
|
||||
done < <(git log ${COMMIT_RANGE} --pretty=format:"%H|%s" -- "${{ inputs.module_path }}" | head -50)
|
||||
|
||||
if [ -z "$NOTES" ]; then
|
||||
NOTES="* Initial release or no path-specific changes found"
|
||||
NOTES="Maintenance release — dependency updates only."
|
||||
fi
|
||||
|
||||
# Store notes in output (handle multiline)
|
||||
|
||||
2
.github/workflows/ts-reusable-build.yml
vendored
2
.github/workflows/ts-reusable-build.yml
vendored
@@ -56,7 +56,7 @@ jobs:
|
||||
bun run build
|
||||
fi
|
||||
else
|
||||
pnpm run --if-present build
|
||||
pnpm run build --if-present
|
||||
fi
|
||||
|
||||
- name: Verify build
|
||||
|
||||
2
.github/workflows/ts-reusable-publish.yml
vendored
2
.github/workflows/ts-reusable-publish.yml
vendored
@@ -98,7 +98,7 @@ jobs:
|
||||
bun run build
|
||||
fi
|
||||
else
|
||||
pnpm run --if-present build
|
||||
pnpm run build --if-present
|
||||
fi
|
||||
|
||||
- name: Publish to npm
|
||||
|
||||
@@ -31,8 +31,12 @@ venv/
|
||||
pnpm-lock.yaml
|
||||
uv.lock
|
||||
|
||||
# Docs with complex JSX formatting
|
||||
docs/content/docs/get-started/quickstart.mdx
|
||||
# Auto-generated docs source
|
||||
docs/.source/
|
||||
docs/next-env.d.ts
|
||||
|
||||
# MDX files (prettier mangles {/* */} comment syntax into {/_ _/})
|
||||
*.mdx
|
||||
|
||||
# Git worktrees (separate branches)
|
||||
.worktrees/
|
||||
@@ -44,7 +44,7 @@ Built-in support for `agent-browser` and `agent-device` (iOS, Android) out of th
|
||||
|
||||
<div align="center">
|
||||
|
||||
**[Get Started](https://cua.ai/docs/cuabot/cuabot)** | **[Installation](https://cua.ai/docs/cuabot/install)** | *First spotted at [ClawCon](https://www.claw-con.com/)*
|
||||
**[Get Started](https://cua.ai/docs/cuabot/cuabot)** | **[Installation](https://cua.ai/docs/cuabot/install)** | _First spotted at [ClawCon](https://www.claw-con.com/)_
|
||||
|
||||
<div align="center">
|
||||
<img src="img/cuabot-screenshot.png" alt="cuabot screenshot" style="max-height: 32em;">
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
# Announcing the First Multi-Player Computer-Use — Live from ClawCon
|
||||
|
||||
_Published on February 6, 2026 by Francesco Bonacci and Dillon DuPont_
|
||||
|
||||
ClawCon brought over 700 attendees to Frontier Tower, with a waitlist that had people lining up down Market Street, and another 20k tuned into the livestream. It was the first community event for OpenClaw, and we had the 2nd demo session.
|
||||
@@ -54,8 +55,6 @@ ClawCon livestream demo
|
||||
</div>
|
||||
Multi-Player Computer Use Agent building an RL gym and coding and playing a desktop game simultaneously. Before today, you could only have 1 Computer-Use Agent deployed per system to control
|
||||
|
||||
|
||||
|
||||
## OpenClaw + CuaBot
|
||||
|
||||
We demoed this at ClawCon for a reason — CuaBot is designed to work with OpenClaw out of the box.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
_Published on Jan 28, 2026 by Francesco Bonacci. Originally posted on [X](https://x.com/francedot/status/2016627257310384554)._
|
||||
|
||||
***TLDR**: Since Clawdbot went viral, I've gotten a lot of questions: Where did this all come from? What's next? Here's my take.*
|
||||
**\*TLDR**: Since Clawdbot went viral, I've gotten a lot of questions: Where did this all come from? What's next? Here's my take.\*
|
||||
|
||||
Clawdbot just hit the mainstream. The open-source AI assistant — now rebranded to Moltbot after trademark issues — has captured the imagination of developers and mainstream users alike. An AI that runs on your own machine, controlled through WhatsApp, extensible through plugins. It feels like the future arriving all at once.
|
||||
|
||||
@@ -104,7 +104,7 @@ Nine days later, the open-source community responded. Browser-use ([@gregpr07](h
|
||||
|
||||
|
||||
|
||||
Then, on January 23, 2025, OpenAI entered with [Operator](https://openai.com/index/introducing-operator/), powered by their Computer-Using Agent (CUA) model.
|
||||
Then, on January 23, 2025, OpenAI entered with [Operator](https://openai.com/index/introducing-operator/), powered by their Computer-Using Agent (CUA) model.
|
||||
|
||||
|
||||
|
||||
@@ -188,6 +188,7 @@ Created by Austrian developer Peter Steinberger, [Clawdbot](https://github.com/c
|
||||
|
||||
|
||||
What makes it different:
|
||||
|
||||
- **Self-hosted**: Runs entirely on your machine. Your data stays local.
|
||||
- **Multi-model**: Works with Claude, GPT, or local models via Ollama.
|
||||
- **Extensible**: Skills and plugins from ClawdHub — a public registry where anyone can contribute capabilities.
|
||||
@@ -202,6 +203,7 @@ But the paradigm is clear: the future of computer-use agents is modular, and use
|
||||
## The Evolution in One Frame
|
||||
|
||||
Looking back, the progression follows a clear arc:
|
||||
|
||||
- 2023: "Can AI see a screen?" (GPT-4V)
|
||||
- 2024: "Can AI click buttons?" (Claude Computer Use, Operator)
|
||||
- 2025: "Can AI write code instead?" (CoAct-1)
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
{
|
||||
"title": "Claude Code",
|
||||
"description": "Claude Code integration examples",
|
||||
"icon": "Terminal",
|
||||
"pages": ["human-demonstrations"]
|
||||
}
|
||||
|
||||
@@ -61,7 +61,7 @@ cua skills read my-skill
|
||||
|
||||
### 1. Start a sandbox and open the VNC UI
|
||||
|
||||
Start a sandbox using [Docker](/docs/cua/guide/get-started/set-up-sandbox) or [Cua Cloud](/docs/cua/guide/get-started/set-up-sandbox). The VNC UI will be available at:
|
||||
Start a sandbox using [Docker](/docs/cua/guide/get-started/self-hosted-sandboxes) or [Cua Cloud](/docs/cua/guide/get-started/quickstart). The VNC UI will be available at:
|
||||
|
||||
- **Docker**: `http://localhost:8006`
|
||||
- **Cloud**: `https://{sandbox-name}.sandbox.cua.ai/vnc.html`
|
||||
|
||||
@@ -5,11 +5,9 @@
|
||||
"icon": "Rocket",
|
||||
"pages": [
|
||||
"what-is-cua",
|
||||
"what-is-computer-use-agent",
|
||||
"what-is-desktop-sandbox",
|
||||
"set-up-sandbox",
|
||||
"quickstart",
|
||||
"using-computer-sdk",
|
||||
"using-agent-sdk",
|
||||
"using-cloud-cli"
|
||||
"self-hosted-sandboxes"
|
||||
]
|
||||
}
|
||||
|
||||
184
docs/content/docs/cua/guide/get-started/quickstart.mdx
Normal file
184
docs/content/docs/cua/guide/get-started/quickstart.mdx
Normal file
@@ -0,0 +1,184 @@
|
||||
---
|
||||
title: Quickstart
|
||||
description: Get a computer-use agent running in 5 minutes
|
||||
---
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
|
||||
This guide gets you from zero to a working computer-use agent using Cua Cloud sandboxes.
|
||||
|
||||
<Callout type="info">
|
||||
**Prerequisites:** Python 3.12 or 3.13 and a free Cua account at [cua.ai](https://cua.ai/signin).
|
||||
</Callout>
|
||||
|
||||
## 1. Install the Cua CLI and SDKs
|
||||
|
||||
```bash
|
||||
pip install cua-cli cua-computer "cua-agent[all]"
|
||||
```
|
||||
|
||||
## 2. Authenticate
|
||||
|
||||
Login with your Cua account:
|
||||
|
||||
```bash
|
||||
cua auth login
|
||||
```
|
||||
|
||||
This opens your browser for authentication. Once complete, your API key is stored locally.
|
||||
|
||||
To export your API key to a `.env` file for use in scripts:
|
||||
|
||||
```bash
|
||||
cua auth env
|
||||
```
|
||||
|
||||
## 3. Create a Cloud Sandbox
|
||||
|
||||
Create a Linux sandbox:
|
||||
|
||||
```bash
|
||||
cua sandbox create --os linux --size small --region north-america
|
||||
```
|
||||
|
||||
Note the sandbox name from the output (e.g., `curious-fox-123`).
|
||||
|
||||
You can view all your sandboxes:
|
||||
|
||||
```bash
|
||||
cua sandbox list
|
||||
```
|
||||
|
||||
## 4. Take a Screenshot (Hello World)
|
||||
|
||||
Create a file `hello.py`:
|
||||
|
||||
```python
|
||||
import os
|
||||
import asyncio
|
||||
from computer import Computer
|
||||
|
||||
# Load API key from environment (or set directly)
|
||||
os.environ["CUA_API_KEY"] = "sk_cua-api01_..." # or use: cua auth env
|
||||
|
||||
computer = Computer(
|
||||
os_type="linux",
|
||||
provider_type="cloud",
|
||||
name="curious-fox-123" # your sandbox name
|
||||
)
|
||||
|
||||
async def main():
|
||||
await computer.run() # Connect to the sandbox
|
||||
|
||||
try:
|
||||
# Take a screenshot
|
||||
screenshot = await computer.interface.screenshot()
|
||||
screenshot.save("screenshot.png")
|
||||
print("Screenshot saved to screenshot.png")
|
||||
|
||||
# Click at coordinates (100, 100)
|
||||
await computer.interface.left_click(100, 100)
|
||||
|
||||
# Type some text
|
||||
await computer.interface.type_text("Hello from Cua!")
|
||||
finally:
|
||||
await computer.disconnect()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
Run it:
|
||||
|
||||
```bash
|
||||
python hello.py
|
||||
```
|
||||
|
||||
## 5. Run an Agent
|
||||
|
||||
Now let's add AI. Create `agent.py`:
|
||||
|
||||
```python
|
||||
import os
|
||||
import asyncio
|
||||
from computer import Computer
|
||||
from agent import ComputerAgent
|
||||
|
||||
os.environ["CUA_API_KEY"] = "sk_cua-api01_..." # or use: cua auth env
|
||||
|
||||
computer = Computer(
|
||||
os_type="linux",
|
||||
provider_type="cloud",
|
||||
name="curious-fox-123" # your sandbox name
|
||||
)
|
||||
|
||||
async def main():
|
||||
await computer.run()
|
||||
|
||||
try:
|
||||
agent = ComputerAgent(
|
||||
model="cua/anthropic/claude-sonnet-4.5",
|
||||
tools=[computer],
|
||||
)
|
||||
|
||||
messages = [{"role": "user", "content": "Open Firefox and go to google.com"}]
|
||||
|
||||
async for result in agent.run(messages):
|
||||
for item in result["output"]:
|
||||
if item["type"] == "message":
|
||||
print(item["content"][0]["text"])
|
||||
finally:
|
||||
await computer.disconnect()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
Run it:
|
||||
|
||||
```bash
|
||||
python agent.py
|
||||
```
|
||||
|
||||
The agent will observe the screen, decide what actions to take, and execute them to complete your task.
|
||||
|
||||
## 6. Open the Desktop in Your Browser
|
||||
|
||||
Watch your agent work in real-time:
|
||||
|
||||
```bash
|
||||
cua sandbox vnc curious-fox-123
|
||||
```
|
||||
|
||||
This opens a browser window showing the sandbox desktop.
|
||||
|
||||
## 7. Clean Up
|
||||
|
||||
When you're done, stop your sandbox to avoid charges:
|
||||
|
||||
```bash
|
||||
cua sandbox stop curious-fox-123
|
||||
```
|
||||
|
||||
Or delete it entirely:
|
||||
|
||||
```bash
|
||||
cua sandbox delete curious-fox-123
|
||||
```
|
||||
|
||||
## CLI Reference
|
||||
|
||||
| Command | Description |
|
||||
| -------------------------------------------------------------- | ---------------------------------- |
|
||||
| `cua auth login` | Authenticate with your Cua account |
|
||||
| `cua auth env` | Export API key to `.env` file |
|
||||
| `cua sandbox list` | List all sandboxes |
|
||||
| `cua sandbox create --os <os> --size <size> --region <region>` | Create a sandbox |
|
||||
| `cua sandbox vnc <name>` | Open sandbox in browser |
|
||||
| `cua sandbox start <name>` | Start a stopped sandbox |
|
||||
| `cua sandbox stop <name>` | Stop a sandbox |
|
||||
| `cua sandbox delete <name>` | Delete a sandbox |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Using the Computer SDK](/cua/guide/get-started/using-computer-sdk) - Learn low-level computer control
|
||||
- [Using the Agent SDK](/cua/guide/get-started/using-agent-sdk) - Advanced AI agent configuration
|
||||
- [Self-Hosted Sandboxes](/cua/guide/get-started/self-hosted-sandboxes) - Run sandboxes locally with Docker
|
||||
@@ -0,0 +1,308 @@
|
||||
---
|
||||
title: Self-Hosted Sandboxes
|
||||
description: Run sandboxes locally with Docker, QEMU, or native virtualization
|
||||
---
|
||||
|
||||
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
|
||||
For development, testing, or air-gapped environments, you can run sandboxes locally instead of using Cua Cloud.
|
||||
|
||||
## Options Overview
|
||||
|
||||
| Option | OS Support | Requirements | Best For |
|
||||
| ------------------- | ----------------------- | ----------------------------- | -------------------------------- |
|
||||
| **Docker** | Linux | Docker Desktop/Engine | Local development, fastest setup |
|
||||
| **QEMU Docker** | Linux, Windows, Android | Docker + golden image | Testing specific OS versions |
|
||||
| **Lume** | macOS | macOS host + Lume CLI | macOS automation |
|
||||
| **Windows Sandbox** | Windows | Windows 10 Pro/Enterprise, 11 | Windows automation |
|
||||
|
||||
## Linux on Docker (Recommended)
|
||||
|
||||
The fastest way to get a local sandbox running.
|
||||
|
||||
**1. Install Docker Desktop or Docker Engine**
|
||||
|
||||
**2. Pull a Cua Docker image:**
|
||||
|
||||
```bash
|
||||
# XFCE (Lightweight) - recommended for most use cases
|
||||
docker pull --platform=linux/amd64 trycua/cua-xfce:latest
|
||||
|
||||
# OR KASM (Full-Featured) - full Ubuntu desktop
|
||||
docker pull --platform=linux/amd64 trycua/cua-ubuntu:latest
|
||||
```
|
||||
|
||||
**3. Connect with Python:**
|
||||
|
||||
```python
|
||||
from computer import Computer
|
||||
import asyncio
|
||||
|
||||
computer = Computer(
|
||||
os_type="linux",
|
||||
provider_type="docker",
|
||||
image="trycua/cua-xfce:latest"
|
||||
)
|
||||
|
||||
async def main():
|
||||
await computer.run() # Launch & connect
|
||||
|
||||
try:
|
||||
screenshot = await computer.interface.screenshot()
|
||||
await computer.interface.left_click(100, 100)
|
||||
await computer.interface.type_text("Hello!")
|
||||
finally:
|
||||
await computer.disconnect()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## QEMU Docker
|
||||
|
||||
Run full virtual machines (Linux, Windows, Android) inside Docker containers using QEMU virtualization.
|
||||
|
||||
<Callout type="warn">
|
||||
Linux and Windows images require a **golden image preparation step** on first use. Android images
|
||||
start directly.
|
||||
</Callout>
|
||||
|
||||
<Tabs items={['Linux', 'Windows', 'Android']}>
|
||||
<Tab value="Linux">
|
||||
|
||||
**1. Pull the QEMU Linux image:**
|
||||
|
||||
```bash
|
||||
docker pull trycua/cua-qemu-linux:latest
|
||||
```
|
||||
|
||||
**2. Download Ubuntu 22.04 LTS Server ISO:**
|
||||
|
||||
Download the [Ubuntu 22.04 Server ISO](https://releases.ubuntu.com/22.04/ubuntu-22.04.5-live-server-amd64.iso) (~2GB)
|
||||
|
||||
**3. Create golden image:**
|
||||
|
||||
```bash
|
||||
docker run -it --rm \
|
||||
--device=/dev/kvm \
|
||||
--cap-add NET_ADMIN \
|
||||
--mount type=bind,source=/path/to/ubuntu-22.04.5-live-server-amd64.iso,target=/custom.iso \
|
||||
-v ~/cua-storage/linux:/storage \
|
||||
-p 8006:8006 \
|
||||
-p 5000:5000 \
|
||||
-e RAM_SIZE=8G \
|
||||
-e CPU_CORES=4 \
|
||||
-e DISK_SIZE=64G \
|
||||
trycua/cua-qemu-linux:latest
|
||||
```
|
||||
|
||||
Monitor progress at [http://localhost:8006](http://localhost:8006). The container will install Ubuntu Desktop and shut down when complete.
|
||||
|
||||
**4. Connect with Python:**
|
||||
|
||||
```python
|
||||
from computer import Computer
|
||||
import asyncio
|
||||
|
||||
computer = Computer(
|
||||
os_type="linux",
|
||||
provider_type="docker",
|
||||
image="trycua/cua-qemu-linux:latest",
|
||||
storage="~/cua-storage/linux",
|
||||
run_opts={"devices": ["/dev/kvm"]},
|
||||
)
|
||||
|
||||
async def main():
|
||||
await computer.run()
|
||||
|
||||
try:
|
||||
screenshot = await computer.interface.screenshot()
|
||||
await computer.interface.left_click(100, 100)
|
||||
finally:
|
||||
await computer.disconnect()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab value="Windows">
|
||||
|
||||
**1. Pull the QEMU Windows image:**
|
||||
|
||||
```bash
|
||||
docker pull trycua/cua-qemu-windows:latest
|
||||
```
|
||||
|
||||
**2. Download Windows 11 Enterprise Evaluation ISO:**
|
||||
|
||||
- Visit [Microsoft Evaluation Center](https://info.microsoft.com/ww-landing-windows-11-enterprise.html)
|
||||
- Download **Windows 11 Enterprise Evaluation (90-day trial)** ISO (~6GB)
|
||||
|
||||
**3. Create golden image:**
|
||||
|
||||
```bash
|
||||
docker run -it --rm \
|
||||
--device=/dev/kvm \
|
||||
--cap-add NET_ADMIN \
|
||||
--mount type=bind,source=/path/to/windows-11-enterprise-eval.iso,target=/custom.iso \
|
||||
-v ~/cua-storage/windows:/storage \
|
||||
-p 8006:8006 \
|
||||
-p 5000:5000 \
|
||||
-e RAM_SIZE=8G \
|
||||
-e CPU_CORES=4 \
|
||||
-e DISK_SIZE=64G \
|
||||
trycua/cua-qemu-windows:latest
|
||||
```
|
||||
|
||||
Monitor progress at [http://localhost:8006](http://localhost:8006). The container will install Windows 11 and shut down when complete.
|
||||
|
||||
**4. Connect with Python:**
|
||||
|
||||
```python
|
||||
from computer import Computer
|
||||
import asyncio
|
||||
|
||||
computer = Computer(
|
||||
os_type="windows",
|
||||
provider_type="docker",
|
||||
image="trycua/cua-qemu-windows:latest",
|
||||
storage="~/cua-storage/windows",
|
||||
run_opts={"devices": ["/dev/kvm"]},
|
||||
)
|
||||
|
||||
async def main():
|
||||
await computer.run()
|
||||
|
||||
try:
|
||||
screenshot = await computer.interface.screenshot()
|
||||
await computer.interface.left_click(100, 100)
|
||||
finally:
|
||||
await computer.disconnect()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab value="Android">
|
||||
|
||||
No golden image preparation needed.
|
||||
|
||||
**1. Pull the QEMU Android image:**
|
||||
|
||||
```bash
|
||||
docker pull trycua/cua-qemu-android:latest
|
||||
```
|
||||
|
||||
**2. Connect with Python:**
|
||||
|
||||
```python
|
||||
from computer import Computer
|
||||
import asyncio
|
||||
|
||||
computer = Computer(
|
||||
os_type="android",
|
||||
provider_type="docker",
|
||||
image="trycua/cua-qemu-android:latest",
|
||||
timeout=150, # Emulator needs more time to boot
|
||||
run_opts={
|
||||
"devices": ["/dev/kvm"],
|
||||
"env": {"EMULATOR_DEVICE": "Samsung Galaxy S10"},
|
||||
},
|
||||
)
|
||||
|
||||
async def main():
|
||||
await computer.run()
|
||||
|
||||
try:
|
||||
screenshot = await computer.interface.screenshot()
|
||||
await computer.interface.left_click(100, 100)
|
||||
finally:
|
||||
await computer.disconnect()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## macOS Sandbox (Lume)
|
||||
|
||||
Run native macOS VMs using Apple's Virtualization framework. **macOS host required.**
|
||||
|
||||
**1. Install the Lume CLI:**
|
||||
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
|
||||
```
|
||||
|
||||
**2. Start a macOS sandbox:**
|
||||
|
||||
```bash
|
||||
lume run macos-sequoia-cua:latest
|
||||
```
|
||||
|
||||
**3. Connect with Python:**
|
||||
|
||||
```python
|
||||
from computer import Computer
|
||||
import asyncio
|
||||
|
||||
computer = Computer(
|
||||
os_type="macos",
|
||||
provider_type="lume",
|
||||
name="macos-sequoia-cua:latest"
|
||||
)
|
||||
|
||||
async def main():
|
||||
await computer.run()
|
||||
|
||||
try:
|
||||
screenshot = await computer.interface.screenshot()
|
||||
await computer.interface.left_click(100, 100)
|
||||
finally:
|
||||
await computer.disconnect()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## Windows Sandbox
|
||||
|
||||
Use the native Windows Sandbox feature. **Windows 10 Pro/Enterprise or Windows 11 required.**
|
||||
|
||||
**1. Enable Windows Sandbox:**
|
||||
|
||||
Follow the [Microsoft guide](https://learn.microsoft.com/en-us/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-install) to enable Windows Sandbox.
|
||||
|
||||
**2. Install the dependency:**
|
||||
|
||||
```bash
|
||||
pip install -U git+git://github.com/karkason/pywinsandbox.git
|
||||
```
|
||||
|
||||
**3. Connect with Python:**
|
||||
|
||||
```python
|
||||
from computer import Computer
|
||||
import asyncio
|
||||
|
||||
computer = Computer(
|
||||
os_type="windows",
|
||||
provider_type="windows_sandbox"
|
||||
)
|
||||
|
||||
async def main():
|
||||
await computer.run()
|
||||
|
||||
try:
|
||||
screenshot = await computer.interface.screenshot()
|
||||
await computer.interface.left_click(100, 100)
|
||||
finally:
|
||||
await computer.disconnect()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Using the Computer SDK](/cua/guide/get-started/using-computer-sdk) - Full SDK reference with all sandbox types
|
||||
- [Using the Agent SDK](/cua/guide/get-started/using-agent-sdk) - Add AI automation to your sandboxes
|
||||
@@ -14,12 +14,16 @@ Cua is an open-source platform for building, benchmarking, and deploying agents
|
||||
Cua consists of three main components:
|
||||
|
||||
<div className="not-prose relative rounded-xl overflow-hidden my-8 w-full">
|
||||
<img src="/docs/img/cua-architecture.png" alt="Cua Architecture" className="w-full h-auto rounded-xl" />
|
||||
<img
|
||||
src="/docs/img/cua-architecture.png"
|
||||
alt="Cua Architecture"
|
||||
className="w-full h-auto rounded-xl"
|
||||
/>
|
||||
</div>
|
||||
|
||||
### 1. Desktop Sandboxes
|
||||
|
||||
Isolated virtual environments where your agents can safely execute tasks. Cua supports:
|
||||
Isolated virtual environments where your agents can safely execute tasks:
|
||||
|
||||
- **Cloud Sandboxes** - Managed Linux, Windows, and macOS environments hosted by Cua
|
||||
- **Local Sandboxes** - Docker containers, QEMU VMs, macOS VMs via Lume, or Windows Sandbox on your own machine
|
||||
@@ -36,16 +40,60 @@ A unified SDK for controlling desktop environments programmatically:
|
||||
|
||||
### 3. Agent Framework
|
||||
|
||||
Build agents that see screens, click buttons, and complete tasks autonomously. Run isolated code execution environments for AI coding assistants like Claude Code, Codex CLI, or OpenCode.
|
||||
Build agents that see screens, click buttons, and complete tasks autonomously:
|
||||
|
||||
- **100+ vision-language model options** through Cua VLM Router or direct provider access
|
||||
- **Pre-built agent loops** optimized for computer-use tasks
|
||||
- **Composable architecture** for combining grounding and planning models
|
||||
- **Built-in telemetry** for monitoring agent performance
|
||||
|
||||
## Why Cua?
|
||||
## How Computer-Use Agents Work
|
||||
|
||||
Cua provides isolated, reproducible environments for AI agents to operate safely:
|
||||
Computer-use agents operate through a continuous loop:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 1. OBSERVE │
|
||||
│ Take a screenshot of the screen │
|
||||
└──────────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 2. UNDERSTAND │
|
||||
│ Vision-language model analyzes │
|
||||
│ the screenshot and current goal │
|
||||
└──────────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 3. DECIDE │
|
||||
│ Determine the next action: │
|
||||
│ click, type, scroll, etc. │
|
||||
└──────────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 4. ACT │
|
||||
│ Execute the action on the computer │
|
||||
└──────────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
Loop back to 1
|
||||
```
|
||||
|
||||
This cycle repeats until the agent completes its goal or determines it cannot proceed.
|
||||
|
||||
## Sandbox Options
|
||||
|
||||
| Sandbox Type | OS Support | Best For | API Key Required |
|
||||
| ------------------- | ----------------------- | ---------------------------- | ---------------- |
|
||||
| **Cloud** | Linux, Windows, macOS | Production, teams, CI/CD | Yes |
|
||||
| **Docker** | Linux | Local development | No |
|
||||
| **QEMU Docker** | Linux, Windows, Android | Testing specific OS versions | No |
|
||||
| **Lume (macOS)** | macOS | macOS automation | No |
|
||||
| **Windows Sandbox** | Windows | Windows automation | No |
|
||||
|
||||
## Why Cua?
|
||||
|
||||
- **Secure execution** - Run AI coding assistants and computer-use agents in sandboxed environments
|
||||
- **Self-hostable** - Deploy locally with Docker, QEMU, or Apple Virtualization
|
||||
@@ -54,8 +102,6 @@ Cua provides isolated, reproducible environments for AI agents to operate safely
|
||||
|
||||
## Use Cases
|
||||
|
||||
Cua is ideal for:
|
||||
|
||||
- **AI coding assistants** - Isolated code execution environments for Claude Code, Codex CLI, OpenCode, and other AI coding tools
|
||||
- **Computer-use agents** - Build agents that interact with any desktop application autonomously
|
||||
- **Workflow automation** - Automate repetitive tasks across any application
|
||||
@@ -65,4 +111,4 @@ Cua is ideal for:
|
||||
|
||||
## Getting Started
|
||||
|
||||
Ready to build your first agent? Continue to [Set Up a Sandbox](/cua/guide/get-started/set-up-sandbox) to set up your environment and run your first automation.
|
||||
Ready to build your first agent? Continue to the [Quickstart](/cua/guide/get-started/quickstart) to get a computer-use agent running.
|
||||
|
||||
623
docs/content/docs/cua/reference/agent-sdk/changelog.mdx
Normal file
623
docs/content/docs/cua/reference/agent-sdk/changelog.mdx
Normal file
@@ -0,0 +1,623 @@
|
||||
---
|
||||
title: Changelog
|
||||
description: Release history for Agent SDK
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-changelog.ts
|
||||
Last updated: 2026-02-04
|
||||
*/}
|
||||
|
||||
# Agent SDK Changelog
|
||||
|
||||
All notable changes to the Agent SDK are documented here.
|
||||
|
||||
## 0.7.x
|
||||
|
||||
### v0.7.24 (2026-02-04)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.12, cua-som: 0.1.3
|
||||
|
||||
- Initial release or no path-specific changes found
|
||||
|
||||
### v0.7.22 (2026-01-28)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.12, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.22 by @github-actions[bot]
|
||||
|
||||
### v0.7.21 (2026-01-26)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.11, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.21 by @github-actions[bot]
|
||||
|
||||
### v0.7.18 (2026-01-22)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.10, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.18 by @github-actions[bot]
|
||||
- fix(agent): accept 'computer_use' as valid function name for Fara model ([#865](https://github.com/trycua/cua/pull/865)) by @sarinali
|
||||
|
||||
### v0.7.17 (2026-01-17)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.7, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.17 by @github-actions[bot]
|
||||
|
||||
### v0.7.16 (2026-01-17)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.7, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.16 by @github-actions[bot]
|
||||
|
||||
### v0.7.15 (2026-01-17)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.7, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.15 by @github-actions[bot]
|
||||
|
||||
### v0.7.14 (2026-01-17)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.6, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.14 by @github-actions[bot]
|
||||
|
||||
### v0.7.13 (2026-01-17)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.6, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.13 by @github-actions[bot]
|
||||
- Fix/gradio 6.3 compatibility ([#810](https://github.com/trycua/cua/pull/810)) by @Weichen Zhang
|
||||
- fix(agent): create screenshot_dir when trajectory_dir option is specified ([#813](https://github.com/trycua/cua/pull/813)) by @Harsh Verma
|
||||
- fix(agent): only yield partial response if not empty ([#802](https://github.com/trycua/cua/pull/802)) by @Harsh Verma
|
||||
- fix tool mismatch in uitars agent loop ([#640](https://github.com/trycua/cua/pull/640)) by @zju-lx
|
||||
|
||||
### v0.7.12 (2026-01-13)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.6, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.12 by @github-actions[bot]
|
||||
- pass browser tool ([#774](https://github.com/trycua/cua/pull/774)) by @Sarina Li
|
||||
- feat(agent): add OpenTelemetry instrumentation callback ([#662](https://github.com/trycua/cua/pull/662)) by @r33drichards
|
||||
- Fix Omniparser historical message conversion using per-screenshot mappings ([#706](https://github.com/trycua/cua/pull/706)) by @Fizza Mukhtar
|
||||
|
||||
### v0.7.11 (2026-01-12)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.6, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.11 by @github-actions[bot]
|
||||
|
||||
### v0.7.10 (2026-01-12)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.6, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.10 by @github-actions[bot]
|
||||
|
||||
### v0.7.9 (2026-01-12)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.5, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.9 by @github-actions[bot]
|
||||
|
||||
### v0.7.8 (2026-01-12)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.4, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.8 by @github-actions[bot]
|
||||
- Bump cua-agent to v0.7.7 ([#781](https://github.com/trycua/cua/pull/781)) by @Francesco Bonacci
|
||||
- Bump cua-agent to v0.7.7 ([#780](https://github.com/trycua/cua/pull/780)) by @Francesco Bonacci
|
||||
|
||||
### v0.7.6 (2026-01-12)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.1, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.6 by @github-actions[bot]
|
||||
|
||||
### v0.7.5 (2026-01-12)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.1, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.5 by @github-actions[bot]
|
||||
|
||||
### v0.7.4 (2026-01-12)
|
||||
|
||||
**Dependencies:** cua-computer: 0.5.1, cua-som: 0.1.3
|
||||
|
||||
- Bump cua-agent to v0.7.4 by @github-actions[bot]
|
||||
- refactor(docs): reorganize lume/cua docs and standardize READMEs ([#752](https://github.com/trycua/cua/pull/752)) by @Francesco Bonacci
|
||||
- feat(lume,ci): add unattended VM setup and reorganize CI/CD workflows ([#729](https://github.com/trycua/cua/pull/729)) by @Francesco Bonacci
|
||||
- Fix linting in cua-bench module ([#727](https://github.com/trycua/cua/pull/727)) by @ddupont
|
||||
- Raise clear error when using Ollama models with ComputerAgent image inputs ([#711](https://github.com/trycua/cua/pull/711)) by @Fizza Mukhtar
|
||||
- update dead links due to docs update by @Sarina Li
|
||||
- add vm name to start/end by @Sarina Li
|
||||
|
||||
## 0.4.x
|
||||
|
||||
### v0.4.53 (2025-11-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.
|
||||
|
||||
- Jagjeevan's Fix + Merged Main for 4o Model Fix by @sarinali in https://github.com/trycua/cua/pull/522
|
||||
- fix: Added GPT-4o compatibility for screenshot actions with text parameter by @JagjeevanAK in https://github.com/trycua/cua/pull/422
|
||||
- Add test infrastructure with CI/CD #478 by @AceAtDev in https://github.com/trycua/cua/pull/491
|
||||
- Fix/omniparser predict refactor by @sarinali in https://github.com/trycua/cua/pull/529
|
||||
- Make VS Code Python interpreter path cross-platform by @skools-here in https://github.com/trycua/cua/pull/520
|
||||
- Fix: sanitize shell in subprocess calls by @AdityaBavadekar in https://github.com/trycua/cua/pull/519
|
||||
- [Agent] Add support for overriding api_base and api_url kwargs by @ddupont808 in https://github.com/trycua/cua/pull/504
|
||||
- Update model list and schedule daily test for agent testing by @YeIIcw in https://github.com/trycua/cua/pull/540
|
||||
- Add Claude Desktop Extension by @YeIIcw in https://github.com/trycua/cua/pull/521
|
||||
- [AGENT] - New Model Gelato-30B-A3B added by @tamoghnokandar in https://github.com/trycua/cua/pull/558
|
||||
- [AGENT] - New model UI-Ins added by @tamoghnokandar in https://github.com/trycua/cua/pull/549
|
||||
- Add "cua/" LLM provider by @ddupont808 in https://github.com/trycua/cua/pull/506
|
||||
- Add Local Desktop Mode for MCP Server with updated docs by @YeIIcw in https://github.com/trycua/cua/pull/493
|
||||
- Fix: Enable custom function tools with Anthropic models by @LucaStngn in https://github.com/trycua/cua/pull/548
|
||||
- Fix cua adapter, add UI-TARS-2 model by @ddupont808 in https://github.com/trycua/cua/pull/592
|
||||
- Fix cua adapter for anthropic models by @ddupont808 in https://github.com/trycua/cua/pull/601
|
||||
- Remove hud-python from cua-agent[all] extra by @f-trycua in https://github.com/trycua/cua/pull/603
|
||||
- Add automatic CUA_API_KEY environment variable support by @f-trycua in https://github.com/trycua/cua/pull/604
|
||||
|
||||
New Contributors
|
||||
|
||||
- @AceAtDev made their first contribution in https://github.com/trycua/cua/pull/491
|
||||
- @skools-here made their first contribution in https://github.com/trycua/cua/pull/520
|
||||
- @tamoghnokandar made their first contribution in https://github.com/trycua/cua/pull/545
|
||||
- @dinmukhamedm made their first contribution in https://github.com/trycua/cua/pull/404
|
||||
- @LucaStngn made their first contribution in https://github.com/trycua/cua/pull/548
|
||||
|
||||
### v0.4.35 (2025-10-22)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
- Standardize Python version 3.12 across all packages by @AdityaBavadekar in https://github.com/trycua/cua/pull/500
|
||||
- Add support for all QwenVL models by @ddupont808 in https://github.com/trycua/cua/pull/501
|
||||
|
||||
### v0.4.34 (2025-10-17)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
- Fix torch dependency in moondream3 loop by @ddupont808 in https://github.com/trycua/cua/pull/482
|
||||
|
||||
New Contributors
|
||||
|
||||
- @sarinali made their first contribution in https://github.com/trycua/cua/pull/477
|
||||
|
||||
### v0.4.33 (2025-10-15)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
- Stream MCP responses instead of buffering by @YeIIcw in https://github.com/trycua/cua/pull/427
|
||||
- Add support for Gemini CUA model by @ddupont808 in https://github.com/trycua/cua/pull/472
|
||||
- Add support for Claude Haiku 4.5 by @ddupont808 in https://github.com/trycua/cua/pull/474
|
||||
- Add bump2version configuration for all Python packages by @r33drichards in https://github.com/trycua/cua/pull/463
|
||||
|
||||
### v0.4.32 (2025-09-25)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.31 (2025-09-13)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.30 (2025-09-12)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.29 (2025-09-12)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.28 (2025-09-12)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.27 (2025-09-10)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.26 (2025-09-10)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.25 (2025-09-05)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
- Change HUD dataset name from `OSWorld-Verified-XLang` to `OSWorld-Verified` by @jamesmurdza in https://github.com/trycua/cua/pull/392
|
||||
- Fixed error when running agent with multimodal user inputs in the anthropic loop by @ddupont808 in https://github.com/trycua/cua/pull/394
|
||||
- Reference documentation batch by @onel in https://github.com/trycua/cua/pull/390
|
||||
|
||||
### v0.4.24 (2025-08-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.23 (2025-08-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.22 (2025-08-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.21 (2025-08-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.20 (2025-08-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.19 (2025-08-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
- Added screenshot_dir parameter
|
||||
- Bugfix: Lazy loading of MLX by @ddupont808 in https://github.com/trycua/cua/pull/373
|
||||
|
||||
### v0.4.18 (2025-08-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
- Fix example code and notebooks by @jamesmurdza in https://github.com/trycua/cua/pull/364
|
||||
- Added a readme file to the notebooks folder by @onel in https://github.com/trycua/cua/pull/361
|
||||
- Restrict root project to Python versions below 3.14 by @jamesmurdza in https://github.com/trycua/cua/pull/363
|
||||
- Restored `mlx/` adapter by @ddupont808 in https://github.com/trycua/cua/pull/366
|
||||
- Upgrade HUD SDK to 0.4.12 by @ddupont808 in https://github.com/trycua/cua/pull/371
|
||||
- Added callback to normalize common tool call hallucinations seen during evals
|
||||
|
||||
New Contributors
|
||||
|
||||
- @onel made their first contribution in https://github.com/trycua/cua/pull/361
|
||||
|
||||
### v0.4.17 (2025-08-19)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.16 (2025-08-19)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.15 (2025-08-19)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
- Pin OpenAI version to work around BerriAI/litellm#13711 by @jamesmurdza in https://github.com/trycua/cua/pull/356
|
||||
- Upgrade Claude 3.5 snapshot in web app, examples and docs by @jamesmurdza in https://github.com/trycua/cua/pull/359
|
||||
- Update agent/computer SDKs to match changes in telemetry SDK by @jamesmurdza in https://github.com/trycua/cua/pull/355
|
||||
|
||||
### v0.4.14 (2025-08-18)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
- Upgrade Agent SDK to require Python 3.12 by @jamesmurdza in https://github.com/trycua/cua/pull/342
|
||||
- Fix UI-TARS predict_click always returning None by @ddupont808 in https://github.com/trycua/cua/pull/350
|
||||
|
||||
### v0.4.13 (2025-08-14)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
- [Agent] Add HUD evals, OSWorld-verified docs, and support for custom computers by @ddupont808 in https://github.com/trycua/cua/pull/334
|
||||
|
||||
### v0.4.12 (2025-08-12)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
- [Agent] Implement left_mouse_down, left_mouse_up, and tool errors by @ddupont808 in https://github.com/trycua/cua/pull/333
|
||||
- [Agent] Add GLM-4.5V support by @ddupont808 in https://github.com/trycua/cua/pull/337
|
||||
|
||||
### v0.4.11 (2025-08-07)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.10 (2025-08-06)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.9 (2025-08-06)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.8 (2025-08-05)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.7 (2025-08-05)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.6 (2025-08-04)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.5 (2025-07-29)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.4.4 (2025-07-29)
|
||||
|
||||
Bugfixes caused by `mouse_move` having the wrong name
|
||||
|
||||
### v0.4.3 (2025-07-29)
|
||||
|
||||
Bugfixes caused by `mouse_move` having the wrong name
|
||||
|
||||
### v0.4.2 (2025-07-29)
|
||||
|
||||
- [Agent] Fix Anthropic unexpected tool_use_id by @ddupont808 in https://github.com/trycua/cua/pull/325
|
||||
|
||||
### v0.4.1 (2025-07-28)
|
||||
|
||||
Updated to use latest `cua-core`
|
||||
|
||||
### v0.4.0 (2025-07-28)
|
||||
|
||||
This update refactored the Agent SDK to make it easier to implement new features and support the release of new agent models/loops.
|
||||
|
||||
Changelog:
|
||||
|
||||
- Reworked agent loop, now all agent providers share a loop (Generate, Execute, Repeat), with the only difference between loops being the implementation of the Generate function
|
||||
- Replaced LLM clients with LiteLLM, now all agent providers support any provider supported by LiteLLM
|
||||
- Added 2 custom LiteLLM providers for local model inference on CUDA and MLX devices: `huggingface-local/`, `mlx/`
|
||||
- Reworked callback system to have hooks at every step of the lifecycle
|
||||
- Converted logging, trajectory saving, image retention into callbacks
|
||||
- Added new callbacks - PII Anonymization (still a W.I.P) & budget management
|
||||
- Anthropic providers - Added support for explicit prompt caching
|
||||
- OpenAI providers - Added support for zero data retention
|
||||
- Added Agent CLI for quick testing: `python -m agent.cli <model name>`
|
||||
|
||||
[Breaking Changes](https://docs-woad-phi.vercel.app/home/agent-sdk/migration-guide#breaking-changes)
|
||||
|
||||
- **Initialization:**
|
||||
- `ComputerAgent` (v0.4.x) uses `model` as a string (e.g. "anthropic/claude-3-5-sonnet-20241022") instead of `LLM` and `AgentLoop` objects.
|
||||
- `tools` is a list (can include multiple computers and decorated functions).
|
||||
- `callbacks` are now first-class for extensibility (image retention, budget, trajectory, logging, etc).
|
||||
- **No explicit `loop` parameter:**
|
||||
- Loop is inferred from the `model` string (e.g. `anthropic/`, `openai/`, `omniparser+`, `ui-tars`).
|
||||
- **No explicit `computer` parameter:**
|
||||
- Computers are added to `tools` list.
|
||||
|
||||
Install
|
||||
|
||||
```bash
|
||||
Before merge:
|
||||
pip install --pre "cua-agent[all]==0.4.0b4"
|
||||
|
||||
After merge:
|
||||
pip install "cua-agent[all]"
|
||||
|
||||
or install specific providers
|
||||
pip install "cua-agent[openai]" # OpenAI computer-use-preview support
|
||||
pip install "cua-agent[anthropic]" # Anthropic Claude support
|
||||
pip install "cua-agent[omni]" # Omniparser + any LLM support
|
||||
pip install "cua-agent[uitars]" # UI-TARS
|
||||
pip install "cua-agent[uitars-mlx]" # UI-TARS + MLX support
|
||||
pip install "cua-agent[uitars-hf]" # UI-TARS + Huggingface support
|
||||
pip install "cua-agent[ui]" # Gradio UI support
|
||||
```
|
||||
|
||||
Supported Models
|
||||
|
||||
Anthropic Claude (Computer Use API)
|
||||
|
||||
```python
|
||||
model="anthropic/claude-3-5-sonnet-20241022"
|
||||
model="anthropic/claude-3-5-sonnet-20240620"
|
||||
model="anthropic/claude-opus-4-20250514"
|
||||
model="anthropic/claude-sonnet-4-20250514"
|
||||
```
|
||||
|
||||
OpenAI Computer Use Preview
|
||||
|
||||
```python
|
||||
model="openai/computer-use-preview"
|
||||
```
|
||||
|
||||
UI-TARS (Local or Huggingface Inference)
|
||||
|
||||
```python
|
||||
model="huggingface-local/ByteDance-Seed/UI-TARS-1.5-7B"
|
||||
model="ollama_chat/0000/ui-tars-1.5-7b"
|
||||
```
|
||||
|
||||
Omniparser + Any LLM
|
||||
|
||||
```python
|
||||
model="omniparser+ollama_chat/mistral-small3.2"
|
||||
model="omniparser+vertex_ai/gemini-pro"
|
||||
model="omniparser+anthropic/claude-3-5-sonnet-20241022"
|
||||
model="omniparser+openai/gpt-4o"
|
||||
```
|
||||
|
||||
## 0.3.x
|
||||
|
||||
### v0.3.2 (2025-07-15)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.3.1 (2025-07-01)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
## 0.2.x
|
||||
|
||||
### v0.2.15 (2025-06-25)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.14 (2025-06-24)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.13 (2025-06-24)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.12 (2025-06-20)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.11 (2025-06-18)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.10 (2025-06-10)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
- Fixed image retention bug by @ddupont808 in https://github.com/trycua/cua/pull/282
|
||||
- Removed `torch` requirement from `cua-agent/core` and `cua-agent/anthropic` by @ddupont808 in https://github.com/trycua/cua/pull/285
|
||||
|
||||
### v0.2.9 (2025-06-05)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.7 (2025-06-05)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.6 (2025-05-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.5 (2025-05-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.4 (2025-05-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.3 (2025-05-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.2 (2025-05-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.1 (2025-05-16)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.2.0 (2025-05-14)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
## 0.1.x
|
||||
|
||||
### v0.1.44 (2025-05-13)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.43 (2025-05-12)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.42 (2025-05-11)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.41 (2025-05-11)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.40 (2025-05-11)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.39 (2025-05-11)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.38 (2025-05-11)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.37 (2025-05-10)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.35 (2025-05-10)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.34 (2025-05-10)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.33 (2025-05-10)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.32 (2025-05-02)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.31 (2025-04-29)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.30 (2025-04-24)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.29 (2025-04-22)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.28 (2025-04-15)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.27 (2025-04-15)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.26 (2025-04-14)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.25 (2025-04-06)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.24 (2025-04-06)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.23 (2025-04-06)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.22 (2025-04-04)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.21 (2025-04-02)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.20 (2025-03-30)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.19 (2025-03-30)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.18 (2025-03-30)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.17 (2025-03-24)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.6 (2025-03-19)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
|
||||
### v0.1.5 (2025-03-17)
|
||||
|
||||
**Dependencies:** cua-computer: latest, cua-som: latest
|
||||
File diff suppressed because it is too large
Load Diff
@@ -2,5 +2,5 @@
|
||||
"title": "Agent SDK",
|
||||
"description": "Python API for building computer-use agents",
|
||||
"icon": "Bot",
|
||||
"pages": ["index"]
|
||||
"pages": ["changelog"]
|
||||
}
|
||||
|
||||
70
docs/content/docs/cua/reference/agent-sdk/v0.3/api.mdx
Normal file
70
docs/content/docs/cua/reference/agent-sdk/v0.3/api.mdx
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Agent SDK v0.3 API Reference
|
||||
description: API reference for Agent SDK version 0.3
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-versioned-docs.ts
|
||||
Source tag: agent-v0.3.2
|
||||
Version: 0.3.2
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
|
||||
<Callout type="warn">
|
||||
This is documentation for **v0.3**. [View latest version](/cua/reference/agent-sdk).
|
||||
</Callout>
|
||||
|
||||
<div className="flex items-center gap-2 mb-6">
|
||||
<span className="px-2 py-1 bg-amber-100 dark:bg-amber-900 text-amber-800 dark:text-amber-200 rounded text-sm font-mono">
|
||||
v0.3.2
|
||||
</span>
|
||||
<span className="text-sm text-fd-muted-foreground">pip install cua-agent==0.3.2</span>
|
||||
</div>
|
||||
|
||||
CUA (Computer Use) Agent for AI-driven computer interaction.
|
||||
|
||||
## Classes
|
||||
|
||||
| Class | Description |
|
||||
| --------------- | -------------------------------------------------------------------------------------- |
|
||||
| `LLMProvider` | Supported LLM providers. |
|
||||
| `LLM` | Configuration for LLM model and provider. |
|
||||
| `ComputerAgent` | A computer agent that can perform automated tasks using natural language instructions. |
|
||||
|
||||
## LLMProvider
|
||||
|
||||
Supported LLM providers.
|
||||
|
||||
## LLM
|
||||
|
||||
Configuration for LLM model and provider.
|
||||
|
||||
## ComputerAgent
|
||||
|
||||
A computer agent that can perform automated tasks using natural language instructions.
|
||||
|
||||
### Methods
|
||||
|
||||
#### ComputerAgent.initialize
|
||||
|
||||
```python
|
||||
async def initialize(self) -> None
|
||||
```
|
||||
|
||||
Initialize the agent and its components.
|
||||
|
||||
#### ComputerAgent.run
|
||||
|
||||
```python
|
||||
async def run(self, task: str) -> AsyncGenerator[AgentResponse, None]
|
||||
```
|
||||
|
||||
Run a task using the computer agent.
|
||||
|
||||
Args:
|
||||
task: Task description
|
||||
|
||||
Yields:
|
||||
Agent response format
|
||||
5
docs/content/docs/cua/reference/agent-sdk/v0.3/meta.json
Normal file
5
docs/content/docs/cua/reference/agent-sdk/v0.3/meta.json
Normal file
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "v0.3",
|
||||
"description": "Agent SDK v0.3 API Reference",
|
||||
"pages": ["api"]
|
||||
}
|
||||
83
docs/content/docs/cua/reference/agent-sdk/v0.4/api.mdx
Normal file
83
docs/content/docs/cua/reference/agent-sdk/v0.4/api.mdx
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: Agent SDK v0.4 API Reference
|
||||
description: API reference for Agent SDK version 0.4
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-versioned-docs.ts
|
||||
Source tag: agent-v0.4.53
|
||||
Version: 0.4.53
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
|
||||
<Callout type="warn">
|
||||
This is documentation for **v0.4**. [View latest version](/cua/reference/agent-sdk).
|
||||
</Callout>
|
||||
|
||||
<div className="flex items-center gap-2 mb-6">
|
||||
<span className="px-2 py-1 bg-amber-100 dark:bg-amber-900 text-amber-800 dark:text-amber-200 rounded text-sm font-mono">
|
||||
v0.4.53
|
||||
</span>
|
||||
<span className="text-sm text-fd-muted-foreground">pip install cua-agent==0.4.53</span>
|
||||
</div>
|
||||
|
||||
agent - Decorator-based Computer Use Agent with liteLLM integration
|
||||
|
||||
## Classes
|
||||
|
||||
| Class | Description |
|
||||
| --------------- | ---------------------------------------------------------------------- |
|
||||
| `ComputerAgent` | Main agent class that automatically selects the appropriate agent loop |
|
||||
|
||||
## ComputerAgent
|
||||
|
||||
Main agent class that automatically selects the appropriate agent loop
|
||||
based on the model and executes tool calls.
|
||||
|
||||
### Methods
|
||||
|
||||
#### ComputerAgent.run
|
||||
|
||||
```python
|
||||
async def run(self, messages: Messages, stream: bool = False, api_key: Optional[str] = None, api_base: Optional[str] = None, additional_generation_kwargs = {}) -> AsyncGenerator[Dict[str, Any], None]
|
||||
```
|
||||
|
||||
Run the agent with the given messages using Computer protocol handler pattern.
|
||||
|
||||
Args:
|
||||
messages: List of message dictionaries
|
||||
stream: Whether to stream the response
|
||||
api_key: Optional API key override for the model provider
|
||||
api_base: Optional API base URL override for the model provider
|
||||
\*\*additional_generation_kwargs: Additional arguments passed to the model provider
|
||||
|
||||
Returns:
|
||||
AsyncGenerator that yields response chunks
|
||||
|
||||
#### ComputerAgent.predict_click
|
||||
|
||||
```python
|
||||
async def predict_click(self, instruction: str, image_b64: Optional[str] = None) -> Optional[Tuple[int, int]]
|
||||
```
|
||||
|
||||
Predict click coordinates based on image and instruction.
|
||||
|
||||
Args:
|
||||
instruction: Instruction for where to click
|
||||
image_b64: Base64 encoded image (optional, will take screenshot if not provided)
|
||||
|
||||
Returns:
|
||||
None or tuple with (x, y) coordinates
|
||||
|
||||
#### ComputerAgent.get_capabilities
|
||||
|
||||
```python
|
||||
def get_capabilities(self) -> List[AgentCapability]
|
||||
```
|
||||
|
||||
Get list of capabilities supported by the current agent config.
|
||||
|
||||
Returns:
|
||||
List of capability strings (e.g., ["step", "click"])
|
||||
5
docs/content/docs/cua/reference/agent-sdk/v0.4/meta.json
Normal file
5
docs/content/docs/cua/reference/agent-sdk/v0.4/meta.json
Normal file
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "v0.4",
|
||||
"description": "Agent SDK v0.4 API Reference",
|
||||
"pages": ["api"]
|
||||
}
|
||||
83
docs/content/docs/cua/reference/agent-sdk/v0.5/api.mdx
Normal file
83
docs/content/docs/cua/reference/agent-sdk/v0.5/api.mdx
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: Agent SDK v0.5 API Reference
|
||||
description: API reference for Agent SDK version 0.5
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-versioned-docs.ts
|
||||
Source tag: agent-v0.5.2
|
||||
Version: 0.5.2
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
|
||||
<Callout type="warn">
|
||||
This is documentation for **v0.5**. [View latest version](/cua/reference/agent-sdk).
|
||||
</Callout>
|
||||
|
||||
<div className="flex items-center gap-2 mb-6">
|
||||
<span className="px-2 py-1 bg-amber-100 dark:bg-amber-900 text-amber-800 dark:text-amber-200 rounded text-sm font-mono">
|
||||
v0.5.2
|
||||
</span>
|
||||
<span className="text-sm text-fd-muted-foreground">pip install cua-agent==0.5.2</span>
|
||||
</div>
|
||||
|
||||
agent - Decorator-based Computer Use Agent with liteLLM integration
|
||||
|
||||
## Classes
|
||||
|
||||
| Class | Description |
|
||||
| --------------- | ---------------------------------------------------------------------- |
|
||||
| `ComputerAgent` | Main agent class that automatically selects the appropriate agent loop |
|
||||
|
||||
## ComputerAgent
|
||||
|
||||
Main agent class that automatically selects the appropriate agent loop
|
||||
based on the model and executes tool calls.
|
||||
|
||||
### Methods
|
||||
|
||||
#### ComputerAgent.run
|
||||
|
||||
```python
|
||||
async def run(self, messages: Messages, stream: bool = False, api_key: Optional[str] = None, api_base: Optional[str] = None, additional_generation_kwargs = {}) -> AsyncGenerator[Dict[str, Any], None]
|
||||
```
|
||||
|
||||
Run the agent with the given messages using Computer protocol handler pattern.
|
||||
|
||||
Args:
|
||||
messages: List of message dictionaries
|
||||
stream: Whether to stream the response
|
||||
api_key: Optional API key override for the model provider
|
||||
api_base: Optional API base URL override for the model provider
|
||||
\*\*additional_generation_kwargs: Additional arguments passed to the model provider
|
||||
|
||||
Returns:
|
||||
AsyncGenerator that yields response chunks
|
||||
|
||||
#### ComputerAgent.predict_click
|
||||
|
||||
```python
|
||||
async def predict_click(self, instruction: str, image_b64: Optional[str] = None) -> Optional[Tuple[int, int]]
|
||||
```
|
||||
|
||||
Predict click coordinates based on image and instruction.
|
||||
|
||||
Args:
|
||||
instruction: Instruction for where to click
|
||||
image_b64: Base64 encoded image (optional, will take screenshot if not provided)
|
||||
|
||||
Returns:
|
||||
None or tuple with (x, y) coordinates
|
||||
|
||||
#### ComputerAgent.get_capabilities
|
||||
|
||||
```python
|
||||
def get_capabilities(self) -> List[AgentCapability]
|
||||
```
|
||||
|
||||
Get list of capabilities supported by the current agent config.
|
||||
|
||||
Returns:
|
||||
List of capability strings (e.g., ["step", "click"])
|
||||
5
docs/content/docs/cua/reference/agent-sdk/v0.5/meta.json
Normal file
5
docs/content/docs/cua/reference/agent-sdk/v0.5/meta.json
Normal file
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "v0.5",
|
||||
"description": "Agent SDK v0.5 API Reference",
|
||||
"pages": ["api"]
|
||||
}
|
||||
99
docs/content/docs/cua/reference/agent-sdk/v0.6/api.mdx
Normal file
99
docs/content/docs/cua/reference/agent-sdk/v0.6/api.mdx
Normal file
@@ -0,0 +1,99 @@
|
||||
---
|
||||
title: Agent SDK v0.6 API Reference
|
||||
description: API reference for Agent SDK version 0.6
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-versioned-docs.ts
|
||||
Source tag: agent-v0.6.2
|
||||
Version: 0.6.2
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
|
||||
<Callout type="warn">
|
||||
This is documentation for **v0.6**. [View latest version](/cua/reference/agent-sdk).
|
||||
</Callout>
|
||||
|
||||
<div className="flex items-center gap-2 mb-6">
|
||||
<span className="px-2 py-1 bg-amber-100 dark:bg-amber-900 text-amber-800 dark:text-amber-200 rounded text-sm font-mono">
|
||||
v0.6.2
|
||||
</span>
|
||||
<span className="text-sm text-fd-muted-foreground">pip install cua-agent==0.6.2</span>
|
||||
</div>
|
||||
|
||||
agent - Decorator-based Computer Use Agent with liteLLM integration
|
||||
|
||||
## Classes
|
||||
|
||||
| Class | Description |
|
||||
| --------------- | ---------------------------------------------------------------------- |
|
||||
| `ComputerAgent` | Main agent class that automatically selects the appropriate agent loop |
|
||||
|
||||
## ComputerAgent
|
||||
|
||||
Main agent class that automatically selects the appropriate agent loop
|
||||
based on the model and executes tool calls.
|
||||
|
||||
### Methods
|
||||
|
||||
#### ComputerAgent.run
|
||||
|
||||
```python
|
||||
async def run(self, messages: Messages, stream: bool = False, api_key: Optional[str] = None, api_base: Optional[str] = None, additional_generation_kwargs = {}) -> AsyncGenerator[Dict[str, Any], None]
|
||||
```
|
||||
|
||||
Run the agent with the given messages using Computer protocol handler pattern.
|
||||
|
||||
Args:
|
||||
messages: List of message dictionaries
|
||||
stream: Whether to stream the response
|
||||
api_key: Optional API key override for the model provider
|
||||
api_base: Optional API base URL override for the model provider
|
||||
\*\*additional_generation_kwargs: Additional arguments passed to the model provider
|
||||
|
||||
Returns:
|
||||
AsyncGenerator that yields response chunks
|
||||
|
||||
#### ComputerAgent.predict_click
|
||||
|
||||
```python
|
||||
async def predict_click(self, instruction: str, image_b64: Optional[str] = None) -> Optional[Tuple[int, int]]
|
||||
```
|
||||
|
||||
Predict click coordinates based on image and instruction.
|
||||
|
||||
Args:
|
||||
instruction: Instruction for where to click
|
||||
image_b64: Base64 encoded image (optional, will take screenshot if not provided)
|
||||
|
||||
Returns:
|
||||
None or tuple with (x, y) coordinates
|
||||
|
||||
#### ComputerAgent.get_capabilities
|
||||
|
||||
```python
|
||||
def get_capabilities(self) -> List[AgentCapability]
|
||||
```
|
||||
|
||||
Get list of capabilities supported by the current agent config.
|
||||
|
||||
Returns:
|
||||
List of capability strings (e.g., ["step", "click"])
|
||||
|
||||
#### ComputerAgent.open
|
||||
|
||||
```python
|
||||
def open(self, port: Optional[int] = None)
|
||||
```
|
||||
|
||||
Start the playground server and open it in the browser.
|
||||
|
||||
This method starts a local HTTP server that exposes the /responses endpoint
|
||||
and automatically opens the CUA playground interface in the default browser.
|
||||
|
||||
Args:
|
||||
port: Port to run the server on. If None, finds an available port automatically.
|
||||
|
||||
Example: >>> agent = ComputerAgent(model="claude-sonnet-4") >>> agent.open() # Starts server and opens browser
|
||||
5
docs/content/docs/cua/reference/agent-sdk/v0.6/meta.json
Normal file
5
docs/content/docs/cua/reference/agent-sdk/v0.6/meta.json
Normal file
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "v0.6",
|
||||
"description": "Agent SDK v0.6 API Reference",
|
||||
"pages": ["api"]
|
||||
}
|
||||
99
docs/content/docs/cua/reference/agent-sdk/v0.7/api.mdx
Normal file
99
docs/content/docs/cua/reference/agent-sdk/v0.7/api.mdx
Normal file
@@ -0,0 +1,99 @@
|
||||
---
|
||||
title: Agent SDK v0.7 API Reference
|
||||
description: API reference for Agent SDK version 0.7
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-versioned-docs.ts
|
||||
Source tag: agent-v0.7.23
|
||||
Version: 0.7.23
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
|
||||
<Callout type="warn">
|
||||
This is documentation for **v0.7**. [View latest version](/cua/reference/agent-sdk).
|
||||
</Callout>
|
||||
|
||||
<div className="flex items-center gap-2 mb-6">
|
||||
<span className="px-2 py-1 bg-amber-100 dark:bg-amber-900 text-amber-800 dark:text-amber-200 rounded text-sm font-mono">
|
||||
v0.7.23
|
||||
</span>
|
||||
<span className="text-sm text-fd-muted-foreground">pip install cua-agent==0.7.23</span>
|
||||
</div>
|
||||
|
||||
agent - Decorator-based Computer Use Agent with liteLLM integration
|
||||
|
||||
## Classes
|
||||
|
||||
| Class | Description |
|
||||
| --------------- | ---------------------------------------------------------------------- |
|
||||
| `ComputerAgent` | Main agent class that automatically selects the appropriate agent loop |
|
||||
|
||||
## ComputerAgent
|
||||
|
||||
Main agent class that automatically selects the appropriate agent loop
|
||||
based on the model and executes tool calls.
|
||||
|
||||
### Methods
|
||||
|
||||
#### ComputerAgent.run
|
||||
|
||||
```python
|
||||
async def run(self, messages: Messages, stream: bool = False, api_key: Optional[str] = None, api_base: Optional[str] = None, additional_generation_kwargs = {}) -> AsyncGenerator[Dict[str, Any], None]
|
||||
```
|
||||
|
||||
Run the agent with the given messages using Computer protocol handler pattern.
|
||||
|
||||
Args:
|
||||
messages: List of message dictionaries
|
||||
stream: Whether to stream the response
|
||||
api_key: Optional API key override for the model provider
|
||||
api_base: Optional API base URL override for the model provider
|
||||
\*\*additional_generation_kwargs: Additional arguments passed to the model provider
|
||||
|
||||
Returns:
|
||||
AsyncGenerator that yields response chunks
|
||||
|
||||
#### ComputerAgent.predict_click
|
||||
|
||||
```python
|
||||
async def predict_click(self, instruction: str, image_b64: Optional[str] = None) -> Optional[Tuple[int, int]]
|
||||
```
|
||||
|
||||
Predict click coordinates based on image and instruction.
|
||||
|
||||
Args:
|
||||
instruction: Instruction for where to click
|
||||
image_b64: Base64 encoded image (optional, will take screenshot if not provided)
|
||||
|
||||
Returns:
|
||||
None or tuple with (x, y) coordinates
|
||||
|
||||
#### ComputerAgent.get_capabilities
|
||||
|
||||
```python
|
||||
def get_capabilities(self) -> List[AgentCapability]
|
||||
```
|
||||
|
||||
Get list of capabilities supported by the current agent config.
|
||||
|
||||
Returns:
|
||||
List of capability strings (e.g., ["step", "click"])
|
||||
|
||||
#### ComputerAgent.open
|
||||
|
||||
```python
|
||||
def open(self, port: Optional[int] = None)
|
||||
```
|
||||
|
||||
Start the playground server and open it in the browser.
|
||||
|
||||
This method starts a local HTTP server that exposes the /responses endpoint
|
||||
and automatically opens the Cua playground interface in the default browser.
|
||||
|
||||
Args:
|
||||
port: Port to run the server on. If None, finds an available port automatically.
|
||||
|
||||
Example: >>> agent = ComputerAgent(model="claude-sonnet-4") >>> agent.open() # Starts server and opens browser
|
||||
5
docs/content/docs/cua/reference/agent-sdk/v0.7/meta.json
Normal file
5
docs/content/docs/cua/reference/agent-sdk/v0.7/meta.json
Normal file
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "v0.7",
|
||||
"description": "Agent SDK v0.7 API Reference",
|
||||
"pages": ["api"]
|
||||
}
|
||||
28
docs/content/docs/cua/reference/cli/changelog.mdx
Normal file
28
docs/content/docs/cua/reference/cli/changelog.mdx
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Changelog
|
||||
description: Release history for Cua CLI
|
||||
---
|
||||
|
||||
# CLI Changelog
|
||||
|
||||
All notable changes to the Cua CLI are documented here.
|
||||
|
||||
## 0.1.x
|
||||
|
||||
### v0.1.0 (Unreleased)
|
||||
|
||||
Initial release of the unified Cua CLI.
|
||||
|
||||
**Features:**
|
||||
|
||||
- Authentication management (`cua auth login/logout/env`)
|
||||
- Sandbox lifecycle management (`cua sandbox create/list/start/stop/delete`)
|
||||
- Cloud image management (`cua image list/push/pull/delete`)
|
||||
- Skills recording and playback (`cua skills record/list/read/replay`)
|
||||
- MCP server for AI assistants (`cua serve-mcp`)
|
||||
|
||||
**Installation:**
|
||||
|
||||
```bash
|
||||
pip install cua-cli
|
||||
```
|
||||
338
docs/content/docs/cua/reference/cli/commands.mdx
Normal file
338
docs/content/docs/cua/reference/cli/commands.mdx
Normal file
@@ -0,0 +1,338 @@
|
||||
---
|
||||
title: Command Reference
|
||||
description: Complete reference for all Cua CLI commands
|
||||
---
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
import { VersionBadge } from '@/components/version-selector';
|
||||
|
||||
<VersionBadge version="0.1.0" />
|
||||
|
||||
## Overview
|
||||
|
||||
The Cua CLI provides commands for authentication, sandbox management, image management, skills recording, and MCP server.
|
||||
|
||||
### Command Groups
|
||||
|
||||
| Group | Alias | Description |
|
||||
| --------------- | --------- | ---------------------------------- |
|
||||
| `cua auth` | | Authentication management |
|
||||
| `cua sandbox` | `cua sb` | Sandbox lifecycle management |
|
||||
| `cua image` | `cua img` | Cloud image management |
|
||||
| `cua skills` | | Skills recording and playback |
|
||||
| `cua serve-mcp` | | Start MCP server for AI assistants |
|
||||
|
||||
## Authentication Commands
|
||||
|
||||
### `cua auth login`
|
||||
|
||||
Authenticate with your Cua account.
|
||||
|
||||
```bash
|
||||
# Browser-based login
|
||||
cua auth login
|
||||
|
||||
# Direct API key login
|
||||
cua auth login --api-key sk_cua-api01_...
|
||||
```
|
||||
|
||||
### `cua auth env`
|
||||
|
||||
Export your API key to a `.env` file in the current directory.
|
||||
|
||||
```bash
|
||||
cua auth env
|
||||
```
|
||||
|
||||
### `cua auth logout`
|
||||
|
||||
Remove the stored API key.
|
||||
|
||||
```bash
|
||||
cua auth logout
|
||||
```
|
||||
|
||||
## Sandbox Commands
|
||||
|
||||
All sandbox commands support the `cua sb` alias (e.g., `cua sb list`).
|
||||
|
||||
### `cua sandbox list`
|
||||
|
||||
List all sandboxes.
|
||||
|
||||
```bash
|
||||
cua sandbox list
|
||||
|
||||
# With JSON output
|
||||
cua sandbox list --json
|
||||
|
||||
# Show passwords
|
||||
cua sandbox list --show-passwords
|
||||
```
|
||||
|
||||
**Aliases:** `cua sb ls`, `cua sb ps`
|
||||
|
||||
### `cua sandbox create`
|
||||
|
||||
Create a new sandbox.
|
||||
|
||||
```bash
|
||||
cua sandbox create --os <OS> --size <SIZE> --region <REGION>
|
||||
```
|
||||
|
||||
**Required options:**
|
||||
|
||||
| Option | Values |
|
||||
| ---------- | ---------------------------------------------------------- |
|
||||
| `--os` | `linux`, `windows`, `macos` |
|
||||
| `--size` | `small`, `medium`, `large` |
|
||||
| `--region` | `north-america`, `europe`, `asia-pacific`, `south-america` |
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
cua sandbox create --os linux --size small --region north-america
|
||||
```
|
||||
|
||||
### `cua sandbox get`
|
||||
|
||||
Get details for a specific sandbox.
|
||||
|
||||
```bash
|
||||
cua sandbox get <name>
|
||||
|
||||
# With options
|
||||
cua sandbox get <name> --json
|
||||
cua sandbox get <name> --show-passwords
|
||||
cua sandbox get <name> --show-vnc-url
|
||||
```
|
||||
|
||||
### `cua sandbox start`
|
||||
|
||||
Start a stopped sandbox.
|
||||
|
||||
```bash
|
||||
cua sandbox start <name>
|
||||
```
|
||||
|
||||
### `cua sandbox stop`
|
||||
|
||||
Stop a running sandbox.
|
||||
|
||||
```bash
|
||||
cua sandbox stop <name>
|
||||
```
|
||||
|
||||
### `cua sandbox restart`
|
||||
|
||||
Restart a sandbox.
|
||||
|
||||
```bash
|
||||
cua sandbox restart <name>
|
||||
```
|
||||
|
||||
### `cua sandbox suspend`
|
||||
|
||||
Suspend a sandbox (preserves memory state).
|
||||
|
||||
```bash
|
||||
cua sandbox suspend <name>
|
||||
```
|
||||
|
||||
### `cua sandbox delete`
|
||||
|
||||
Delete a sandbox permanently.
|
||||
|
||||
```bash
|
||||
cua sandbox delete <name>
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
This action is irreversible. All data on the sandbox will be permanently lost.
|
||||
</Callout>
|
||||
|
||||
### `cua sandbox vnc`
|
||||
|
||||
Open the sandbox desktop in your browser.
|
||||
|
||||
```bash
|
||||
cua sandbox vnc <name>
|
||||
```
|
||||
|
||||
**Alias:** `cua sb open <name>`
|
||||
|
||||
## Image Commands
|
||||
|
||||
All image commands support the `cua img` alias.
|
||||
|
||||
### `cua image list`
|
||||
|
||||
List cloud images.
|
||||
|
||||
```bash
|
||||
cua image list
|
||||
|
||||
# JSON output
|
||||
cua image list --json
|
||||
|
||||
# List local images instead
|
||||
cua image list --local
|
||||
```
|
||||
|
||||
**Alias:** `cua img ls`
|
||||
|
||||
### `cua image push`
|
||||
|
||||
Upload a local image to the cloud.
|
||||
|
||||
```bash
|
||||
cua image push <name> --file <path> --tag <tag>
|
||||
```
|
||||
|
||||
### `cua image pull`
|
||||
|
||||
Download an image from the cloud.
|
||||
|
||||
```bash
|
||||
cua image pull <name> --tag <tag> --output <path>
|
||||
```
|
||||
|
||||
### `cua image delete`
|
||||
|
||||
Delete a cloud image.
|
||||
|
||||
```bash
|
||||
cua image delete <name> --tag <tag>
|
||||
|
||||
# Skip confirmation
|
||||
cua image delete <name> --tag <tag> --force
|
||||
```
|
||||
|
||||
## Skills Commands
|
||||
|
||||
Skills are recorded demonstrations that guide agent behavior.
|
||||
|
||||
### `cua skills list`
|
||||
|
||||
List all saved skills.
|
||||
|
||||
```bash
|
||||
cua skills list
|
||||
|
||||
# JSON output
|
||||
cua skills list --json
|
||||
```
|
||||
|
||||
### `cua skills record`
|
||||
|
||||
Record a new skill from a sandbox.
|
||||
|
||||
```bash
|
||||
cua skills record --sandbox <name>
|
||||
|
||||
# With options
|
||||
cua skills record --sandbox <name> --name "my-skill" --description "Does something"
|
||||
cua skills record --sandbox <name> --provider anthropic --model claude-sonnet-4-5-20250514
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Description |
|
||||
| --------------- | --------------------------------------------------- |
|
||||
| `--sandbox` | Sandbox to record from |
|
||||
| `--name` | Skill name (skips prompt) |
|
||||
| `--description` | Skill description (skips prompt) |
|
||||
| `--provider` | LLM provider for captioning (`anthropic`, `openai`) |
|
||||
| `--model` | Model to use for captioning |
|
||||
|
||||
### `cua skills read`
|
||||
|
||||
Display a skill's instructions.
|
||||
|
||||
```bash
|
||||
cua skills read <name>
|
||||
|
||||
# JSON format with trajectory data
|
||||
cua skills read <name> --format json
|
||||
```
|
||||
|
||||
### `cua skills replay`
|
||||
|
||||
Open the recorded video for a skill.
|
||||
|
||||
```bash
|
||||
cua skills replay <name>
|
||||
```
|
||||
|
||||
### `cua skills delete`
|
||||
|
||||
Delete a skill.
|
||||
|
||||
```bash
|
||||
cua skills delete <name>
|
||||
```
|
||||
|
||||
### `cua skills clean`
|
||||
|
||||
Delete all skills (with confirmation).
|
||||
|
||||
```bash
|
||||
cua skills clean
|
||||
```
|
||||
|
||||
## MCP Server
|
||||
|
||||
Run the CLI as an MCP (Model Context Protocol) server for AI assistants like Claude.
|
||||
|
||||
### `cua serve-mcp`
|
||||
|
||||
Start the MCP server.
|
||||
|
||||
```bash
|
||||
cua serve-mcp
|
||||
|
||||
# With specific sandbox
|
||||
cua serve-mcp --sandbox <name>
|
||||
|
||||
# With permission restrictions
|
||||
cua serve-mcp --permissions sandbox:readonly
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Description |
|
||||
| --------------- | ------------------------------------- |
|
||||
| `--sandbox` | Default sandbox for computer commands |
|
||||
| `--permissions` | Permission groups (see below) |
|
||||
|
||||
**Permission groups:**
|
||||
|
||||
| Group | Description |
|
||||
| ------------------- | ---------------------------- |
|
||||
| `all` | All permissions (default) |
|
||||
| `sandbox:all` | Full sandbox management |
|
||||
| `sandbox:readonly` | List and view sandboxes only |
|
||||
| `computer:all` | Full computer control |
|
||||
| `computer:readonly` | Screenshots only |
|
||||
| `skills:all` | Full skills management |
|
||||
| `skills:readonly` | List and read skills only |
|
||||
|
||||
**Example with multiple permissions:**
|
||||
|
||||
```bash
|
||||
cua serve-mcp --permissions "sandbox:all,computer:readonly,skills:list"
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
| --------------------- | -------------------------- |
|
||||
| `CUA_API_KEY` | API key for authentication |
|
||||
| `CUA_SANDBOX` | Default sandbox name |
|
||||
| `CUA_MCP_PERMISSIONS` | Default MCP permissions |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Quickstart Guide](/cua/guide/get-started/quickstart)
|
||||
- [Computer SDK Reference](/cua/reference/computer-sdk)
|
||||
- [Agent SDK Reference](/cua/reference/agent-sdk)
|
||||
249
docs/content/docs/cua/reference/cli/index.mdx
Normal file
249
docs/content/docs/cua/reference/cli/index.mdx
Normal file
@@ -0,0 +1,249 @@
|
||||
---
|
||||
title: Cua CLI API Reference
|
||||
description: Python API reference for the Cua command-line interface
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/python-sdk.ts
|
||||
Source: libs/python/cua-cli/cua_cli
|
||||
Version: 0.1.0
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
|
||||
import { VersionHeader } from '@/components/version-selector';
|
||||
|
||||
<VersionHeader
|
||||
versions={[{"version":"0.1","href":"/cua/reference/cli","isCurrent":true}]}
|
||||
currentVersion="0.1"
|
||||
fullVersion="0.1.0"
|
||||
packageName="cua-cli"
|
||||
/>
|
||||
|
||||
CUA CLI - Unified command-line interface for Computer-Use Agents.
|
||||
|
||||
---
|
||||
|
||||
## main
|
||||
|
||||
Main entry point for CUA CLI.
|
||||
|
||||
### print_error
|
||||
|
||||
```python
|
||||
def print_error(message: str) -> None
|
||||
```
|
||||
|
||||
Print an error message to stderr.
|
||||
|
||||
### create_parser
|
||||
|
||||
```python
|
||||
def create_parser() -> argparse.ArgumentParser
|
||||
```
|
||||
|
||||
Create the main argument parser with all subcommands.
|
||||
|
||||
### main
|
||||
|
||||
```python
|
||||
def main() -> int
|
||||
```
|
||||
|
||||
Main entry point for the CLI.
|
||||
|
||||
---
|
||||
|
||||
## auth
|
||||
|
||||
Authentication module for CUA CLI.
|
||||
|
||||
---
|
||||
|
||||
## CredentialStore
|
||||
|
||||
SQLite-based credential store with WAL mode for concurrent access.
|
||||
|
||||
### Constructor
|
||||
|
||||
```python
|
||||
CredentialStore(self, db_path: Path | None = None)
|
||||
```
|
||||
|
||||
### Attributes
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `db_path` | `Any` | |
|
||||
|
||||
### Methods
|
||||
|
||||
#### CredentialStore.get
|
||||
|
||||
```python
|
||||
def get(self, key: str) -> Optional[str]
|
||||
```
|
||||
|
||||
Get a value from the store.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `key` | `Any` | The key to look up |
|
||||
|
||||
**Returns:** The value, or None if not found
|
||||
|
||||
#### CredentialStore.set
|
||||
|
||||
```python
|
||||
def set(self, key: str, value: str) -> None
|
||||
```
|
||||
|
||||
Set a value in the store.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `key` | `Any` | The key to set |
|
||||
| `value` | `Any` | The value to store |
|
||||
|
||||
#### CredentialStore.delete
|
||||
|
||||
```python
|
||||
def delete(self, key: str) -> bool
|
||||
```
|
||||
|
||||
Delete a value from the store.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `key` | `Any` | The key to delete |
|
||||
|
||||
**Returns:** True if the key was deleted, False if it didn't exist
|
||||
|
||||
#### CredentialStore.clear
|
||||
|
||||
```python
|
||||
def clear(self) -> None
|
||||
```
|
||||
|
||||
Clear all stored credentials.
|
||||
|
||||
### clear_credentials
|
||||
|
||||
```python
|
||||
def clear_credentials() -> None
|
||||
```
|
||||
|
||||
Clear all stored credentials.
|
||||
|
||||
### get_api_key
|
||||
|
||||
```python
|
||||
def get_api_key() -> Optional[str]
|
||||
```
|
||||
|
||||
Get the stored API key.
|
||||
|
||||
First checks CUA_API_KEY environment variable, then falls back to stored credentials.
|
||||
|
||||
**Returns:** The API key, or None if not found
|
||||
|
||||
### save_api_key
|
||||
|
||||
```python
|
||||
def save_api_key(api_key: str) -> None
|
||||
```
|
||||
|
||||
Save an API key to the credential store.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `api_key` | `Any` | The API key to save |
|
||||
|
||||
---
|
||||
|
||||
## utils
|
||||
|
||||
Utility modules for CUA CLI.
|
||||
|
||||
### run_async
|
||||
|
||||
```python
|
||||
def run_async(coro: Coroutine[Any, Any, T]) -> T
|
||||
```
|
||||
|
||||
Run an async coroutine synchronously.
|
||||
|
||||
This is the standard pattern for CLI commands that need to call async code.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `coro` | `Any` | The coroutine to run |
|
||||
|
||||
**Returns:** The result of the coroutine
|
||||
|
||||
### print_error
|
||||
|
||||
```python
|
||||
def print_error(message: str) -> None
|
||||
```
|
||||
|
||||
Print an error message to stderr.
|
||||
|
||||
### print_info
|
||||
|
||||
```python
|
||||
def print_info(message: str) -> None
|
||||
```
|
||||
|
||||
Print an info message.
|
||||
|
||||
### print_json
|
||||
|
||||
```python
|
||||
def print_json(data: Any) -> None
|
||||
```
|
||||
|
||||
Print data as formatted JSON.
|
||||
|
||||
### print_success
|
||||
|
||||
```python
|
||||
def print_success(message: str) -> None
|
||||
```
|
||||
|
||||
Print a success message.
|
||||
|
||||
### print_table
|
||||
|
||||
```python
|
||||
def print_table(data: list[dict[str, Any]], columns: list[tuple[str, str]] | None = None, title: str | None = None) -> None
|
||||
```
|
||||
|
||||
Print data as a formatted table.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `data` | `Any` | List of dictionaries to display |
|
||||
| `columns` | `Any` | List of (key, header) tuples. If None, uses all keys from first item. |
|
||||
| `title` | `Any` | Optional table title |
|
||||
|
||||
### print_warning
|
||||
|
||||
```python
|
||||
def print_warning(message: str) -> None
|
||||
```
|
||||
|
||||
Print a warning message.
|
||||
6
docs/content/docs/cua/reference/cli/meta.json
Normal file
6
docs/content/docs/cua/reference/cli/meta.json
Normal file
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"title": "CLI",
|
||||
"description": "Command-line interface for Cua",
|
||||
"icon": "Terminal",
|
||||
"pages": ["commands", "changelog"]
|
||||
}
|
||||
328
docs/content/docs/cua/reference/computer-sdk/changelog.mdx
Normal file
328
docs/content/docs/cua/reference/computer-sdk/changelog.mdx
Normal file
@@ -0,0 +1,328 @@
|
||||
---
|
||||
title: Changelog
|
||||
description: Release history for Computer SDK
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-changelog.ts
|
||||
Last updated: 2026-02-04
|
||||
*/}
|
||||
|
||||
# Computer SDK Changelog
|
||||
|
||||
All notable changes to the Computer SDK are documented here.
|
||||
|
||||
## 0.5.x
|
||||
|
||||
### v0.5.12 (2026-01-26)
|
||||
|
||||
- Initial release or no path-specific changes found
|
||||
|
||||
### v0.5.11 (2026-01-24)
|
||||
|
||||
- Bump cua-computer to v0.5.11 by @github-actions[bot]
|
||||
- Setup UV as venv manager for computer ([#789](https://github.com/trycua/cua/pull/789)) by @synacktraa
|
||||
|
||||
### v0.5.10 (2026-01-17)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.5.7 (2026-01-17)
|
||||
|
||||
- Bump cua-computer to v0.5.7 by @github-actions[bot]
|
||||
- fix(computer): prevent data loss when tracing.stop path conflicts with trace directory ([#814](https://github.com/trycua/cua/pull/814)) by @Harsh Verma
|
||||
- Improve Computer API Server connection warnings and timeout errors ([#803](https://github.com/trycua/cua/pull/803)) by @Fizza Mukhtar
|
||||
- feat(computer): add OpenTelemetry instrumentation ([#663](https://github.com/trycua/cua/pull/663)) by @r33drichards
|
||||
|
||||
### v0.5.6 (2026-01-12)
|
||||
|
||||
- Initial release or no path-specific changes found
|
||||
|
||||
### v0.5.5 (2026-01-12)
|
||||
|
||||
- Initial release or no path-specific changes found
|
||||
|
||||
### v0.5.4 (2026-01-12)
|
||||
|
||||
- Bump cua-computer to v0.5.3 by @github-actions[bot]
|
||||
- Bump cua-computer to v0.5.2 by @github-actions[bot]
|
||||
- refactor(docs): reorganize lume/cua docs and standardize READMEs ([#752](https://github.com/trycua/cua/pull/752)) by @Francesco Bonacci
|
||||
- feat(lume,ci): add unattended VM setup and reorganize CI/CD workflows ([#729](https://github.com/trycua/cua/pull/729)) by @Francesco Bonacci
|
||||
- update dead links due to docs update by @Sarina Li
|
||||
- pyautogui cleanup by @Adam
|
||||
- Revert "refractor docs into 6 sections" by @Adam
|
||||
- refractor docs into 6 sections by @Adam
|
||||
|
||||
## 0.4.x
|
||||
|
||||
### v0.4.11 (2025-10-29)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
- Docs/improve readme by @jamesmurdza in https://github.com/trycua/cua/pull/512
|
||||
- Feature/version bump workflows by @r33drichards in https://github.com/trycua/cua/pull/511
|
||||
- Support `display` and `ephemeral` in Docker provider by @ddupont808 in https://github.com/trycua/cua/pull/514
|
||||
- Fix markdown formatting in docs by @jamesmurdza in https://github.com/trycua/cua/pull/523
|
||||
- Jagjeevan's Fix + Merged Main for 4o Model Fix by @sarinali in https://github.com/trycua/cua/pull/522
|
||||
- fix: Added GPT-4o compatibility for screenshot actions with text parameter by @JagjeevanAK in https://github.com/trycua/cua/pull/422
|
||||
- Remove PyLume code and examples by @jamesmurdza in https://github.com/trycua/cua/pull/435
|
||||
- Remove PyLume library by @jamesmurdza in https://github.com/trycua/cua/pull/527
|
||||
- Add test infrastructure with CI/CD #478 by @AceAtDev in https://github.com/trycua/cua/pull/491
|
||||
- Feature/agent loop test by @YeIIcw in https://github.com/trycua/cua/pull/528
|
||||
- Update Agent Loop Test by @YeIIcw in https://github.com/trycua/cua/pull/530
|
||||
- Fix/omniparser predict refactor by @sarinali in https://github.com/trycua/cua/pull/529
|
||||
- Fix agent test condition trigger by @YeIIcw in https://github.com/trycua/cua/pull/531
|
||||
- Fix/agent loop test by @YeIIcw in https://github.com/trycua/cua/pull/532
|
||||
- Add desktop and window management commands to computer interface by @ddupont808 in https://github.com/trycua/cua/pull/516
|
||||
|
||||
### v0.4.10 (2025-10-14)
|
||||
|
||||
- Fix XFCE Password Prompts and Lock Screen Issues by @f-trycua in https://github.com/trycua/cua/pull/466
|
||||
- Add Cloud VM Management API by @ddupont808 in https://github.com/trycua/cua/pull/452
|
||||
|
||||
### v0.4.8 (2025-10-12)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.4.7 (2025-10-03)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.4.6 (2025-09-24)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
- 🔧 Improve HUD eval script: auto-discover .env and simplify usage by @YeIIcw in https://github.com/trycua/cua/pull/419
|
||||
- Fix Windows Sandbox errors by @ddupont808 in https://github.com/trycua/cua/pull/424
|
||||
|
||||
New Contributors
|
||||
|
||||
- @YeIIcw made their first contribution in https://github.com/trycua/cua/pull/419
|
||||
- @JagjeevanAK made their first contribution in https://github.com/trycua/cua/pull/420
|
||||
|
||||
### v0.4.5 (2025-09-05)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
- Fix x/y scrolling by @ddupont808 in https://github.com/trycua/cua/pull/393
|
||||
- Fix invalid image error with some providers (i.e. WinSandbox)
|
||||
- Reference documentation batch by @onel in https://github.com/trycua/cua/pull/390
|
||||
|
||||
### v0.4.4 (2025-08-19)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
- Update agent/computer SDKs to match changes in telemetry SDK by @jamesmurdza in https://github.com/trycua/cua/pull/355
|
||||
- Bugfixes - Removed slashes from container name by @ddupont808 in https://github.com/trycua/cua/pull/358
|
||||
|
||||
### v0.4.3 (2025-08-15)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
- Fixed bug where the `image` kwarg would be ignored
|
||||
|
||||
### v0.4.2 (2025-08-14)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
- [Computer] Add Docker as a local VM provider by @ddupont808 in https://github.com/trycua/cua/pull/339
|
||||
|
||||
### v0.4.1 (2025-08-05)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.4.0 (2025-07-28)
|
||||
|
||||
Bumped `cua-computer` to use latest `cua-core`
|
||||
|
||||
## 0.3.x
|
||||
|
||||
### v0.3.7 (2025-07-16)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.3.6 (2025-07-16)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.3.5 (2025-07-10)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.3.4 (2025-07-03)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.3.3 (2025-07-03)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.3.2 (2025-07-03)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.3.1 (2025-07-01)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.3.0 (2025-06-25)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
## 0.2.x
|
||||
|
||||
### v0.2.13 (2025-06-24)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.12 (2025-06-20)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.11 (2025-06-18)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.10 (2025-06-10)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
- Removed warning when calling `start_vm` on the CloudProvider
|
||||
- Add disconnect() method for Computer
|
||||
- Fixed `file_exists` and `directory_exists` not being implemented in the computer-server
|
||||
- Added keyboard/mouse primitives ( `mouse_up`, `mouse_down`, `key_up`, `key_down` )
|
||||
- Added file system commands to computer interface
|
||||
- Added file system interface pytests
|
||||
- Improved computer interface accessibility tree output on macOS, now includes menubar and dock items, along with preserving z-ordering
|
||||
- Increased timeout for web socket commands due to a TimeoutError if the accessibility tree takes longer than 30 seconds to crawl
|
||||
|
||||
**Changes reference:**
|
||||
|
||||
```py
|
||||
... old actions haven't changed
|
||||
|
||||
Disconnect from computer interface / cleanup websocket resources
|
||||
await computer.disconnect()
|
||||
|
||||
New mouse actions
|
||||
await computer.interface.mouse_down(x, y, button="left") # Press and hold a mouse button
|
||||
await computer.interface.mouse_up(x, y, button="left") # Release a mouse button
|
||||
|
||||
New keyboard actions
|
||||
await computer.interface.key_down("command") # Press and hold a key
|
||||
await computer.interface.key_up("command") # Release a key
|
||||
|
||||
New scrolling actions
|
||||
await computer.interface.scroll(x, y) # Scroll the mouse wheel
|
||||
|
||||
New file-system commands
|
||||
Fixed: await computer.interface.file_exists(path) # Check if file exists
|
||||
Fixed: await computer.interface.directory_exists(path) # Check if directory exists
|
||||
await computer.interface.read_text(path) # Read file content
|
||||
await computer.interface.write_text(path, content) # Write file content
|
||||
await computer.interface.read_bytes(path) # Read file content as bytes
|
||||
await computer.interface.write_bytes(path, content) # Write file content as bytes
|
||||
await computer.interface.delete_file(path) # Delete file
|
||||
await computer.interface.create_dir(path) # Create directory
|
||||
await computer.interface.delete_dir(path) # Delete directory
|
||||
await computer.interface.list_dir(path) # List directory contents
|
||||
```
|
||||
|
||||
### v0.2.9 (2025-06-05)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.8 (2025-05-31)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.7 (2025-05-28)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.6 (2025-05-28)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.5 (2025-05-28)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.4 (2025-05-28)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.3 (2025-05-28)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.2 (2025-05-16)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.1 (2025-05-14)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.2.0 (2025-05-14)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
## 0.1.x
|
||||
|
||||
### v0.1.29 (2025-05-12)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.28 (2025-05-10)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.27 (2025-05-10)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.26 (2025-05-10)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.25 (2025-05-07)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.24 (2025-04-29)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.23 (2025-04-22)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.22 (2025-04-15)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.21 (2025-03-30)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.20 (2025-03-30)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.19 (2025-03-30)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.18 (2025-03-24)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.7 (2025-03-19)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
|
||||
### v0.1.6 (2025-03-17)
|
||||
|
||||
**Dependencies:** pylume: latest
|
||||
File diff suppressed because it is too large
Load Diff
@@ -2,5 +2,5 @@
|
||||
"title": "Computer SDK",
|
||||
"description": "Python API for sandboxed desktop environments",
|
||||
"icon": "Monitor",
|
||||
"pages": ["index"]
|
||||
"pages": ["changelog"]
|
||||
}
|
||||
|
||||
209
docs/content/docs/cua/reference/computer-sdk/v0.3/api.mdx
Normal file
209
docs/content/docs/cua/reference/computer-sdk/v0.3/api.mdx
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
title: Computer SDK v0.3 API Reference
|
||||
description: API reference for Computer SDK version 0.3
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-versioned-docs.ts
|
||||
Source tag: computer-v0.3.7
|
||||
Version: 0.3.7
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
|
||||
<Callout type="warn">
|
||||
This is documentation for **v0.3**. [View latest version](/cua/reference/computer-sdk).
|
||||
</Callout>
|
||||
|
||||
<div className="flex items-center gap-2 mb-6">
|
||||
<span className="px-2 py-1 bg-amber-100 dark:bg-amber-900 text-amber-800 dark:text-amber-200 rounded text-sm font-mono">
|
||||
v0.3.7
|
||||
</span>
|
||||
<span className="text-sm text-fd-muted-foreground">pip install cua-computer==0.3.7</span>
|
||||
</div>
|
||||
|
||||
CUA Computer Interface for cross-platform computer control.
|
||||
|
||||
## Classes
|
||||
|
||||
| Class | Description |
|
||||
| ---------------- | ------------------------------------------------------------- |
|
||||
| `Computer` | Computer is the main class for interacting with the computer. |
|
||||
| `VMProviderType` | Enum of supported VM provider types. |
|
||||
|
||||
## Computer
|
||||
|
||||
Computer is the main class for interacting with the computer.
|
||||
|
||||
### Methods
|
||||
|
||||
#### Computer.create_desktop_from_apps
|
||||
|
||||
```python
|
||||
def create_desktop_from_apps(self, apps)
|
||||
```
|
||||
|
||||
Create a virtual desktop from a list of app names, returning a DioramaComputer
|
||||
that proxies Diorama.Interface but uses diorama_cmds via the computer interface.
|
||||
|
||||
Args:
|
||||
apps (list[str]): List of application names to include in the desktop.
|
||||
Returns:
|
||||
DioramaComputer: A proxy object with the Diorama interface, but using diorama_cmds.
|
||||
|
||||
#### Computer.run
|
||||
|
||||
```python
|
||||
async def run(self) -> Optional[str]
|
||||
```
|
||||
|
||||
Initialize the VM and computer interface.
|
||||
|
||||
#### Computer.disconnect
|
||||
|
||||
```python
|
||||
async def disconnect(self) -> None
|
||||
```
|
||||
|
||||
Disconnect from the computer's WebSocket interface.
|
||||
|
||||
#### Computer.stop
|
||||
|
||||
```python
|
||||
async def stop(self) -> None
|
||||
```
|
||||
|
||||
Disconnect from the computer's WebSocket interface and stop the computer.
|
||||
|
||||
#### Computer.get_ip
|
||||
|
||||
```python
|
||||
async def get_ip(self, max_retries: int = 15, retry_delay: int = 3) -> str
|
||||
```
|
||||
|
||||
Get the IP address of the VM or localhost if using host computer server.
|
||||
|
||||
This method delegates to the provider's get_ip method, which waits indefinitely
|
||||
until the VM has a valid IP address.
|
||||
|
||||
Args:
|
||||
max_retries: Unused parameter, kept for backward compatibility
|
||||
retry_delay: Delay between retries in seconds (default: 2)
|
||||
|
||||
Returns:
|
||||
IP address of the VM or localhost if using host computer server
|
||||
|
||||
#### Computer.wait_vm_ready
|
||||
|
||||
```python
|
||||
async def wait_vm_ready(self) -> Optional[Dict[str, Any]]
|
||||
```
|
||||
|
||||
Wait for VM to be ready with an IP address.
|
||||
|
||||
Returns:
|
||||
VM status information or None if using host computer server.
|
||||
|
||||
#### Computer.update
|
||||
|
||||
```python
|
||||
async def update(self, cpu: Optional[int] = None, memory: Optional[str] = None)
|
||||
```
|
||||
|
||||
Update VM settings.
|
||||
|
||||
#### Computer.get_screenshot_size
|
||||
|
||||
```python
|
||||
def get_screenshot_size(self, screenshot: bytes) -> Dict[str, int]
|
||||
```
|
||||
|
||||
Get the dimensions of a screenshot.
|
||||
|
||||
Args:
|
||||
screenshot: The screenshot bytes
|
||||
|
||||
Returns:
|
||||
Dict[str, int]: Dictionary containing 'width' and 'height' of the image
|
||||
|
||||
#### Computer.to_screen_coordinates
|
||||
|
||||
```python
|
||||
async def to_screen_coordinates(self, x: float, y: float) -> tuple[float, float]
|
||||
```
|
||||
|
||||
Convert normalized coordinates to screen coordinates.
|
||||
|
||||
Args:
|
||||
x: X coordinate between 0 and 1
|
||||
y: Y coordinate between 0 and 1
|
||||
|
||||
Returns:
|
||||
tuple[float, float]: Screen coordinates (x, y)
|
||||
|
||||
#### Computer.to_screenshot_coordinates
|
||||
|
||||
```python
|
||||
async def to_screenshot_coordinates(self, x: float, y: float) -> tuple[float, float]
|
||||
```
|
||||
|
||||
Convert screen coordinates to screenshot coordinates.
|
||||
|
||||
Args:
|
||||
x: X coordinate in screen space
|
||||
y: Y coordinate in screen space
|
||||
|
||||
Returns:
|
||||
tuple[float, float]: (x, y) coordinates in screenshot space
|
||||
|
||||
#### Computer.venv_install
|
||||
|
||||
```python
|
||||
async def venv_install(self, venv_name: str, requirements: list[str])
|
||||
```
|
||||
|
||||
Install packages in a virtual environment.
|
||||
|
||||
Args:
|
||||
venv_name: Name of the virtual environment
|
||||
requirements: List of package requirements to install
|
||||
|
||||
Returns:
|
||||
Tuple of (stdout, stderr) from the installation command
|
||||
|
||||
#### Computer.venv_cmd
|
||||
|
||||
```python
|
||||
async def venv_cmd(self, venv_name: str, command: str)
|
||||
```
|
||||
|
||||
Execute a shell command in a virtual environment.
|
||||
|
||||
Args:
|
||||
venv_name: Name of the virtual environment
|
||||
command: Shell command to execute in the virtual environment
|
||||
|
||||
Returns:
|
||||
Tuple of (stdout, stderr) from the command execution
|
||||
|
||||
#### Computer.venv_exec
|
||||
|
||||
```python
|
||||
async def venv_exec(self, venv_name: str, python_func, args = (), kwargs = {})
|
||||
```
|
||||
|
||||
Execute Python function in a virtual environment using source code extraction.
|
||||
|
||||
Args:
|
||||
venv_name: Name of the virtual environment
|
||||
python_func: A callable function to execute
|
||||
\*args: Positional arguments to pass to the function
|
||||
\*\*kwargs: Keyword arguments to pass to the function
|
||||
|
||||
Returns:
|
||||
The result of the function execution, or raises any exception that occurred
|
||||
|
||||
## VMProviderType
|
||||
|
||||
Enum of supported VM provider types.
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "v0.3",
|
||||
"description": "Computer SDK v0.3 API Reference",
|
||||
"pages": ["api"]
|
||||
}
|
||||
328
docs/content/docs/cua/reference/computer-sdk/v0.4/api.mdx
Normal file
328
docs/content/docs/cua/reference/computer-sdk/v0.4/api.mdx
Normal file
@@ -0,0 +1,328 @@
|
||||
---
|
||||
title: Computer SDK v0.4 API Reference
|
||||
description: API reference for Computer SDK version 0.4
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-versioned-docs.ts
|
||||
Source tag: computer-v0.4.19
|
||||
Version: 0.4.19
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
|
||||
<Callout type="warn">
|
||||
This is documentation for **v0.4**. [View latest version](/cua/reference/computer-sdk).
|
||||
</Callout>
|
||||
|
||||
<div className="flex items-center gap-2 mb-6">
|
||||
<span className="px-2 py-1 bg-amber-100 dark:bg-amber-900 text-amber-800 dark:text-amber-200 rounded text-sm font-mono">
|
||||
v0.4.19
|
||||
</span>
|
||||
<span className="text-sm text-fd-muted-foreground">pip install cua-computer==0.4.19</span>
|
||||
</div>
|
||||
|
||||
CUA Computer Interface for cross-platform computer control.
|
||||
|
||||
## Classes
|
||||
|
||||
| Class | Description |
|
||||
| ---------------- | ------------------------------------------------------------- |
|
||||
| `Computer` | Computer is the main class for interacting with the computer. |
|
||||
| `VMProviderType` | Enum of supported VM provider types. |
|
||||
|
||||
## Computer
|
||||
|
||||
Computer is the main class for interacting with the computer.
|
||||
|
||||
### Methods
|
||||
|
||||
#### Computer.create_desktop_from_apps
|
||||
|
||||
```python
|
||||
def create_desktop_from_apps(self, apps)
|
||||
```
|
||||
|
||||
Create a virtual desktop from a list of app names, returning a DioramaComputer
|
||||
that proxies Diorama.Interface but uses diorama_cmds via the computer interface.
|
||||
|
||||
Args:
|
||||
apps (list[str]): List of application names to include in the desktop.
|
||||
Returns:
|
||||
DioramaComputer: A proxy object with the Diorama interface, but using diorama_cmds.
|
||||
|
||||
#### Computer.run
|
||||
|
||||
```python
|
||||
async def run(self) -> Optional[str]
|
||||
```
|
||||
|
||||
Initialize the VM and computer interface.
|
||||
|
||||
#### Computer.disconnect
|
||||
|
||||
```python
|
||||
async def disconnect(self) -> None
|
||||
```
|
||||
|
||||
Disconnect from the computer's WebSocket interface.
|
||||
|
||||
#### Computer.stop
|
||||
|
||||
```python
|
||||
async def stop(self) -> None
|
||||
```
|
||||
|
||||
Disconnect from the computer's WebSocket interface and stop the computer.
|
||||
|
||||
#### Computer.start
|
||||
|
||||
```python
|
||||
async def start(self) -> None
|
||||
```
|
||||
|
||||
Start the computer.
|
||||
|
||||
#### Computer.restart
|
||||
|
||||
```python
|
||||
async def restart(self) -> None
|
||||
```
|
||||
|
||||
Restart the computer.
|
||||
|
||||
If using a VM provider that supports restart, this will issue a restart
|
||||
without tearing down the provider context, then reconnect the interface.
|
||||
Falls back to stop()+run() when a provider restart is not available.
|
||||
|
||||
#### Computer.get_ip
|
||||
|
||||
```python
|
||||
async def get_ip(self, max_retries: int = 15, retry_delay: int = 3) -> str
|
||||
```
|
||||
|
||||
Get the IP address of the VM or localhost if using host computer server.
|
||||
|
||||
This method delegates to the provider's get_ip method, which waits indefinitely
|
||||
until the VM has a valid IP address.
|
||||
|
||||
Args:
|
||||
max_retries: Unused parameter, kept for backward compatibility
|
||||
retry_delay: Delay between retries in seconds (default: 2)
|
||||
|
||||
Returns:
|
||||
IP address of the VM or localhost if using host computer server
|
||||
|
||||
#### Computer.wait_vm_ready
|
||||
|
||||
```python
|
||||
async def wait_vm_ready(self) -> Optional[Dict[str, Any]]
|
||||
```
|
||||
|
||||
Wait for VM to be ready with an IP address.
|
||||
|
||||
Returns:
|
||||
VM status information or None if using host computer server.
|
||||
|
||||
#### Computer.update
|
||||
|
||||
```python
|
||||
async def update(self, cpu: Optional[int] = None, memory: Optional[str] = None)
|
||||
```
|
||||
|
||||
Update VM settings.
|
||||
|
||||
#### Computer.get_screenshot_size
|
||||
|
||||
```python
|
||||
def get_screenshot_size(self, screenshot: bytes) -> Dict[str, int]
|
||||
```
|
||||
|
||||
Get the dimensions of a screenshot.
|
||||
|
||||
Args:
|
||||
screenshot: The screenshot bytes
|
||||
|
||||
Returns:
|
||||
Dict[str, int]: Dictionary containing 'width' and 'height' of the image
|
||||
|
||||
#### Computer.to_screen_coordinates
|
||||
|
||||
```python
|
||||
async def to_screen_coordinates(self, x: float, y: float) -> tuple[float, float]
|
||||
```
|
||||
|
||||
Convert normalized coordinates to screen coordinates.
|
||||
|
||||
Args:
|
||||
x: X coordinate between 0 and 1
|
||||
y: Y coordinate between 0 and 1
|
||||
|
||||
Returns:
|
||||
tuple[float, float]: Screen coordinates (x, y)
|
||||
|
||||
#### Computer.to_screenshot_coordinates
|
||||
|
||||
```python
|
||||
async def to_screenshot_coordinates(self, x: float, y: float) -> tuple[float, float]
|
||||
```
|
||||
|
||||
Convert screen coordinates to screenshot coordinates.
|
||||
|
||||
Args:
|
||||
x: X coordinate in screen space
|
||||
y: Y coordinate in screen space
|
||||
|
||||
Returns:
|
||||
tuple[float, float]: (x, y) coordinates in screenshot space
|
||||
|
||||
#### Computer.playwright_exec
|
||||
|
||||
```python
|
||||
async def playwright_exec(self, command: str, params: Optional[Dict] = None) -> Dict[str, Any]
|
||||
```
|
||||
|
||||
Execute a Playwright browser command.
|
||||
|
||||
Args:
|
||||
command: The browser command to execute (visit_url, click, type, scroll, web_search)
|
||||
params: Command parameters
|
||||
|
||||
Returns:
|
||||
Dict containing the command result
|
||||
|
||||
Examples: # Navigate to a URL
|
||||
await computer.playwright_exec("visit_url", \{"url": "https://example.com"\})
|
||||
|
||||
# Click at coordinates
|
||||
await computer.playwright_exec("click", \{"x": 100, "y": 200\})
|
||||
|
||||
# Type text
|
||||
await computer.playwright_exec("type", \{"text": "Hello, world!"\})
|
||||
|
||||
# Scroll
|
||||
await computer.playwright_exec("scroll", \{"delta_x": 0, "delta_y": -100\})
|
||||
|
||||
# Web search
|
||||
await computer.playwright_exec("web_search", \{"query": "computer use agent"\})
|
||||
|
||||
#### Computer.venv_install
|
||||
|
||||
```python
|
||||
async def venv_install(self, venv_name: str, requirements: list[str])
|
||||
```
|
||||
|
||||
Install packages in a virtual environment.
|
||||
|
||||
Args:
|
||||
venv_name: Name of the virtual environment
|
||||
requirements: List of package requirements to install
|
||||
|
||||
Returns:
|
||||
Tuple of (stdout, stderr) from the installation command
|
||||
|
||||
#### Computer.pip_install
|
||||
|
||||
```python
|
||||
async def pip_install(self, requirements: list[str])
|
||||
```
|
||||
|
||||
Install packages using the system Python/pip (no venv).
|
||||
|
||||
Args:
|
||||
requirements: List of package requirements to install globally/user site.
|
||||
|
||||
Returns:
|
||||
Tuple of (stdout, stderr) from the installation command
|
||||
|
||||
#### Computer.venv_cmd
|
||||
|
||||
```python
|
||||
async def venv_cmd(self, venv_name: str, command: str)
|
||||
```
|
||||
|
||||
Execute a shell command in a virtual environment.
|
||||
|
||||
Args:
|
||||
venv_name: Name of the virtual environment
|
||||
command: Shell command to execute in the virtual environment
|
||||
|
||||
Returns:
|
||||
Tuple of (stdout, stderr) from the command execution
|
||||
|
||||
#### Computer.venv_exec
|
||||
|
||||
```python
|
||||
async def venv_exec(self, venv_name: str, python_func, args = (), kwargs = {})
|
||||
```
|
||||
|
||||
Execute Python function in a virtual environment using source code extraction.
|
||||
|
||||
Args:
|
||||
venv_name: Name of the virtual environment
|
||||
python_func: A callable function to execute
|
||||
\*args: Positional arguments to pass to the function
|
||||
\*\*kwargs: Keyword arguments to pass to the function
|
||||
|
||||
Returns:
|
||||
The result of the function execution, or raises any exception that occurred
|
||||
|
||||
#### Computer.venv_exec_background
|
||||
|
||||
```python
|
||||
async def venv_exec_background(self, venv_name: str, python_func, args = (), requirements: Optional[List[str]] = None, kwargs = {}) -> int
|
||||
```
|
||||
|
||||
Run the Python function in the venv in the background and return the PID.
|
||||
|
||||
Uses a short launcher Python that spawns a detached child and exits immediately.
|
||||
|
||||
#### Computer.python_exec
|
||||
|
||||
```python
|
||||
async def python_exec(self, python_func, args = (), kwargs = {})
|
||||
```
|
||||
|
||||
Execute a Python function using the system Python (no venv).
|
||||
|
||||
Uses source extraction and base64 transport, mirroring venv_exec but
|
||||
without virtual environment activation.
|
||||
|
||||
Returns the function result or raises a reconstructed exception with
|
||||
remote traceback context appended.
|
||||
|
||||
#### Computer.python_exec_background
|
||||
|
||||
```python
|
||||
async def python_exec_background(self, python_func, args = (), requirements: Optional[List[str]] = None, kwargs = {}) -> int
|
||||
```
|
||||
|
||||
Run a Python function with the system interpreter in the background and return PID.
|
||||
|
||||
Uses a short launcher Python that spawns a detached child and exits immediately.
|
||||
|
||||
#### Computer.python_command
|
||||
|
||||
```python
|
||||
def python_command(self, requirements: Optional[List[str]] = None, venv_name: str = 'default', use_system_python: bool = False, background: bool = False) -> Callable[[Callable[P, R]], Callable[P, Awaitable[R]]]
|
||||
```
|
||||
|
||||
Decorator to execute a Python function remotely in this Computer's venv.
|
||||
|
||||
This mirrors `computer.helpers.sandboxed()` but binds to this instance and
|
||||
optionally ensures required packages are installed before execution.
|
||||
|
||||
Args:
|
||||
requirements: Packages to install in the virtual environment.
|
||||
venv_name: Name of the virtual environment to use.
|
||||
use_system_python: If True, use the system Python/pip instead of a venv.
|
||||
background: If True, run the function detached and return the child PID immediately.
|
||||
|
||||
Returns:
|
||||
A decorator that turns a local function into an async callable which
|
||||
runs remotely and returns the function's result.
|
||||
|
||||
## VMProviderType
|
||||
|
||||
Enum of supported VM provider types.
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "v0.4",
|
||||
"description": "Computer SDK v0.4 API Reference",
|
||||
"pages": ["api"]
|
||||
}
|
||||
328
docs/content/docs/cua/reference/computer-sdk/v0.5/api.mdx
Normal file
328
docs/content/docs/cua/reference/computer-sdk/v0.5/api.mdx
Normal file
@@ -0,0 +1,328 @@
|
||||
---
|
||||
title: Computer SDK v0.5 API Reference
|
||||
description: API reference for Computer SDK version 0.5
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-versioned-docs.ts
|
||||
Source tag: computer-v0.5.12
|
||||
Version: 0.5.12
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
|
||||
<Callout type="warn">
|
||||
This is documentation for **v0.5**. [View latest version](/cua/reference/computer-sdk).
|
||||
</Callout>
|
||||
|
||||
<div className="flex items-center gap-2 mb-6">
|
||||
<span className="px-2 py-1 bg-amber-100 dark:bg-amber-900 text-amber-800 dark:text-amber-200 rounded text-sm font-mono">
|
||||
v0.5.12
|
||||
</span>
|
||||
<span className="text-sm text-fd-muted-foreground">pip install cua-computer==0.5.12</span>
|
||||
</div>
|
||||
|
||||
Cua Computer Interface for cross-platform computer control.
|
||||
|
||||
## Classes
|
||||
|
||||
| Class | Description |
|
||||
| ---------------- | ------------------------------------------------------------- |
|
||||
| `Computer` | Computer is the main class for interacting with the computer. |
|
||||
| `VMProviderType` | Enum of supported VM provider types. |
|
||||
|
||||
## Computer
|
||||
|
||||
Computer is the main class for interacting with the computer.
|
||||
|
||||
### Methods
|
||||
|
||||
#### Computer.create_desktop_from_apps
|
||||
|
||||
```python
|
||||
def create_desktop_from_apps(self, apps)
|
||||
```
|
||||
|
||||
Create a virtual desktop from a list of app names, returning a DioramaComputer
|
||||
that proxies Diorama.Interface but uses diorama_cmds via the computer interface.
|
||||
|
||||
Args:
|
||||
apps (list[str]): List of application names to include in the desktop.
|
||||
Returns:
|
||||
DioramaComputer: A proxy object with the Diorama interface, but using diorama_cmds.
|
||||
|
||||
#### Computer.run
|
||||
|
||||
```python
|
||||
async def run(self) -> Optional[str]
|
||||
```
|
||||
|
||||
Initialize the VM and computer interface.
|
||||
|
||||
#### Computer.disconnect
|
||||
|
||||
```python
|
||||
async def disconnect(self) -> None
|
||||
```
|
||||
|
||||
Disconnect from the computer's WebSocket interface.
|
||||
|
||||
#### Computer.stop
|
||||
|
||||
```python
|
||||
async def stop(self) -> None
|
||||
```
|
||||
|
||||
Disconnect from the computer's WebSocket interface and stop the computer.
|
||||
|
||||
#### Computer.start
|
||||
|
||||
```python
|
||||
async def start(self) -> None
|
||||
```
|
||||
|
||||
Start the computer.
|
||||
|
||||
#### Computer.restart
|
||||
|
||||
```python
|
||||
async def restart(self) -> None
|
||||
```
|
||||
|
||||
Restart the computer.
|
||||
|
||||
If using a VM provider that supports restart, this will issue a restart
|
||||
without tearing down the provider context, then reconnect the interface.
|
||||
Falls back to stop()+run() when a provider restart is not available.
|
||||
|
||||
#### Computer.get_ip
|
||||
|
||||
```python
|
||||
async def get_ip(self, max_retries: int = 15, retry_delay: int = 3) -> str
|
||||
```
|
||||
|
||||
Get the IP address of the VM or localhost if using host computer server.
|
||||
|
||||
This method delegates to the provider's get_ip method, which waits indefinitely
|
||||
until the VM has a valid IP address.
|
||||
|
||||
Args:
|
||||
max_retries: Unused parameter, kept for backward compatibility
|
||||
retry_delay: Delay between retries in seconds (default: 2)
|
||||
|
||||
Returns:
|
||||
IP address of the VM or localhost if using host computer server
|
||||
|
||||
#### Computer.wait_vm_ready
|
||||
|
||||
```python
|
||||
async def wait_vm_ready(self) -> Optional[Dict[str, Any]]
|
||||
```
|
||||
|
||||
Wait for VM to be ready with an IP address.
|
||||
|
||||
Returns:
|
||||
VM status information or None if using host computer server.
|
||||
|
||||
#### Computer.update
|
||||
|
||||
```python
|
||||
async def update(self, cpu: Optional[int] = None, memory: Optional[str] = None)
|
||||
```
|
||||
|
||||
Update VM settings.
|
||||
|
||||
#### Computer.get_screenshot_size
|
||||
|
||||
```python
|
||||
def get_screenshot_size(self, screenshot: bytes) -> Dict[str, int]
|
||||
```
|
||||
|
||||
Get the dimensions of a screenshot.
|
||||
|
||||
Args:
|
||||
screenshot: The screenshot bytes
|
||||
|
||||
Returns:
|
||||
Dict[str, int]: Dictionary containing 'width' and 'height' of the image
|
||||
|
||||
#### Computer.to_screen_coordinates
|
||||
|
||||
```python
|
||||
async def to_screen_coordinates(self, x: float, y: float) -> tuple[float, float]
|
||||
```
|
||||
|
||||
Convert normalized coordinates to screen coordinates.
|
||||
|
||||
Args:
|
||||
x: X coordinate between 0 and 1
|
||||
y: Y coordinate between 0 and 1
|
||||
|
||||
Returns:
|
||||
tuple[float, float]: Screen coordinates (x, y)
|
||||
|
||||
#### Computer.to_screenshot_coordinates
|
||||
|
||||
```python
|
||||
async def to_screenshot_coordinates(self, x: float, y: float) -> tuple[float, float]
|
||||
```
|
||||
|
||||
Convert screen coordinates to screenshot coordinates.
|
||||
|
||||
Args:
|
||||
x: X coordinate in screen space
|
||||
y: Y coordinate in screen space
|
||||
|
||||
Returns:
|
||||
tuple[float, float]: (x, y) coordinates in screenshot space
|
||||
|
||||
#### Computer.playwright_exec
|
||||
|
||||
```python
|
||||
async def playwright_exec(self, command: str, params: Optional[Dict] = None) -> Dict[str, Any]
|
||||
```
|
||||
|
||||
Execute a Playwright browser command.
|
||||
|
||||
Args:
|
||||
command: The browser command to execute (visit_url, click, type, scroll, web_search)
|
||||
params: Command parameters
|
||||
|
||||
Returns:
|
||||
Dict containing the command result
|
||||
|
||||
Examples: # Navigate to a URL
|
||||
await computer.playwright_exec("visit_url", \{"url": "https://example.com"\})
|
||||
|
||||
# Click at coordinates
|
||||
await computer.playwright_exec("click", \{"x": 100, "y": 200\})
|
||||
|
||||
# Type text
|
||||
await computer.playwright_exec("type", \{"text": "Hello, world!"\})
|
||||
|
||||
# Scroll
|
||||
await computer.playwright_exec("scroll", \{"delta_x": 0, "delta_y": -100\})
|
||||
|
||||
# Web search
|
||||
await computer.playwright_exec("web_search", \{"query": "computer use agent"\})
|
||||
|
||||
#### Computer.venv_install
|
||||
|
||||
```python
|
||||
async def venv_install(self, venv_name: str, requirements: list[str])
|
||||
```
|
||||
|
||||
Install packages in a UV project.
|
||||
|
||||
Args:
|
||||
venv_name: Name of the UV project
|
||||
requirements: List of package requirements to install
|
||||
|
||||
Returns:
|
||||
Tuple of (stdout, stderr) from the installation command
|
||||
|
||||
#### Computer.pip_install
|
||||
|
||||
```python
|
||||
async def pip_install(self, requirements: list[str])
|
||||
```
|
||||
|
||||
Install packages using the system Python with UV (no venv).
|
||||
|
||||
Args:
|
||||
requirements: List of package requirements to install globally/user site.
|
||||
|
||||
Returns:
|
||||
Tuple of (stdout, stderr) from the installation command
|
||||
|
||||
#### Computer.venv_cmd
|
||||
|
||||
```python
|
||||
async def venv_cmd(self, venv_name: str, command: str)
|
||||
```
|
||||
|
||||
Execute a shell command in a UV project.
|
||||
|
||||
Args:
|
||||
venv_name: Name of the UV project
|
||||
command: Shell command to execute in the UV project
|
||||
|
||||
Returns:
|
||||
Tuple of (stdout, stderr) from the command execution
|
||||
|
||||
#### Computer.venv_exec
|
||||
|
||||
```python
|
||||
async def venv_exec(self, venv_name: str, python_func, args = (), kwargs = {})
|
||||
```
|
||||
|
||||
Execute Python function in a virtual environment using source code extraction.
|
||||
|
||||
Args:
|
||||
venv_name: Name of the virtual environment
|
||||
python_func: A callable function to execute
|
||||
\*args: Positional arguments to pass to the function
|
||||
\*\*kwargs: Keyword arguments to pass to the function
|
||||
|
||||
Returns:
|
||||
The result of the function execution, or raises any exception that occurred
|
||||
|
||||
#### Computer.venv_exec_background
|
||||
|
||||
```python
|
||||
async def venv_exec_background(self, venv_name: str, python_func, args = (), requirements: Optional[List[str]] = None, kwargs = {}) -> int
|
||||
```
|
||||
|
||||
Run the Python function in the venv in the background and return the PID.
|
||||
|
||||
Uses a short launcher Python that spawns a detached child and exits immediately.
|
||||
|
||||
#### Computer.python_exec
|
||||
|
||||
```python
|
||||
async def python_exec(self, python_func, args = (), kwargs = {})
|
||||
```
|
||||
|
||||
Execute a Python function using the system Python (no venv).
|
||||
|
||||
Uses source extraction and base64 transport, mirroring venv_exec but
|
||||
without virtual environment activation.
|
||||
|
||||
Returns the function result or raises a reconstructed exception with
|
||||
remote traceback context appended.
|
||||
|
||||
#### Computer.python_exec_background
|
||||
|
||||
```python
|
||||
async def python_exec_background(self, python_func, args = (), requirements: Optional[List[str]] = None, kwargs = {}) -> int
|
||||
```
|
||||
|
||||
Run a Python function with the system interpreter in the background and return PID.
|
||||
|
||||
Uses a short launcher Python that spawns a detached child and exits immediately.
|
||||
|
||||
#### Computer.python_command
|
||||
|
||||
```python
|
||||
def python_command(self, requirements: Optional[List[str]] = None, venv_name: str = 'default', use_system_python: bool = False, background: bool = False) -> Callable[[Callable[P, R]], Callable[P, Awaitable[R]]]
|
||||
```
|
||||
|
||||
Decorator to execute a Python function remotely in this Computer's venv.
|
||||
|
||||
This mirrors `computer.helpers.sandboxed()` but binds to this instance and
|
||||
optionally ensures required packages are installed before execution.
|
||||
|
||||
Args:
|
||||
requirements: Packages to install in the virtual environment.
|
||||
venv_name: Name of the virtual environment to use.
|
||||
use_system_python: If True, use the system Python/pip instead of a venv.
|
||||
background: If True, run the function detached and return the child PID immediately.
|
||||
|
||||
Returns:
|
||||
A decorator that turns a local function into an async callable which
|
||||
runs remotely and returns the function's result.
|
||||
|
||||
## VMProviderType
|
||||
|
||||
Enum of supported VM provider types.
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "v0.5",
|
||||
"description": "Computer SDK v0.5 API Reference",
|
||||
"pages": ["api"]
|
||||
}
|
||||
341
docs/content/docs/cua/reference/desktop-sandbox/changelog.mdx
Normal file
341
docs/content/docs/cua/reference/desktop-sandbox/changelog.mdx
Normal file
@@ -0,0 +1,341 @@
|
||||
---
|
||||
title: Changelog
|
||||
description: Release history for Desktop Sandbox
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-changelog.ts
|
||||
Last updated: 2026-02-04
|
||||
*/}
|
||||
|
||||
# Desktop Sandbox Changelog
|
||||
|
||||
All notable changes to the Desktop Sandbox are documented here.
|
||||
|
||||
## 0.3.x
|
||||
|
||||
### v0.3.16 (2026-01-30)
|
||||
|
||||
- Initial release or no path-specific changes found
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.3.15 (2026-01-29)
|
||||
|
||||
* Bump cua-computer-server to v0.3.15 by @github-actions[bot]
|
||||
* fix(computer-server): initialize coordinate scaling after auto-resize in ([#936](https://github.com/trycua/cua/pull/936)) by @synacktraa
|
||||
* fix(mcp-server): disable redirect for /mcp endpoint ([#935](https://github.com/trycua/cua/pull/935)) by @Fizza-Mukhtar
|
||||
* feat(agent): Centralized tool resolution in ComputerAgent ([#920](https://github.com/trycua/cua/pull/920)) by @sarinali
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.3.14 (2026-01-24)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.3.13 (2026-01-23)
|
||||
|
||||
- Bump cua-computer-server to v0.3.13 by @github-actions[bot]
|
||||
- fix(computer-server): standardize Android handler response format ([#893](https://github.com/trycua/cua/pull/893)) by @synacktraa
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.3.12 (2026-01-21)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.3.11 (2026-01-21)
|
||||
|
||||
* Initial release or no path-specific changes found
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.3.9 (2026-01-21)
|
||||
|
||||
- Bump cua-computer-server to v0.3.9 by @github-actions[bot]
|
||||
- fix(computer-server): make fastmcp a required dependency ([#875](https://github.com/trycua/cua/pull/875)) by @Francesco Bonacci
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.3.8 (2026-01-20)
|
||||
|
||||
* Bump cua-computer-server to v0.3.8 by @github-actions[bot]
|
||||
* fix(computer-server): correct MCP endpoint path and lifespan ([#869](https://github.com/trycua/cua/pull/869)) by @Francesco Bonacci
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.3.7 (2026-01-20)
|
||||
|
||||
- Bump cua-computer-server to v0.3.7 by @github-actions[bot]
|
||||
- feat(computer-server): expose HTTP and MCP interfaces simultaneously ([#861](https://github.com/trycua/cua/pull/861)) by @Francesco Bonacci
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.3.6 (2026-01-20)
|
||||
|
||||
* Bump cua-computer-server to v0.3.6 by @github-actions[bot]
|
||||
* feat(computer-server): auto-detect MCP mode and expose HTTP+MCP simultaneously ([#860](https://github.com/trycua/cua/pull/860)) by @Francesco Bonacci
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.3.5 (2026-01-20)
|
||||
|
||||
- Bump cua-computer-server to v0.3.5 by @github-actions[bot]
|
||||
- feat(computer-server): add MCP interface for Claude Code integration ([#859](https://github.com/trycua/cua/pull/859)) by @Francesco Bonacci
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.3.2 (2026-01-11)
|
||||
|
||||
* Initial release or no path-specific changes found
|
||||
|
||||
### v0.3.1 (2026-01-11)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
## 0.1.x
|
||||
|
||||
### v0.1.28 (2025-10-29)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
- Add test infrastructure with CI/CD #478 by @AceAtDev in https://github.com/trycua/cua/pull/491
|
||||
- Add desktop and window management commands to computer interface by @ddupont808 in https://github.com/trycua/cua/pull/516
|
||||
|
||||
New Contributors
|
||||
|
||||
- @AceAtDev made their first contribution in https://github.com/trycua/cua/pull/491
|
||||
|
||||
### v0.1.27 (2025-10-24)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
- Patch Python SSL on Windows VMs to use system cert store (Python bug: https://bugs.python.org/issue36011) ( by @ddupont808 in https://github.com/trycua/cua/pull/510
|
||||
|
||||
### v0.1.26 (2025-10-24)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
|
||||
* Moved platform-specific deps from computer-server out of optional dependencies (fixes accessibility API not working on macOS, Windows) by @ddupont808 in https://github.com/trycua/cua/pull/508
|
||||
|
||||
### v0.1.25 (2025-10-22)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
- Fix authentication / connection errors caused by computer-server using old API url by @ddupont808 in https://github.com/trycua/cua/pull/499
|
||||
|
||||
New Contributors
|
||||
|
||||
- @masterbatcoderman10 made their first contribution in https://github.com/trycua/cua/pull/480
|
||||
|
||||
### v0.1.23 (2025-10-03)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.1.22 (2025-09-03)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.1.21 (2025-08-06)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.1.20 (2025-07-29)
|
||||
|
||||
Replaced `pyautogui.type_text` with `pynput.KeyboardController`, fixing the bug where multi-line text would just type the letter `"v"` on Linux
|
||||
|
||||
### v0.1.19 (2025-07-11)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.1.18 (2025-07-10)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.1.17 (2025-07-09)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.1.16 (2025-07-09)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.1.15 (2025-07-01)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.1.14 (2025-07-01)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.1.13 (2025-06-18)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.1.12 (2025-06-10)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.1.11 (2025-06-05)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.1.10 (2025-05-31)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.1.9 (2025-05-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.1.8 (2025-05-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.1.7 (2025-05-28)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.1.6 (2025-05-25)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.1.5 (2025-05-16)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
|
||||
### v0.1.4 (2025-04-25)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
|
||||
```
|
||||
|
||||
### v0.1.3 (2025-04-15)
|
||||
|
||||
**Dependencies:** cua-computer: latest
|
||||
|
||||
Run the server
|
||||
cua-computer-server
|
||||
```
|
||||
@@ -7,43 +7,43 @@ Desktop sandbox environments provide isolated desktops for running Computer-Usin
|
||||
|
||||
## Sandbox Options
|
||||
|
||||
### [macOS Sandbox](/cua/reference/desktop-sandbox/macos)
|
||||
### macOS Sandbox
|
||||
|
||||
Native macOS virtual machines on Apple Silicon using Apple's Virtualization Framework. Near-native performance for macOS automation.
|
||||
Native macOS virtual machines on Apple Silicon using Apple's Virtualization Framework. Near-native performance for macOS automation. [Learn more →](/cua/reference/desktop-sandbox/macos)
|
||||
|
||||
- **Lume** - Native CLI for VM management
|
||||
- **Lumier** - Docker wrapper for containerized deployments
|
||||
|
||||
### [Linux Container](/cua/reference/desktop-sandbox/linux-container)
|
||||
### Linux Container
|
||||
|
||||
Docker containers running Linux desktops. Fast startup, low resource usage.
|
||||
Docker containers running Linux desktops. Fast startup, low resource usage. [Learn more →](/cua/reference/desktop-sandbox/linux-container)
|
||||
|
||||
| Container | Description |
|
||||
|-----------|-------------|
|
||||
| [Kasm](/cua/reference/desktop-sandbox/linux-container/kasm) | KasmWeb-based Ubuntu with XFCE |
|
||||
| Container | Description |
|
||||
| ----------------------------------------------------------- | ---------------------------------- |
|
||||
| [Kasm](/cua/reference/desktop-sandbox/linux-container/kasm) | KasmWeb-based Ubuntu with XFCE |
|
||||
| [XFCE](/cua/reference/desktop-sandbox/linux-container/xfce) | Vanilla XFCE, minimal dependencies |
|
||||
|
||||
### [QEMU Container](/cua/reference/desktop-sandbox/qemu-container)
|
||||
### QEMU Container
|
||||
|
||||
Full virtual machines running in Docker via QEMU/KVM. Complete OS isolation, supports Windows.
|
||||
Full virtual machines running in Docker via QEMU/KVM. Complete OS isolation, supports Windows. [Learn more →](/cua/reference/desktop-sandbox/qemu-container)
|
||||
|
||||
| Container | OS | Description |
|
||||
|-----------|-----|-------------|
|
||||
| [Windows](/cua/reference/desktop-sandbox/qemu-container/windows) | Windows 11 | Windows desktop with KVM |
|
||||
| [Linux](/cua/reference/desktop-sandbox/qemu-container/linux) | Ubuntu 22.04 | Full Ubuntu VM |
|
||||
| [Android](/cua/reference/desktop-sandbox/qemu-container/android) | Android 11 | Android emulator |
|
||||
| Container | OS | Description |
|
||||
| ---------------------------------------------------------------- | ------------ | ------------------------ |
|
||||
| [Windows](/cua/reference/desktop-sandbox/qemu-container/windows) | Windows 11 | Windows desktop with KVM |
|
||||
| [Linux](/cua/reference/desktop-sandbox/qemu-container/linux) | Ubuntu 22.04 | Full Ubuntu VM |
|
||||
| [Android](/cua/reference/desktop-sandbox/qemu-container/android) | Android 11 | Android emulator |
|
||||
|
||||
## Quick Comparison
|
||||
|
||||
| Feature | macOS (Lume) | Linux Container | QEMU VM |
|
||||
|---------|--------------|-----------------|---------|
|
||||
| Performance | Near-native | Native | Virtualized |
|
||||
| Startup Time | Minutes | Seconds | 30s-2min |
|
||||
| Host Requirements | Apple Silicon | Docker | KVM support |
|
||||
| Windows Support | No | No | Yes |
|
||||
| Resource Usage | Medium | Low | High |
|
||||
| Memory Snapshots | Yes | No | Yes |
|
||||
| Filesystem Snapshots | Yes | Yes | Yes |
|
||||
| Feature | macOS (Lume) | Linux Container | QEMU VM |
|
||||
| -------------------- | ------------- | --------------- | ----------- |
|
||||
| Performance | Near-native | Native | Virtualized |
|
||||
| Startup Time | Minutes | Seconds | 30s-2min |
|
||||
| Host Requirements | Apple Silicon | Docker | KVM support |
|
||||
| Windows Support | No | No | Yes |
|
||||
| Resource Usage | Medium | Low | High |
|
||||
| Memory Snapshots | Yes | No | Yes |
|
||||
| Filesystem Snapshots | Yes | Yes | Yes |
|
||||
|
||||
### Snapshot Capabilities
|
||||
|
||||
|
||||
@@ -28,6 +28,7 @@ docker run --rm -it \
|
||||
```
|
||||
|
||||
**Access Points:**
|
||||
|
||||
- **VNC Web Interface**: `http://localhost:6901`
|
||||
- **Computer Server API**: `http://localhost:8000`
|
||||
|
||||
@@ -60,10 +61,10 @@ async with computer:
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `VNC_PW` | `password` | VNC password |
|
||||
| `DISPLAY` | `:0` | X11 display |
|
||||
| Variable | Default | Description |
|
||||
| --------- | ---------- | ------------ |
|
||||
| `VNC_PW` | `password` | VNC password |
|
||||
| `DISPLAY` | `:0` | X11 display |
|
||||
|
||||
### Volumes
|
||||
|
||||
|
||||
@@ -28,6 +28,7 @@ docker run --rm -it \
|
||||
```
|
||||
|
||||
**Access Points:**
|
||||
|
||||
- **noVNC Web Interface**: `http://localhost:6901` (no password required)
|
||||
- **VNC Client**: `localhost:5901` (no password required)
|
||||
- **Computer Server API**: `http://localhost:8000`
|
||||
@@ -78,13 +79,13 @@ async with computer:
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `VNC_RESOLUTION` | `1024x768` | Screen resolution |
|
||||
| `VNC_COL_DEPTH` | `24` | Color depth |
|
||||
| `VNC_PORT` | `5901` | VNC server port |
|
||||
| `NOVNC_PORT` | `6901` | noVNC web interface port |
|
||||
| `API_PORT` | `8000` | Computer-server API port |
|
||||
| Variable | Default | Description |
|
||||
| ---------------- | ---------- | ------------------------ |
|
||||
| `VNC_RESOLUTION` | `1024x768` | Screen resolution |
|
||||
| `VNC_COL_DEPTH` | `24` | Color depth |
|
||||
| `VNC_PORT` | `5901` | VNC server port |
|
||||
| `NOVNC_PORT` | `6901` | noVNC web interface port |
|
||||
| `API_PORT` | `8000` | Computer-server API port |
|
||||
|
||||
### Ports
|
||||
|
||||
@@ -111,12 +112,12 @@ docker commit <container_id> cua-xfce-snapshot:latest
|
||||
|
||||
## Comparison with Kasm Container
|
||||
|
||||
| Feature | Kasm Container | XFCE Container |
|
||||
|---------|----------------|----------------|
|
||||
| Base Image | KasmWeb Ubuntu | Vanilla Ubuntu |
|
||||
| VNC Server | KasmVNC | TigerVNC |
|
||||
| Dependencies | Higher | Lower |
|
||||
| Size | Larger | Smaller |
|
||||
| Feature | Kasm Container | XFCE Container |
|
||||
| ------------ | -------------- | -------------- |
|
||||
| Base Image | KasmWeb Ubuntu | Vanilla Ubuntu |
|
||||
| VNC Server | KasmVNC | TigerVNC |
|
||||
| Dependencies | Higher | Lower |
|
||||
| Size | Larger | Smaller |
|
||||
|
||||
## Building from Source
|
||||
|
||||
|
||||
@@ -7,10 +7,10 @@ macOS sandbox environments run native macOS virtual machines on Apple Silicon us
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Description | Best For |
|
||||
|--------|-------------|----------|
|
||||
| [Lume](/lume) | Native CLI for creating and managing macOS VMs | Direct VM management, development |
|
||||
| [Lumier](/lume/guide/advanced/lumier) | Docker wrapper around Lume | Containerized deployments |
|
||||
| Option | Description | Best For |
|
||||
| ------------------------------------- | ---------------------------------------------- | --------------------------------- |
|
||||
| [Lume](/lume) | Native CLI for creating and managing macOS VMs | Direct VM management, development |
|
||||
| [Lumier](/lume/guide/advanced/lumier) | Docker wrapper around Lume | Containerized deployments |
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -67,12 +67,12 @@ async with computer:
|
||||
|
||||
## Comparison with Other Platforms
|
||||
|
||||
| Feature | macOS (Lume) | Linux Container | QEMU VM |
|
||||
|---------|--------------|-----------------|---------|
|
||||
| Performance | Near-native | Native | Virtualized |
|
||||
| Host OS | macOS only | Any with Docker | Any with KVM |
|
||||
| Setup Time | Minutes | Seconds | 15-30 min (first run) |
|
||||
| Windows Support | No | No | Yes |
|
||||
| Feature | macOS (Lume) | Linux Container | QEMU VM |
|
||||
| --------------- | ------------ | --------------- | --------------------- |
|
||||
| Performance | Near-native | Native | Virtualized |
|
||||
| Host OS | macOS only | Any with Docker | Any with KVM |
|
||||
| Setup Time | Minutes | Seconds | 15-30 min (first run) |
|
||||
| Windows Support | No | No | Yes |
|
||||
|
||||
## Related Documentation
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"title": "Desktop Sandbox",
|
||||
"icon": "Container",
|
||||
"pages": ["macos", "linux-container", "qemu-container"]
|
||||
"pages": ["macos", "linux-container", "qemu-container", "changelog"]
|
||||
}
|
||||
|
||||
@@ -33,6 +33,7 @@ docker run -d \
|
||||
```
|
||||
|
||||
**Access Points:**
|
||||
|
||||
- **VNC Web UI**: `http://localhost:6080`
|
||||
- **Computer Server API**: `http://localhost:8000`
|
||||
- **API Documentation**: `http://localhost:8000/docs`
|
||||
@@ -60,10 +61,10 @@ curl -X POST http://localhost:8000/cmd \
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `EMULATOR_DEVICE` | - | Device profile (e.g., "Samsung Galaxy S10") |
|
||||
| `WEB_VNC` | `true` | Enable VNC web interface |
|
||||
| Variable | Default | Description |
|
||||
| ----------------- | ------- | ------------------------------------------- |
|
||||
| `EMULATOR_DEVICE` | - | Device profile (e.g., "Samsung Galaxy S10") |
|
||||
| `WEB_VNC` | `true` | Enable VNC web interface |
|
||||
|
||||
### Ports
|
||||
|
||||
|
||||
@@ -37,6 +37,7 @@ docker run -it --rm \
|
||||
```
|
||||
|
||||
**Access Points:**
|
||||
|
||||
- **Computer Server API**: `http://localhost:5000`
|
||||
- **noVNC Browser**: `http://localhost:8006`
|
||||
|
||||
@@ -44,11 +45,11 @@ docker run -it --rm \
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `RAM_SIZE` | `8G` | RAM allocated to Ubuntu VM |
|
||||
| `CPU_CORES` | `8` | CPU cores allocated to VM |
|
||||
| `DISK_SIZE` | `64G` | VM disk size (minimum: 32G) |
|
||||
| Variable | Default | Description |
|
||||
| ----------- | ------- | --------------------------- |
|
||||
| `RAM_SIZE` | `8G` | RAM allocated to Ubuntu VM |
|
||||
| `CPU_CORES` | `8` | CPU cores allocated to VM |
|
||||
| `DISK_SIZE` | `64G` | VM disk size (minimum: 32G) |
|
||||
|
||||
### Ports
|
||||
|
||||
|
||||
@@ -37,6 +37,7 @@ docker run -it --rm \
|
||||
```
|
||||
|
||||
**Access Points:**
|
||||
|
||||
- **Computer Server API**: `http://localhost:5000`
|
||||
- **noVNC Browser**: `http://localhost:8006`
|
||||
|
||||
@@ -44,11 +45,11 @@ docker run -it --rm \
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `RAM_SIZE` | `8G` | RAM allocated to Windows VM |
|
||||
| `CPU_CORES` | `8` | CPU cores allocated to VM |
|
||||
| `DISK_SIZE` | `30G` | VM disk size (minimum: 20G) |
|
||||
| Variable | Default | Description |
|
||||
| ----------- | ------- | --------------------------- |
|
||||
| `RAM_SIZE` | `8G` | RAM allocated to Windows VM |
|
||||
| `CPU_CORES` | `8` | CPU cores allocated to VM |
|
||||
| `DISK_SIZE` | `30G` | VM disk size (minimum: 20G) |
|
||||
|
||||
### Ports
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
"title": "Reference",
|
||||
"description": "SDK and CLI API reference",
|
||||
"icon": "FileText",
|
||||
"pages": ["desktop-sandbox", "computer-sdk", "agent-sdk", "mcp-server", "cloud-cli"]
|
||||
"pages": ["desktop-sandbox", "computer-sdk", "agent-sdk", "cli"]
|
||||
}
|
||||
|
||||
@@ -713,16 +713,16 @@ modal run modal_grpo_training.py \
|
||||
|
||||
## CLI Options
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `--model-id` | `Qwen/Qwen3-VL-2B-Instruct` | Model to train |
|
||||
| `--num-workers` | `2` | Number of parallel environment workers |
|
||||
| `--max-steps` | `10` | Max steps per episode |
|
||||
| `--num-generations` | `4` | Rollouts per prompt |
|
||||
| `--dataset-size` | `1000` | Number of training samples |
|
||||
| `--learning-rate` | `5e-6` | Learning rate |
|
||||
| `--save-steps` | `100` | Checkpoint save interval |
|
||||
| `--debug` | `False` | Enable verbose output |
|
||||
| Option | Default | Description |
|
||||
| ------------------- | --------------------------- | -------------------------------------- |
|
||||
| `--model-id` | `Qwen/Qwen3-VL-2B-Instruct` | Model to train |
|
||||
| `--num-workers` | `2` | Number of parallel environment workers |
|
||||
| `--max-steps` | `10` | Max steps per episode |
|
||||
| `--num-generations` | `4` | Rollouts per prompt |
|
||||
| `--dataset-size` | `1000` | Number of training samples |
|
||||
| `--learning-rate` | `5e-6` | Learning rate |
|
||||
| `--save-steps` | `100` | Checkpoint save interval |
|
||||
| `--debug` | `False` | Enable verbose output |
|
||||
|
||||
## Creating Custom Tasks
|
||||
|
||||
|
||||
@@ -2,5 +2,13 @@
|
||||
"title": "Fundamentals",
|
||||
"description": "Core concepts of tasks and environments",
|
||||
"icon": "Lightbulb",
|
||||
"pages": ["tasks", "app-helpers", "universal-gui", "simulated-desktop", "agent-traces", "adapters", "registry"]
|
||||
"pages": [
|
||||
"tasks",
|
||||
"app-helpers",
|
||||
"universal-gui",
|
||||
"simulated-desktop",
|
||||
"agent-traces",
|
||||
"adapters",
|
||||
"registry"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -4,7 +4,8 @@ description: A benchmark to measure the capabilities of computer-use agents in d
|
||||
---
|
||||
|
||||
<Callout type="info">
|
||||
Building or researching computer-use agents? Fill out the [Interest Form](https://cuabench.ai/) to chat with us.
|
||||
Building or researching computer-use agents? Fill out the [Interest Form](https://cuabench.ai/) to
|
||||
chat with us.
|
||||
</Callout>
|
||||
|
||||
**Cua-Bench** is a framework and set of tasks for evaluating how well AI agents can accomplish complex tasks on a desktop computer using primarily the keyboard and mouse, or on a mobile device using primarily the touchscreen.
|
||||
|
||||
5157
docs/content/docs/cuabench/reference/api.mdx
Normal file
5157
docs/content/docs/cuabench/reference/api.mdx
Normal file
File diff suppressed because it is too large
Load Diff
@@ -3,6 +3,10 @@ title: CLI Reference
|
||||
description: Complete reference for all cua-bench CLI commands
|
||||
---
|
||||
|
||||
import { VersionBadge } from '@/components/version-selector';
|
||||
|
||||
<VersionBadge version="0.2.3" />
|
||||
|
||||
## Image Commands
|
||||
|
||||
Create and manage base images for environments.
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
"title": "Reference",
|
||||
"description": "CLI and API reference",
|
||||
"icon": "FileText",
|
||||
"pages": ["cli-reference", "sdk-reference"]
|
||||
"pages": ["cli-reference", "api"]
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Installation
|
||||
description: Install CuaBot and its dependencies
|
||||
description: Install Cua-Bot and its dependencies
|
||||
---
|
||||
|
||||
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
|
||||
@@ -41,7 +41,7 @@ import { Callout } from 'fumadocs-ui/components/callout';
|
||||
# Install Xpra
|
||||
sudo apt install xpra
|
||||
|
||||
# Install CuaBot
|
||||
# Install Cua-Bot
|
||||
npm install -g cuabot
|
||||
```
|
||||
|
||||
@@ -1,10 +1,15 @@
|
||||
---
|
||||
title: CuaBot
|
||||
title: Introduction
|
||||
description: Multi-user computing with AI
|
||||
---
|
||||
|
||||
<div className="not-prose flex justify-center my-8">
|
||||
<img src="/docs/img/cuabot-screenshot.png" alt="cuabot screenshot" style={{maxHeight: '32em'}} className="rounded-xl" />
|
||||
<img
|
||||
src="/docs/img/cuabot-screenshot.png"
|
||||
alt="cuabot screenshot"
|
||||
style={{ maxHeight: '32em' }}
|
||||
className="rounded-xl"
|
||||
/>
|
||||
</div>
|
||||
|
||||
**Multi-user computing with AI**
|
||||
@@ -107,7 +112,7 @@ cuabot --help # Show help
|
||||
|
||||
## How It Works
|
||||
|
||||
CuaBot runs a Docker container with Xpra, streaming individual application windows to your desktop. Your chosen agent runs inside the container with:
|
||||
Cua-Bot runs a Docker container with Xpra, streaming individual application windows to your desktop. Your chosen agent runs inside the container with:
|
||||
|
||||
- Full Ubuntu 22.04 environment
|
||||
- Pre-installed: Node.js, Python, browsers, dev tools
|
||||
@@ -117,6 +122,7 @@ CuaBot runs a Docker container with Xpra, streaming individual application windo
|
||||
## Configuration
|
||||
|
||||
Config files are stored in `~/.cuabot/`:
|
||||
|
||||
- `settings.json` - Default agent and preferences
|
||||
- `server.pid` / `server.<name>.pid` - Server process ID
|
||||
- `server.port` / `server.<name>.port` - Server port number
|
||||
7
docs/content/docs/cuabot/guide/getting-started/meta.json
Normal file
7
docs/content/docs/cuabot/guide/getting-started/meta.json
Normal file
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"title": "Getting Started",
|
||||
"description": "Get started with Cua-Bot",
|
||||
"icon": "Rocket",
|
||||
"defaultOpen": true,
|
||||
"pages": ["introduction", "installation"]
|
||||
}
|
||||
6
docs/content/docs/cuabot/guide/meta.json
Normal file
6
docs/content/docs/cuabot/guide/meta.json
Normal file
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"title": "Guide",
|
||||
"description": "Learn how to use Cua-Bot",
|
||||
"icon": "Book",
|
||||
"pages": ["getting-started"]
|
||||
}
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"title": "CuaBot",
|
||||
"title": "Cua-Bot",
|
||||
"description": "Co-op computer-use for any agent",
|
||||
"pages": ["cuabot", "install"]
|
||||
"pages": ["guide", "reference"]
|
||||
}
|
||||
|
||||
132
docs/content/docs/cuabot/reference/changelog.mdx
Normal file
132
docs/content/docs/cuabot/reference/changelog.mdx
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
title: Changelog
|
||||
description: Release history for Cua-Bot
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-changelog.ts
|
||||
Last updated: 2026-02-09
|
||||
*/}
|
||||
|
||||
# Cua-Bot Changelog
|
||||
|
||||
All notable changes to the Cua-Bot are documented here.
|
||||
|
||||
## 1.0.x
|
||||
|
||||
### v1.0.13 (2026-02-05)
|
||||
|
||||
- Bump cuabot to v1.0.13 by @github-actions[bot]
|
||||
|
||||
Documentation
|
||||
|
||||
- [Getting Started](https://cua.ai/docs/cuabot/cuabot)
|
||||
- [Installation Guide](https://cua.ai/docs/cuabot/install)
|
||||
|
||||
### v1.0.12 (2026-02-05)
|
||||
|
||||
- Bump cuabot to v1.0.12 by @github-actions[bot]
|
||||
- fix cursor blocking input, remove start command override for cuabot ([#1020](https://github.com/trycua/cua/pull/1020)) by @ddupont808
|
||||
|
||||
Documentation
|
||||
|
||||
- [Getting Started](https://cua.ai/docs/cuabot/cuabot)
|
||||
- [Installation Guide](https://cua.ai/docs/cuabot/install)
|
||||
|
||||
### v1.0.11 (2026-02-04)
|
||||
|
||||
- Bump cuabot to v1.0.11 by @github-actions[bot]
|
||||
|
||||
Documentation
|
||||
|
||||
- [Getting Started](https://cua.ai/docs/cuabot/cuabot)
|
||||
- [Installation Guide](https://cua.ai/docs/cuabot/install)
|
||||
|
||||
### v1.0.10 (2026-02-04)
|
||||
|
||||
- Bump cuabot to v1.0.10 by @github-actions[bot]
|
||||
|
||||
Documentation
|
||||
|
||||
- [Getting Started](https://cua.ai/docs/cuabot/cuabot)
|
||||
- [Installation Guide](https://cua.ai/docs/cuabot/install)
|
||||
|
||||
### v1.0.9 (2026-02-04)
|
||||
|
||||
- Bump cuabot to v1.0.9 by @github-actions[bot]
|
||||
- Fix onboarding step missing on Windows over npx/pnpx
|
||||
|
||||
Documentation
|
||||
|
||||
- [Getting Started](https://cua.ai/docs/cuabot/cuabot)
|
||||
- [Installation Guide](https://cua.ai/docs/cuabot/install)
|
||||
|
||||
### v1.0.8 (2026-02-04)
|
||||
|
||||
- Bump cuabot to v1.0.8 by @github-actions[bot]
|
||||
- Add onboarding debug info and fix Xpra window detection on Windows ([#1014](https://github.com/trycua/cua/pull/1014)) by @ddupont808
|
||||
|
||||
Documentation
|
||||
|
||||
- [Getting Started](https://cua.ai/docs/cuabot/cuabot)
|
||||
- [Installation Guide](https://cua.ai/docs/cuabot/install)
|
||||
|
||||
### v1.0.7 (2026-02-04)
|
||||
|
||||
- Bump cuabot to v1.0.7 by @github-actions[bot]
|
||||
|
||||
Documentation
|
||||
|
||||
- [Getting Started](https://cua.ai/docs/cuabot/cuabot)
|
||||
- [Installation Guide](https://cua.ai/docs/cuabot/install)
|
||||
|
||||
### v1.0.6 (2026-02-04)
|
||||
|
||||
- Bump cuabot to v1.0.6 by @github-actions[bot]
|
||||
- Bugfixes for Windows
|
||||
|
||||
Documentation
|
||||
|
||||
- [Getting Started](https://cua.ai/docs/cuabot/cuabot)
|
||||
- [Installation Guide](https://cua.ai/docs/cuabot/install)
|
||||
|
||||
### v1.0.5 (2026-02-04)
|
||||
|
||||
- Bump cuabot to v1.0.5 by @github-actions[bot]
|
||||
- [Cuabot] add y to npx ([#1009](https://github.com/trycua/cua/pull/1009)) by @ddupont808
|
||||
- chore: bump cuabot container to 1.0.4 by @github-actions[bot]
|
||||
|
||||
Documentation
|
||||
|
||||
- [Getting Started](https://cua.ai/docs/cuabot/cuabot)
|
||||
- [Installation Guide](https://cua.ai/docs/cuabot/install)
|
||||
|
||||
### v1.0.4 (2026-02-04)
|
||||
|
||||
- Initial release or no path-specific changes found
|
||||
|
||||
Documentation
|
||||
|
||||
- [Getting Started](https://cua.ai/docs/cuabot/cuabot)
|
||||
- [Installation Guide](https://cua.ai/docs/cuabot/install)
|
||||
|
||||
### v1.0.3 (2026-02-04)
|
||||
|
||||
- Bump cuabot to v1.0.3 by @github-actions[bot]
|
||||
- fix cuabot publish 3 ([#1003](https://github.com/trycua/cua/pull/1003)) by @ddupont808
|
||||
- fix cuabot publish 2 ([#1002](https://github.com/trycua/cua/pull/1002)) by @ddupont808
|
||||
|
||||
Documentation
|
||||
|
||||
- [Getting Started](https://cua.ai/docs/cuabot/cuabot)
|
||||
- [Installation Guide](https://cua.ai/docs/cuabot/install)
|
||||
|
||||
### v1.0.2 (2026-02-04)
|
||||
|
||||
- fix cuabot publish ([#1001](https://github.com/trycua/cua/pull/1001)) by @ddupont808
|
||||
- Bump cuabot to v1.0.2 by @github-actions[bot]
|
||||
|
||||
Documentation
|
||||
|
||||
See [cua.ai/docs/cuabot](https://cua.ai/docs/cuabot)
|
||||
295
docs/content/docs/cuabot/reference/index.mdx
Normal file
295
docs/content/docs/cuabot/reference/index.mdx
Normal file
@@ -0,0 +1,295 @@
|
||||
---
|
||||
title: API Reference
|
||||
description: TypeScript API reference for the Cua-Bot sandboxed agent framework
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/typescript-sdk.ts
|
||||
Source: libs/cuabot/src
|
||||
Version: 1.0.13
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
import { VersionHeader } from '@/components/version-selector';
|
||||
|
||||
<VersionHeader
|
||||
versions={[{"version":"1.0","href":"/cuabot/reference","isCurrent":true}]}
|
||||
currentVersion="1.0"
|
||||
fullVersion="1.0.13"
|
||||
packageName="cuabot"
|
||||
installCommand="npm install -g cuabot"
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## client
|
||||
|
||||
CuaBot Server Client
|
||||
Connects to the CuaBot server via HTTP
|
||||
|
||||
### CuaBotClient
|
||||
|
||||
#### Constructor
|
||||
|
||||
```typescript
|
||||
new CuaBotClient(port: number)
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `port` | `number` | |
|
||||
|
||||
#### Methods
|
||||
|
||||
##### CuaBotClient.for
|
||||
|
||||
```typescript
|
||||
for(): Promise<
|
||||
```
|
||||
|
||||
**Returns:** `Promise<`
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<number | null>
|
||||
```
|
||||
|
||||
**Returns:** `Promise<number | null>`
|
||||
|
||||
##### CuaBotClient.status
|
||||
|
||||
```typescript
|
||||
status(): Promise<
|
||||
```
|
||||
|
||||
**Returns:** `Promise<`
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<string>
|
||||
```
|
||||
|
||||
**Returns:** `Promise<string>`
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<void>
|
||||
```
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<void>
|
||||
```
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<void>
|
||||
```
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<void>
|
||||
```
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<void>
|
||||
```
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<void>
|
||||
```
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<void>
|
||||
```
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<void>
|
||||
```
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<void>
|
||||
```
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<void>
|
||||
```
|
||||
|
||||
##### CuaBotClient.request
|
||||
|
||||
```typescript
|
||||
request(): Promise<void>
|
||||
```
|
||||
|
||||
### setSessionName
|
||||
|
||||
```typescript
|
||||
function setSessionName(name: string | null): void
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `name` | `string | null` | |
|
||||
|
||||
### getSessionName
|
||||
|
||||
```typescript
|
||||
function getSessionName(): string | null
|
||||
```
|
||||
|
||||
**Returns:** `string | null`
|
||||
|
||||
### isServerRunning
|
||||
|
||||
```typescript
|
||||
async function isServerRunning(): Promise<
|
||||
```
|
||||
|
||||
**Returns:** `Promise<`
|
||||
|
||||
### ensureServerRunning
|
||||
|
||||
```typescript
|
||||
async function ensureServerRunning(): Promise<number>
|
||||
```
|
||||
|
||||
**Returns:** `Promise<number>`
|
||||
|
||||
---
|
||||
|
||||
## settings
|
||||
|
||||
CuaBot Settings Management
|
||||
|
||||
### Settings
|
||||
|
||||
```typescript
|
||||
interface Settings {
|
||||
defaultAgent?: string;
|
||||
telemetryEnabled?: boolean;
|
||||
aliasIgnored?: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `defaultAgent` | `string` | *(optional)* |
|
||||
| `telemetryEnabled` | `boolean` | *(optional)* |
|
||||
| `aliasIgnored` | `boolean` | *(optional)* |
|
||||
|
||||
### AGENTS
|
||||
|
||||
```typescript
|
||||
const AGENTS: const
|
||||
```
|
||||
|
||||
### loadSettings
|
||||
|
||||
```typescript
|
||||
function loadSettings(): Settings
|
||||
```
|
||||
|
||||
**Returns:** `Settings`
|
||||
|
||||
### saveSettings
|
||||
|
||||
```typescript
|
||||
function saveSettings(settings: Settings): void
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `settings` | `Settings` | |
|
||||
|
||||
### getDefaultAgent
|
||||
|
||||
```typescript
|
||||
function getDefaultAgent(): string | undefined
|
||||
```
|
||||
|
||||
**Returns:** `string | undefined`
|
||||
|
||||
### setDefaultAgent
|
||||
|
||||
```typescript
|
||||
function setDefaultAgent(agent: string): void
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `agent` | `string` | |
|
||||
|
||||
### getTelemetryEnabled
|
||||
|
||||
```typescript
|
||||
function getTelemetryEnabled(): boolean
|
||||
```
|
||||
|
||||
**Returns:** `boolean`
|
||||
|
||||
### isTelemetryConfigured
|
||||
|
||||
```typescript
|
||||
function isTelemetryConfigured(): boolean
|
||||
```
|
||||
|
||||
**Returns:** `boolean`
|
||||
|
||||
### setTelemetryEnabled
|
||||
|
||||
```typescript
|
||||
function setTelemetryEnabled(enabled: boolean): void
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `enabled` | `boolean` | |
|
||||
|
||||
### getAliasIgnored
|
||||
|
||||
```typescript
|
||||
function getAliasIgnored(): boolean
|
||||
```
|
||||
|
||||
**Returns:** `boolean`
|
||||
|
||||
### setAliasIgnored
|
||||
|
||||
```typescript
|
||||
function setAliasIgnored(ignored: boolean): void
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `ignored` | `boolean` | |
|
||||
6
docs/content/docs/cuabot/reference/meta.json
Normal file
6
docs/content/docs/cuabot/reference/meta.json
Normal file
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"title": "Reference",
|
||||
"description": "API and CLI reference for Cua-Bot",
|
||||
"icon": "FileText",
|
||||
"pages": ["changelog"]
|
||||
}
|
||||
@@ -190,11 +190,11 @@ You: Install jq, uninstall it, and verify it's completely removed with no leftov
|
||||
|
||||
## Why this matters
|
||||
|
||||
| Testing Approach | Clean Environment | Isolated | Resettable |
|
||||
|-----------------|-------------------|----------|------------|
|
||||
| Host machine | No | No | No |
|
||||
| Docker | Yes | Yes | Yes (but no macOS) |
|
||||
| **macOS VM** | **Yes** | **Yes** | **Yes** |
|
||||
| Testing Approach | Clean Environment | Isolated | Resettable |
|
||||
| ---------------- | ----------------- | -------- | ------------------ |
|
||||
| Host machine | No | No | No |
|
||||
| Docker | Yes | Yes | Yes (but no macOS) |
|
||||
| **macOS VM** | **Yes** | **Yes** | **Yes** |
|
||||
|
||||
Homebrew is macOS-specific. Testing Homebrew formulas requires macOS, and testing them properly requires isolation.
|
||||
|
||||
|
||||
@@ -89,13 +89,15 @@ Then tell Claude:
|
||||
> Install any dependencies you need, run builds, execute tests—all inside that VM."
|
||||
|
||||
Claude Code will:
|
||||
|
||||
1. SSH into the sandbox VM
|
||||
2. Navigate to your shared project
|
||||
3. Run commands in the isolated environment
|
||||
4. Report results back to you
|
||||
|
||||
<Callout type="info">
|
||||
Claude Code runs on your host but executes commands via SSH inside the VM. Your host system stays untouched—only the sandbox and shared files are affected.
|
||||
Claude Code runs on your host but executes commands via SSH inside the VM. Your host system stays
|
||||
untouched—only the sandbox and shared files are affected.
|
||||
</Callout>
|
||||
|
||||
## Example session
|
||||
@@ -157,18 +159,19 @@ echo "Then tell Claude to SSH into lume@$VM_IP"
|
||||
## Security considerations
|
||||
|
||||
<Callout type="warn">
|
||||
The shared folder is read/write. Claude can modify or delete files in that folder. For sensitive work:
|
||||
- Share a copy of your project, not the original
|
||||
- Use git to track changes and revert if needed
|
||||
- Clone the VM before risky operations
|
||||
The shared folder is read/write. Claude can modify or delete files in that folder. For sensitive
|
||||
work: - Share a copy of your project, not the original - Use git to track changes and revert if
|
||||
needed - Clone the VM before risky operations
|
||||
</Callout>
|
||||
|
||||
The VM itself is fully isolated—code running inside cannot:
|
||||
|
||||
- Access files outside the shared folder
|
||||
- Modify your host system
|
||||
- Read your host's environment variables or credentials
|
||||
|
||||
But it can:
|
||||
|
||||
- Access the network
|
||||
- Install software inside the VM
|
||||
- Consume CPU/memory
|
||||
|
||||
@@ -159,11 +159,11 @@ Try these related tasks:
|
||||
|
||||
This example shows why macOS sandboxes are valuable:
|
||||
|
||||
| Approach | Can use Numbers.app? | Native macOS automation? |
|
||||
|----------|---------------------|-------------------------|
|
||||
| Docker | No | No |
|
||||
| Linux VM | No | No |
|
||||
| **macOS VM** | **Yes** | **Yes** |
|
||||
| Approach | Can use Numbers.app? | Native macOS automation? |
|
||||
| ------------ | -------------------- | ------------------------ |
|
||||
| Docker | No | No |
|
||||
| Linux VM | No | No |
|
||||
| **macOS VM** | **Yes** | **Yes** |
|
||||
|
||||
Tasks requiring Numbers, Keynote, Pages, or other macOS-only apps need a macOS environment. Lume provides that in an isolated sandbox.
|
||||
|
||||
|
||||
@@ -53,7 +53,7 @@ Add the Lume MCP server to your Claude Desktop config:
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
If `lume` isn't in your PATH, use the full path: `/Users/yourname/.local/bin/lume`
|
||||
If `lume` isn't in your PATH, use the full path: `/Users/yourname/.local/bin/lume`
|
||||
</Callout>
|
||||
|
||||
### 2. Restart Claude Desktop
|
||||
@@ -70,15 +70,15 @@ lume create sandbox --os macos --ipsw latest --unattended tahoe
|
||||
|
||||
## Available MCP tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `lume_list_vms` | List all VMs with status and IP addresses |
|
||||
| `lume_get_vm` | Get detailed VM info |
|
||||
| `lume_run_vm` | Start a VM with optional shared directory |
|
||||
| `lume_stop_vm` | Stop a running VM |
|
||||
| `lume_clone_vm` | Clone a VM (for golden images) |
|
||||
| `lume_delete_vm` | Delete a VM |
|
||||
| `lume_exec` | Execute commands inside the VM |
|
||||
| Tool | Description |
|
||||
| ---------------- | ----------------------------------------- |
|
||||
| `lume_list_vms` | List all VMs with status and IP addresses |
|
||||
| `lume_get_vm` | Get detailed VM info |
|
||||
| `lume_run_vm` | Start a VM with optional shared directory |
|
||||
| `lume_stop_vm` | Stop a running VM |
|
||||
| `lume_clone_vm` | Clone a VM (for golden images) |
|
||||
| `lume_delete_vm` | Delete a VM |
|
||||
| `lume_exec` | Execute commands inside the VM |
|
||||
|
||||
## Example workflow
|
||||
|
||||
@@ -150,12 +150,12 @@ VM 'sandbox' started from clean state.
|
||||
|
||||
## Advantages over SSH
|
||||
|
||||
| Feature | SSH (Claude Code) | MCP (Claude Cowork) |
|
||||
|---------|------------------|---------------------|
|
||||
| VM lifecycle | Manual (`lume run/stop`) | Automated via tools |
|
||||
| IP lookup | Manual (`lume get`) | Automatic |
|
||||
| Credentials | User provides | Configured once |
|
||||
| Reset workflow | Script required | Natural language |
|
||||
| Feature | SSH (Claude Code) | MCP (Claude Cowork) |
|
||||
| -------------- | ------------------------ | ------------------- |
|
||||
| VM lifecycle | Manual (`lume run/stop`) | Automated via tools |
|
||||
| IP lookup | Manual (`lume get`) | Automatic |
|
||||
| Credentials | User provides | Configured once |
|
||||
| Reset workflow | Script required | Natural language |
|
||||
|
||||
With MCP, Cowork can manage the entire VM lifecycle through conversation.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: Step-by-step tutorials and use cases for Lume
|
||||
---
|
||||
|
||||
import { Card, Cards } from 'fumadocs-ui/components/card';
|
||||
import { Bot, Terminal, MessageCircle } from 'lucide-react';
|
||||
import { Bot, Terminal } from 'lucide-react';
|
||||
|
||||
# Examples
|
||||
|
||||
@@ -23,12 +23,6 @@ Explore real-world examples and tutorials for using Lume to create and manage ma
|
||||
title="Claude Cowork"
|
||||
description="Use Claude Cowork with Lume MCP connector"
|
||||
/>
|
||||
<Card
|
||||
icon={<MessageCircle className="w-6 h-6" />}
|
||||
href="/lume/examples/openclaw"
|
||||
title="OpenClaw"
|
||||
description="Run OpenClaw messaging gateway with iMessage support"
|
||||
/>
|
||||
</Cards>
|
||||
|
||||
## Available Examples
|
||||
@@ -47,12 +41,6 @@ Use Claude Cowork with the Lume MCP connector for native VM management:
|
||||
- **[Sandbox with MCP](/lume/examples/claude-cowork/sandbox)** — Configure the MCP connector for VM lifecycle control
|
||||
- **[Stock Analysis with Numbers](/lume/examples/claude-cowork/numbers-stock-analysis)** — Use macOS-only apps like Numbers.app
|
||||
|
||||
### OpenClaw
|
||||
|
||||
Run a unified messaging gateway that bridges WhatsApp, Telegram, iMessage, and more with AI agents:
|
||||
|
||||
- **[OpenClaw Setup](/lume/examples/openclaw)** — Install and configure OpenClaw in a headless macOS VM with iMessage support
|
||||
|
||||
## Coming Soon
|
||||
|
||||
- **CI/CD with GitHub Actions** - Run macOS builds and tests in ephemeral VMs
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
"title": "Examples",
|
||||
"description": "Step-by-step tutorials and use cases",
|
||||
"icon": "Blocks",
|
||||
"pages": ["claude-code", "claude-cowork", "openclaw"]
|
||||
"pages": ["claude-code", "claude-cowork"]
|
||||
}
|
||||
|
||||
@@ -16,7 +16,8 @@ lume serve --port 8080
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
If you installed Lume with default settings, the server runs as a background service on port 7777. No need to start it manually.
|
||||
If you installed Lume with default settings, the server runs as a background service on port 7777.
|
||||
No need to start it manually.
|
||||
</Callout>
|
||||
|
||||
## Base URL
|
||||
@@ -66,6 +67,7 @@ curl -X POST http://localhost:7777/lume/vms \
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "VM creation started",
|
||||
|
||||
@@ -27,11 +27,11 @@ docker run -it --rm \
|
||||
|
||||
## Customization points
|
||||
|
||||
| Location | What to customize |
|
||||
|----------|-------------------|
|
||||
| `Dockerfile` | Base image, installed packages |
|
||||
| `/run/hooks/` | Scripts that run during VM lifecycle |
|
||||
| `/run/config/constants.sh` | Default settings |
|
||||
| Location | What to customize |
|
||||
| -------------------------- | ------------------------------------ |
|
||||
| `Dockerfile` | Base image, installed packages |
|
||||
| `/run/hooks/` | Scripts that run during VM lifecycle |
|
||||
| `/run/config/constants.sh` | Default settings |
|
||||
|
||||
### Change the base image
|
||||
|
||||
|
||||
@@ -53,11 +53,11 @@ Access at `http://localhost:8006`.
|
||||
|
||||
## Configuration options
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Field | Description |
|
||||
| ------------------------- | ------------------------------------ |
|
||||
| `restart: unless-stopped` | Auto-restart unless manually stopped |
|
||||
| `stop_grace_period: 2m` | Wait 2 minutes for graceful shutdown |
|
||||
| `stop_signal: SIGINT` | Send interrupt signal to stop |
|
||||
| `stop_grace_period: 2m` | Wait 2 minutes for graceful shutdown |
|
||||
| `stop_signal: SIGINT` | Send interrupt signal to stop |
|
||||
|
||||
## Multiple VMs
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@ docker run -it --rm \
|
||||
Open `http://localhost:8006` in your browser.
|
||||
|
||||
<Callout type="info">
|
||||
In ephemeral mode, changes are lost when you stop the container. See below for persistent storage.
|
||||
In ephemeral mode, changes are lost when you stop the container. See below for persistent storage.
|
||||
</Callout>
|
||||
|
||||
## Persistent storage
|
||||
@@ -90,19 +90,20 @@ chmod +x shared/lifecycle/on-logon.sh
|
||||
```
|
||||
|
||||
The script runs as the `lume` user and can access:
|
||||
|
||||
- `/Users/lume` — home directory
|
||||
- `/Volumes/My Shared Files` — shared folder
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `VM_NAME` | Name for the VM | `my-vm` |
|
||||
| `VERSION` | macOS image to use | `ghcr.io/trycua/macos-sequoia-cua:latest` |
|
||||
| `CPU_CORES` | CPU cores | `4` |
|
||||
| `RAM_SIZE` | Memory in MB | `8192` |
|
||||
| `HOST_STORAGE_PATH` | Persistent storage path | `$(pwd)/storage` |
|
||||
| `HOST_SHARED_PATH` | Shared folder path | `$(pwd)/shared` |
|
||||
| Variable | Description | Example |
|
||||
| ------------------- | ----------------------- | ----------------------------------------- |
|
||||
| `VM_NAME` | Name for the VM | `my-vm` |
|
||||
| `VERSION` | macOS image to use | `ghcr.io/trycua/macos-sequoia-cua:latest` |
|
||||
| `CPU_CORES` | CPU cores | `4` |
|
||||
| `RAM_SIZE` | Memory in MB | `8192` |
|
||||
| `HOST_STORAGE_PATH` | Persistent storage path | `$(pwd)/storage` |
|
||||
| `HOST_SHARED_PATH` | Shared folder path | `$(pwd)/shared` |
|
||||
|
||||
## Change the port
|
||||
|
||||
|
||||
@@ -21,17 +21,18 @@ Open `http://localhost:8006` in your browser—you'll see a macOS desktop.
|
||||
|
||||
## When to use Lumier vs Lume directly
|
||||
|
||||
| Use Lumier when... | Use Lume directly when... |
|
||||
|--------------------|---------------------------|
|
||||
| You want browser-based VNC access | You prefer native VNC clients |
|
||||
| You're distributing VM environments | You're running locally for development |
|
||||
| You want Docker Compose orchestration | You need maximum performance |
|
||||
| You're building Docker-based workflows | You want full CLI control |
|
||||
| Use Lumier when... | Use Lume directly when... |
|
||||
| -------------------------------------- | -------------------------------------- |
|
||||
| You want browser-based VNC access | You prefer native VNC clients |
|
||||
| You're distributing VM environments | You're running locally for development |
|
||||
| You want Docker Compose orchestration | You need maximum performance |
|
||||
| You're building Docker-based workflows | You want full CLI control |
|
||||
|
||||
## How it works
|
||||
|
||||
<Callout type="info">
|
||||
Docker is the delivery mechanism, not an isolation layer. Lumier connects to the Lume service on your host Mac to create real VMs using Apple's Virtualization Framework.
|
||||
Docker is the delivery mechanism, not an isolation layer. Lumier connects to the Lume service on
|
||||
your host Mac to create real VMs using Apple's Virtualization Framework.
|
||||
</Callout>
|
||||
|
||||
```
|
||||
@@ -53,6 +54,7 @@ Docker is the delivery mechanism, not an isolation layer. Lumier connects to the
|
||||
```
|
||||
|
||||
The Docker container provides:
|
||||
|
||||
- noVNC server for browser access
|
||||
- Environment variable configuration
|
||||
- Lifecycle hooks for automation
|
||||
|
||||
@@ -32,7 +32,8 @@ curl http://localhost:7777/lume/vms
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
Lume runs as a background service on port 7777. Lumier connects to this service to create and manage VMs.
|
||||
Lume runs as a background service on port 7777. Lumier connects to this service to create and
|
||||
manage VMs.
|
||||
</Callout>
|
||||
|
||||
## Verify everything works
|
||||
|
||||
@@ -58,7 +58,8 @@ Or manually edit `~/Library/Application Support/Claude/claude_desktop_config.jso
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
If editing manually, replace `/Users/yourname/.local/bin/lume` with the actual path to your lume binary. You can find it by running `which lume` in your terminal.
|
||||
If editing manually, replace `/Users/yourname/.local/bin/lume` with the actual path to your lume
|
||||
binary. You can find it by running `which lume` in your terminal.
|
||||
</Callout>
|
||||
|
||||
### 2. Restart Claude Desktop
|
||||
@@ -68,6 +69,7 @@ Claude will now have access to Lume's VM management tools.
|
||||
### 3. Try it out
|
||||
|
||||
Ask Claude:
|
||||
|
||||
- "List my VMs"
|
||||
- "Start the sandbox VM"
|
||||
- "Run `ls -la` in the sandbox VM"
|
||||
@@ -75,35 +77,35 @@ Ask Claude:
|
||||
|
||||
## Available tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `lume_create_vm` | Create a new macOS VM (async, returns immediately) |
|
||||
| `lume_list_vms` | List all VMs with status, IP addresses, and resource allocation |
|
||||
| `lume_get_vm` | Get detailed VM info (IP, VNC URL, SSH availability) |
|
||||
| `lume_run_vm` | Start a VM with optional shared directory |
|
||||
| `lume_stop_vm` | Stop a running VM gracefully |
|
||||
| `lume_clone_vm` | Clone a VM (useful for golden images) |
|
||||
| `lume_delete_vm` | Delete a VM and its files |
|
||||
| `lume_exec` | Execute commands inside a VM via SSH |
|
||||
| Tool | Description |
|
||||
| ---------------- | --------------------------------------------------------------- |
|
||||
| `lume_create_vm` | Create a new macOS VM (async, returns immediately) |
|
||||
| `lume_list_vms` | List all VMs with status, IP addresses, and resource allocation |
|
||||
| `lume_get_vm` | Get detailed VM info (IP, VNC URL, SSH availability) |
|
||||
| `lume_run_vm` | Start a VM with optional shared directory |
|
||||
| `lume_stop_vm` | Stop a running VM gracefully |
|
||||
| `lume_clone_vm` | Clone a VM (useful for golden images) |
|
||||
| `lume_delete_vm` | Delete a VM and its files |
|
||||
| `lume_exec` | Execute commands inside a VM via SSH |
|
||||
|
||||
## Resources
|
||||
|
||||
The MCP server provides documentation resources that AI agents can read:
|
||||
|
||||
| Resource | Description |
|
||||
|----------|-------------|
|
||||
| Resource | Description |
|
||||
| -------------------- | ------------------------------------------------------------------------ |
|
||||
| `lume://usage-guide` | Comprehensive guide with workflows, best practices, and status reference |
|
||||
| `lume://credentials` | Default SSH credentials for VMs created with unattended setup |
|
||||
| `lume://credentials` | Default SSH credentials for VMs created with unattended setup |
|
||||
|
||||
## Prompts
|
||||
|
||||
Pre-defined workflow prompts guide AI agents through common tasks:
|
||||
|
||||
| Prompt | Description |
|
||||
|--------|-------------|
|
||||
| `create-sandbox` | Create a new macOS VM with unattended setup |
|
||||
| `run-in-sandbox` | Execute a command in an existing VM |
|
||||
| `reset-sandbox` | Reset a sandbox by cloning from a golden image |
|
||||
| Prompt | Description |
|
||||
| ---------------- | ---------------------------------------------- |
|
||||
| `create-sandbox` | Create a new macOS VM with unattended setup |
|
||||
| `run-in-sandbox` | Execute a command in an existing VM |
|
||||
| `reset-sandbox` | Reset a sandbox by cloning from a golden image |
|
||||
|
||||
## Creating VMs
|
||||
|
||||
@@ -111,15 +113,15 @@ The `lume_create_vm` tool creates new macOS VMs asynchronously. Since VM creatio
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Required | Default | Description |
|
||||
|-----------|----------|---------|-------------|
|
||||
| `name` | Yes | - | Name for the new VM |
|
||||
| `ipsw` | No | `latest` | IPSW path or "latest" to download |
|
||||
| `unattended` | No | - | Preset name (e.g., "tahoe", "sequoia") for automatic setup |
|
||||
| `cpu` | No | 4 | Number of CPU cores |
|
||||
| `memory` | No | `8GB` | Memory size (e.g., "8GB", "16GB") |
|
||||
| `disk_size` | No | `64GB` | Disk size (e.g., "64GB", "128GB") |
|
||||
| `storage` | No | - | Storage location name or path |
|
||||
| Parameter | Required | Default | Description |
|
||||
| ------------ | -------- | -------- | ---------------------------------------------------------- |
|
||||
| `name` | Yes | - | Name for the new VM |
|
||||
| `ipsw` | No | `latest` | IPSW path or "latest" to download |
|
||||
| `unattended` | No | - | Preset name (e.g., "tahoe", "sequoia") for automatic setup |
|
||||
| `cpu` | No | 4 | Number of CPU cores |
|
||||
| `memory` | No | `8GB` | Memory size (e.g., "8GB", "16GB") |
|
||||
| `disk_size` | No | `64GB` | Disk size (e.g., "64GB", "128GB") |
|
||||
| `storage` | No | - | Storage location name or path |
|
||||
|
||||
### Provisioning status
|
||||
|
||||
@@ -133,6 +135,7 @@ test stopped -
|
||||
```
|
||||
|
||||
The operation progresses through:
|
||||
|
||||
1. `ipsw_install` — Downloading and installing macOS
|
||||
2. `unattended_setup` — Running Setup Assistant automation (if `unattended` specified)
|
||||
|
||||
@@ -171,6 +174,7 @@ brew install hudochenkov/sshpass/sshpass
|
||||
```
|
||||
|
||||
For VMs created with `--unattended tahoe`:
|
||||
|
||||
- Username: `lume`
|
||||
- Password: `lume`
|
||||
|
||||
@@ -208,12 +212,12 @@ Tests completed! Here are the results:
|
||||
|
||||
## MCP vs HTTP API
|
||||
|
||||
| Feature | MCP Server | HTTP Server |
|
||||
|---------|-----------|-------------|
|
||||
| Command | `lume serve --mcp` | `lume serve` |
|
||||
| Transport | stdio (spawned by client) | HTTP (port 7777) |
|
||||
| Use case | AI agent integration | Scripts, CI/CD, SDKs |
|
||||
| Lifecycle | On-demand, client-managed | Background daemon |
|
||||
| Feature | MCP Server | HTTP Server |
|
||||
| --------- | ------------------------- | -------------------- |
|
||||
| Command | `lume serve --mcp` | `lume serve` |
|
||||
| Transport | stdio (spawned by client) | HTTP (port 7777) |
|
||||
| Use case | AI agent integration | Scripts, CI/CD, SDKs |
|
||||
| Lifecycle | On-demand, client-managed | Background daemon |
|
||||
|
||||
Use MCP for AI agent integration. Use HTTP for programmatic access from scripts and applications.
|
||||
|
||||
@@ -226,6 +230,7 @@ npx @modelcontextprotocol/inspector lume serve --mcp
|
||||
```
|
||||
|
||||
This opens a web UI where you can:
|
||||
|
||||
- See all available tools
|
||||
- Test tool calls interactively
|
||||
- Inspect request/response payloads
|
||||
@@ -276,15 +281,18 @@ New VMs created with `--unattended tahoe` have SSH enabled automatically.
|
||||
## Security considerations
|
||||
|
||||
<Callout type="warn">
|
||||
The MCP server gives AI agents direct control over your VMs. Only use it with trusted AI applications.
|
||||
The MCP server gives AI agents direct control over your VMs. Only use it with trusted AI
|
||||
applications.
|
||||
</Callout>
|
||||
|
||||
The MCP server:
|
||||
|
||||
- Runs locally (stdio transport, no network exposure)
|
||||
- Has full access to VM lifecycle operations
|
||||
- Can execute commands inside VMs with SSH access
|
||||
|
||||
Consider:
|
||||
|
||||
- Using dedicated sandbox VMs for AI agent tasks
|
||||
- Cloning VMs before letting agents modify them
|
||||
- Reviewing agent actions in Claude's interface
|
||||
|
||||
@@ -14,7 +14,8 @@ lume create my-vm --os macos --ipsw latest --unattended tahoe
|
||||
This creates a VM, installs macOS, and runs through the entire Setup Assistant. When it's done, you have a configured VM with user `lume` (password `lume`) and SSH enabled.
|
||||
|
||||
<Callout type="warn">
|
||||
Unattended configs are macOS version-specific. The `tahoe` preset works with macOS Tahoe (15.x). Setup Assistant changes between versions, so configs may need updating for new releases.
|
||||
Unattended configs are macOS version-specific. The `tahoe` preset works with macOS Tahoe (15.x).
|
||||
Setup Assistant changes between versions, so configs may need updating for new releases.
|
||||
</Callout>
|
||||
|
||||
## Prerequisites
|
||||
@@ -72,15 +73,15 @@ Screenshots go to `/tmp/unattended-<uuid>` by default, or specify `--debug-dir /
|
||||
A config has three parts:
|
||||
|
||||
```yaml
|
||||
boot_wait: 30 # Seconds to wait after boot
|
||||
boot_wait: 30 # Seconds to wait after boot
|
||||
|
||||
boot_commands: # Sequence of automation commands
|
||||
boot_commands: # Sequence of automation commands
|
||||
- "<wait 'Continue'>"
|
||||
- "<click 'Continue'>"
|
||||
- "<type 'lume'>"
|
||||
- "<enter>"
|
||||
- '<enter>'
|
||||
|
||||
health_check: # Optional verification
|
||||
health_check: # Optional verification
|
||||
type: ssh
|
||||
user: lume
|
||||
password: lume
|
||||
@@ -91,20 +92,21 @@ health_check: # Optional verification
|
||||
### Wait for text (OCR)
|
||||
|
||||
```yaml
|
||||
- "<wait 'Continue'>" # Wait up to 120s (default)
|
||||
- "<wait 'Loading...', timeout=300>" # Custom timeout
|
||||
- "<wait 'Continue'>" # Wait up to 120s (default)
|
||||
- "<wait 'Loading...', timeout=300>" # Custom timeout
|
||||
```
|
||||
|
||||
### Click text
|
||||
|
||||
```yaml
|
||||
- "<click 'Continue'>" # Click first occurrence
|
||||
- "<click 'Agree', index=-1>" # Click last occurrence
|
||||
- "<click 'Label', xoffset=50>" # Click 50px right of text
|
||||
- "<click_at 960,540>" # Click exact coordinates
|
||||
- "<click 'Continue'>" # Click first occurrence
|
||||
- "<click 'Agree', index=-1>" # Click last occurrence
|
||||
- "<click 'Label', xoffset=50>" # Click 50px right of text
|
||||
- '<click_at 960,540>' # Click exact coordinates
|
||||
```
|
||||
|
||||
When text appears multiple times (like "Agree" in license text and button), use `index`:
|
||||
|
||||
- `index=0` — first (top)
|
||||
- `index=-1` — last (bottom)
|
||||
|
||||
@@ -131,12 +133,12 @@ When text appears multiple times (like "Agree" in license text and button), use
|
||||
### Hotkey combinations
|
||||
|
||||
```yaml
|
||||
- "<cmd+space>" # Spotlight
|
||||
- "<cmd+c>" # Copy
|
||||
- "<cmd+v>" # Paste
|
||||
- "<cmd+q>" # Quit
|
||||
- "<shift+cmd+3>" # Screenshot
|
||||
- "<ctrl+alt+delete>"
|
||||
- '<cmd+space>' # Spotlight
|
||||
- '<cmd+c>' # Copy
|
||||
- '<cmd+v>' # Paste
|
||||
- '<cmd+q>' # Quit
|
||||
- '<shift+cmd+3>' # Screenshot
|
||||
- '<ctrl+alt+delete>'
|
||||
```
|
||||
|
||||
Modifiers: `cmd`/`command`/`super`, `shift`, `alt`/`option`, `ctrl`/`control`
|
||||
@@ -144,8 +146,8 @@ Modifiers: `cmd`/`command`/`super`, `shift`, `alt`/`option`, `ctrl`/`control`
|
||||
### Delays
|
||||
|
||||
```yaml
|
||||
- "<delay 2>" # Wait 2 seconds
|
||||
- "<delay 0.5>" # Decimals work
|
||||
- '<delay 2>' # Wait 2 seconds
|
||||
- '<delay 0.5>' # Decimals work
|
||||
```
|
||||
|
||||
## Example: Complete Setup Assistant
|
||||
@@ -157,30 +159,30 @@ boot_wait: 30
|
||||
|
||||
boot_commands:
|
||||
# Dismiss greeting
|
||||
- "<delay 5>"
|
||||
- "<space>"
|
||||
- "<delay 2>"
|
||||
- '<delay 5>'
|
||||
- '<space>'
|
||||
- '<delay 2>'
|
||||
|
||||
# Language
|
||||
- "<wait 'English', timeout=120>"
|
||||
- "<type 'English'>"
|
||||
- "<delay 1>"
|
||||
- "<enter>"
|
||||
- "<delay 2>"
|
||||
- '<delay 1>'
|
||||
- '<enter>'
|
||||
- '<delay 2>'
|
||||
|
||||
# Country
|
||||
- "<wait 'Country or Region'>"
|
||||
- "<click_at 960,900>"
|
||||
- '<click_at 960,900>'
|
||||
- "<type 'United States'>"
|
||||
- "<enter>"
|
||||
- '<enter>'
|
||||
- "<click 'Continue'>"
|
||||
- "<delay 2>"
|
||||
- '<delay 2>'
|
||||
|
||||
# Transfer - select "Set up as new"
|
||||
- "<wait 'Transfer Your Data'>"
|
||||
- "<delay 20>"
|
||||
- "<tab><tab><tab>"
|
||||
- "<space>"
|
||||
- '<delay 20>'
|
||||
- '<tab><tab><tab>'
|
||||
- '<space>'
|
||||
- "<click 'Continue'>"
|
||||
|
||||
# Accessibility
|
||||
@@ -189,13 +191,13 @@ boot_commands:
|
||||
|
||||
# Account creation
|
||||
- "<wait 'Create a Mac Account'>"
|
||||
- "<tab><tab><tab><tab><tab><tab>"
|
||||
- '<tab><tab><tab><tab><tab><tab>'
|
||||
- "<type 'lume'>"
|
||||
- "<tab><tab>"
|
||||
- '<tab><tab>'
|
||||
- "<type 'lume'>"
|
||||
- "<tab>"
|
||||
- '<tab>'
|
||||
- "<type 'lume'>"
|
||||
- "<tab><tab><space>"
|
||||
- '<tab><tab><space>'
|
||||
- "<click 'Continue'>"
|
||||
|
||||
# Terms
|
||||
@@ -222,9 +224,9 @@ health_check:
|
||||
type: ssh
|
||||
user: lume
|
||||
password: lume
|
||||
timeout: 30 # Seconds per attempt
|
||||
retries: 5 # Number of attempts
|
||||
retry_delay: 10 # Seconds between retries
|
||||
timeout: 30 # Seconds per attempt
|
||||
retries: 5 # Number of attempts
|
||||
retry_delay: 10 # Seconds between retries
|
||||
```
|
||||
|
||||
The automation waits for the VM to become reachable via SSH before declaring success.
|
||||
@@ -240,10 +242,10 @@ The automation waits for the VM to become reachable via SSH before declaring suc
|
||||
**Keyboard navigation** — macOS doesn't Tab through all elements by default. Enable full keyboard access:
|
||||
|
||||
```yaml
|
||||
- "<cmd+space>"
|
||||
- '<cmd+space>'
|
||||
- "<type 'Keyboard'>"
|
||||
- "<delay 2>"
|
||||
- "<enter>"
|
||||
- '<delay 2>'
|
||||
- '<enter>'
|
||||
# Then enable "Keyboard navigation" in settings
|
||||
```
|
||||
|
||||
@@ -251,13 +253,13 @@ The automation waits for the VM to become reachable via SSH before declaring suc
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Commands run too early | Increase `boot_wait`, add `<delay>` |
|
||||
| Text not found | Check spelling/case, increase timeout, use coordinates |
|
||||
| Wrong element clicked | Use `index` to select correct occurrence |
|
||||
| Hotkeys ignored | Click desktop first to focus |
|
||||
| Tab skips elements | Enable keyboard navigation in System Settings |
|
||||
| Problem | Solution |
|
||||
| ---------------------- | ------------------------------------------------------ |
|
||||
| Commands run too early | Increase `boot_wait`, add `<delay>` |
|
||||
| Text not found | Check spelling/case, increase timeout, use coordinates |
|
||||
| Wrong element clicked | Use `index` to select correct occurrence |
|
||||
| Hotkeys ignored | Click desktop first to focus |
|
||||
| Tab skips elements | Enable keyboard navigation in System Settings |
|
||||
|
||||
## Limitations
|
||||
|
||||
@@ -270,19 +272,19 @@ The automation waits for the VM to become reachable via SSH before declaring suc
|
||||
|
||||
### Config fields
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `boot_wait` | integer | 60 | Seconds to wait before starting |
|
||||
| `boot_commands` | array | required | List of commands |
|
||||
| `health_check` | object | optional | Verification config |
|
||||
| Field | Type | Default | Description |
|
||||
| --------------- | ------- | -------- | ------------------------------- |
|
||||
| `boot_wait` | integer | 60 | Seconds to wait before starting |
|
||||
| `boot_commands` | array | required | List of commands |
|
||||
| `health_check` | object | optional | Verification config |
|
||||
|
||||
### Health check fields
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `type` | string | required | `ssh` |
|
||||
| `user` | string | — | SSH username |
|
||||
| `password` | string | — | SSH password |
|
||||
| `timeout` | integer | 30 | Seconds per attempt |
|
||||
| `retries` | integer | 3 | Number of attempts |
|
||||
| `retry_delay` | integer | 5 | Seconds between retries |
|
||||
| Field | Type | Default | Description |
|
||||
| ------------- | ------- | -------- | ----------------------- |
|
||||
| `type` | string | required | `ssh` |
|
||||
| `user` | string | — | SSH username |
|
||||
| `password` | string | — | SSH password |
|
||||
| `timeout` | integer | 30 | Seconds per attempt |
|
||||
| `retries` | integer | 3 | Number of attempts |
|
||||
| `retry_delay` | integer | 5 | Seconds between retries |
|
||||
|
||||
@@ -9,15 +9,15 @@ Once you've [created a VM](/lume/guide/getting-started/quickstart), here's how t
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| List VMs | `lume ls` |
|
||||
| Get details | `lume get my-vm` |
|
||||
| Run | `lume run my-vm` |
|
||||
| Task | Command |
|
||||
| ------------ | ----------------------------- |
|
||||
| List VMs | `lume ls` |
|
||||
| Get details | `lume get my-vm` |
|
||||
| Run | `lume run my-vm` |
|
||||
| Run headless | `lume run my-vm --no-display` |
|
||||
| Stop | `lume stop my-vm` |
|
||||
| Clone | `lume clone my-vm backup` |
|
||||
| Delete | `lume delete my-vm` |
|
||||
| Stop | `lume stop my-vm` |
|
||||
| Clone | `lume clone my-vm backup` |
|
||||
| Delete | `lume delete my-vm` |
|
||||
|
||||
## Run a VM
|
||||
|
||||
@@ -73,7 +73,8 @@ Any ARM64 Linux distribution works. Download the ARM64 (aarch64) ISO, not x86_64
|
||||
- **Fedora** - [fedoraproject.org](https://fedoraproject.org/)
|
||||
|
||||
<Callout type="info">
|
||||
Linux VMs have no licensing restrictions—run as many concurrent instances as your hardware supports. Only macOS VMs are limited to 2 per Mac.
|
||||
Linux VMs have no licensing restrictions—run as many concurrent instances as your hardware
|
||||
supports. Only macOS VMs are limited to 2 per Mac.
|
||||
</Callout>
|
||||
|
||||
## Stop a VM
|
||||
@@ -101,7 +102,7 @@ lume get my-vm
|
||||
## Change VM settings
|
||||
|
||||
<Callout type="warn">
|
||||
Stop the VM before changing settings. Disk size can only increase, not decrease.
|
||||
Stop the VM before changing settings. Disk size can only increase, not decrease.
|
||||
</Callout>
|
||||
|
||||
```bash
|
||||
@@ -207,7 +208,8 @@ lume prune
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
Enable caching if you frequently pull the same images or images sharing base layers. With caching disabled, each `lume pull` downloads everything fresh.
|
||||
Enable caching if you frequently pull the same images or images sharing base layers. With caching
|
||||
disabled, each `lume pull` downloads everything fresh.
|
||||
</Callout>
|
||||
|
||||
## What's next
|
||||
|
||||
@@ -9,16 +9,16 @@ This page compares Lume with other macOS virtualization tools. All of these are
|
||||
|
||||
## Quick Comparison
|
||||
|
||||
| Feature | Lume | Tart | Lima | UTM |
|
||||
|---------|------|------|------|-----|
|
||||
| **License** | MIT | Fair Source | Apache 2.0 | Apache 2.0 |
|
||||
| **macOS VMs** | Yes | Yes | No | Yes |
|
||||
| **Linux VMs** | Yes | Yes | Yes | Yes |
|
||||
| **HTTP API** | Yes | No | No | No |
|
||||
| **MCP Server** | Yes | No | No | No |
|
||||
| **Unattended Setup** | Yes (VNC + OCR) | Via Packer | N/A | No |
|
||||
| **Registry Support** | OCI (GHCR, GCS) | OCI registries | N/A | No |
|
||||
| **Primary Use Case** | Agent automation, CI/CD | CI/CD | Linux containers | General desktop |
|
||||
| Feature | Lume | Tart | Lima | UTM |
|
||||
| -------------------- | ----------------------- | -------------- | ---------------- | --------------- |
|
||||
| **License** | MIT | Fair Source | Apache 2.0 | Apache 2.0 |
|
||||
| **macOS VMs** | Yes | Yes | No | Yes |
|
||||
| **Linux VMs** | Yes | Yes | Yes | Yes |
|
||||
| **HTTP API** | Yes | No | No | No |
|
||||
| **MCP Server** | Yes | No | No | No |
|
||||
| **Unattended Setup** | Yes (VNC + OCR) | Via Packer | N/A | No |
|
||||
| **Registry Support** | OCI (GHCR, GCS) | OCI registries | N/A | No |
|
||||
| **Primary Use Case** | Agent automation, CI/CD | CI/CD | Linux containers | General desktop |
|
||||
|
||||
## Tart
|
||||
|
||||
@@ -91,6 +91,7 @@ This page compares Lume with other macOS virtualization tools. All of these are
|
||||
## Summary
|
||||
|
||||
Choose Lume if you need:
|
||||
|
||||
- An HTTP API for programmatic VM control
|
||||
- MCP server integration for AI agents
|
||||
- Fully automated macOS VM provisioning
|
||||
|
||||
@@ -141,11 +141,11 @@ lume run linux-vm
|
||||
|
||||
Check VM status with `lume ls`:
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `stopped` | VM is not running and ready to start |
|
||||
| `running` | VM is running |
|
||||
| `provisioning (ipsw_install)` | VM is being created—downloading and installing macOS |
|
||||
| Status | Description |
|
||||
| --------------------------------- | ----------------------------------------------------- |
|
||||
| `stopped` | VM is not running and ready to start |
|
||||
| `running` | VM is running |
|
||||
| `provisioning (ipsw_install)` | VM is being created—downloading and installing macOS |
|
||||
| `provisioning (unattended_setup)` | VM is being created—running automated Setup Assistant |
|
||||
|
||||
VMs in `provisioning` status are being created asynchronously. Wait for status to change to `stopped` before starting them.
|
||||
|
||||
@@ -22,6 +22,7 @@ source ~/.zshrc
|
||||
```
|
||||
|
||||
Or restart your terminal after the first command.
|
||||
|
||||
</Callout>
|
||||
|
||||
### Verify it worked
|
||||
@@ -47,11 +48,11 @@ If you see version output, you're ready to [create your first VM](/lume/guide/ge
|
||||
|
||||
The default install includes a background service and auto-updater. You can disable either:
|
||||
|
||||
| Option | Command |
|
||||
|--------|---------|
|
||||
| No background service | `install.sh -- --no-background-service` |
|
||||
| No auto-updates | `install.sh -- --no-auto-updater` |
|
||||
| Neither | `install.sh -- --no-background-service --no-auto-updater` |
|
||||
| Option | Command |
|
||||
| --------------------- | --------------------------------------------------------- |
|
||||
| No background service | `install.sh -- --no-background-service` |
|
||||
| No auto-updates | `install.sh -- --no-auto-updater` |
|
||||
| Neither | `install.sh -- --no-background-service --no-auto-updater` |
|
||||
|
||||
Full command with options:
|
||||
|
||||
@@ -60,7 +61,8 @@ Full command with options:
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
Without the background service, you'll need to run `lume serve` manually when using tools that rely on the Lume API (like the Computer Use Agent).
|
||||
Without the background service, you'll need to run `lume serve` manually when using tools that
|
||||
rely on the Lume API (like the Computer Use Agent).
|
||||
</Callout>
|
||||
|
||||
## Manual installation
|
||||
@@ -104,24 +106,29 @@ rm ~/Library/LaunchAgents/com.trycua.lume_updater.plist
|
||||
|
||||
## Uninstall
|
||||
|
||||
Remove Lume with a single command:
|
||||
Remove Lume completely:
|
||||
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/uninstall.sh)"
|
||||
# Stop and remove background service
|
||||
launchctl unload ~/Library/LaunchAgents/com.trycua.lume_daemon.plist 2>/dev/null
|
||||
rm -f ~/Library/LaunchAgents/com.trycua.lume_daemon.plist
|
||||
|
||||
# Stop and remove auto-updater
|
||||
launchctl unload ~/Library/LaunchAgents/com.trycua.lume_updater.plist 2>/dev/null
|
||||
rm -f ~/Library/LaunchAgents/com.trycua.lume_updater.plist
|
||||
rm -f ~/.local/bin/lume-update
|
||||
|
||||
# Optional: Remove cached images (run before removing binary)
|
||||
lume prune
|
||||
|
||||
# Remove Lume binary
|
||||
rm -f $(which lume)
|
||||
|
||||
# Optional: Remove VMs and config
|
||||
rm -rf ~/.lume
|
||||
rm -rf ~/.config/lume
|
||||
```
|
||||
|
||||
This stops all services, removes the binary, and cleans up LaunchAgents while preserving your VMs and configuration.
|
||||
|
||||
To also remove all VMs and data, use the `--purge` flag:
|
||||
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/uninstall.sh)" -- --purge
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
The `--purge` flag permanently deletes all VMs in `~/.lume/` and configuration in `~/.config/lume/`. This cannot be undone.
|
||||
</Callout>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**`lume: command not found`** — The install location (`~/.local/bin`) isn't in your PATH. Add it and reload:
|
||||
|
||||
@@ -8,11 +8,14 @@ import { Callout } from 'fumadocs-ui/components/callout';
|
||||
Lume is a VM runtime for building AI agents, running CI/CD pipelines, and automating macOS. It uses Apple's native Virtualization Framework to run macOS and Linux VMs at near-native speed on Apple Silicon.
|
||||
|
||||
<Callout type="info" title="MIT License">
|
||||
Lume is open-source and MIT licensed. If you find it useful, we'd appreciate a [star on GitHub](https://github.com/trycua/cua)!
|
||||
Lume is open-source and MIT licensed. If you find it useful, we'd appreciate a [star on
|
||||
GitHub](https://github.com/trycua/cua)!
|
||||
</Callout>
|
||||
|
||||
<Callout type="info" title="Cloud macOS Sandboxes">
|
||||
We're piloting a managed service for customers who want to run cloud macOS sandboxes for CI/CD and agent workloads. [Book a demo](https://cal.com/cua/cua-demo?overlayCalendar=true) if you're interested.
|
||||
We're piloting a managed service for customers who want to run cloud macOS sandboxes for CI/CD and
|
||||
agent workloads. [Book a demo](https://cal.com/cua/cua-demo?overlayCalendar=true) if you're
|
||||
interested.
|
||||
</Callout>
|
||||
|
||||
```bash
|
||||
@@ -52,7 +55,10 @@ Lume is a thin layer over Apple's [Virtualization Framework](https://developer.a
|
||||
**Building AI agents** — Lume powers the [Cua Computer SDK](/cua/reference/computer-sdk), providing VMs that AI models can interact with through screenshots and input simulation.
|
||||
|
||||
<Callout type="info" title="Used by Anthropic">
|
||||
Apple's Virtualization Framework—the same technology Lume is built on—powers [Claude Cowork](https://support.claude.com/en/articles/13345190-getting-started-with-cowork), Anthropic's sandboxed environment for Claude Code. It downloads a Linux root filesystem and boots it in an isolated VM where Claude can safely execute commands without access to your broader system.
|
||||
Apple's Virtualization Framework—the same technology Lume is built on—powers [Claude
|
||||
Cowork](https://support.claude.com/en/articles/13345190-getting-started-with-cowork), Anthropic's
|
||||
sandboxed environment for Claude Code. It downloads a Linux root filesystem and boots it in an
|
||||
isolated VM where Claude can safely execute commands without access to your broader system.
|
||||
</Callout>
|
||||
|
||||
## What Lume doesn't do
|
||||
|
||||
@@ -38,7 +38,8 @@ lume create my-vm --os macos --ipsw latest
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
The IPSW file is ~15GB. If you plan to create multiple VMs, downloading manually and reusing the file saves time and bandwidth.
|
||||
The IPSW file is ~15GB. If you plan to create multiple VMs, downloading manually and reusing the
|
||||
file saves time and bandwidth.
|
||||
</Callout>
|
||||
|
||||
## Configure VM storage location (optional)
|
||||
@@ -67,7 +68,8 @@ lume create my-vm --os macos --ipsw latest --storage /path/to/vm/directory
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
VM disk images can grow large (~50GB+). Using an external SSD keeps your internal storage free and can improve performance for I/O-heavy workloads.
|
||||
VM disk images can grow large (~50GB+). Using an external SSD keeps your internal storage free and
|
||||
can improve performance for I/O-heavy workloads.
|
||||
</Callout>
|
||||
|
||||
## Create a Linux VM
|
||||
@@ -86,7 +88,8 @@ lume run ubuntu-vm
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
Linux VMs require ARM64 ISO images (not x86). Ubuntu, Debian, and Fedora all provide ARM64 server and desktop images.
|
||||
Linux VMs require ARM64 ISO images (not x86). Ubuntu, Debian, and Fedora all provide ARM64 server
|
||||
and desktop images.
|
||||
</Callout>
|
||||
|
||||
## Run your VM
|
||||
@@ -97,10 +100,6 @@ lume run my-vm
|
||||
|
||||
A VNC window opens. For macOS VMs, you'll see the Setup Assistant—complete it manually or use [Unattended Setup](/lume/guide/fundamentals/unattended-setup) to automate it.
|
||||
|
||||
<Callout type="info">
|
||||
**Automatic clipboard sync:** When Remote Login (SSH) is enabled on your VM, Lume automatically syncs clipboard between your Mac and the VM in both directions. Copy on your Mac, paste in the VM—or copy in the VM, paste on your Mac. VMs created with `--unattended` have SSH enabled by default.
|
||||
</Callout>
|
||||
|
||||
## Create a VM with custom resources
|
||||
|
||||
By default, Lume creates VMs with 4 CPU cores, 8GB memory, and a 50GB disk. Override any of these:
|
||||
@@ -112,11 +111,11 @@ lume create dev-vm --os macos --ipsw latest \
|
||||
--disk-size 100GB
|
||||
```
|
||||
|
||||
| Resource | Default | Notes |
|
||||
|----------|---------|-------|
|
||||
| CPU | 4 cores | Max is your Mac's core count |
|
||||
| Memory | 8GB | Leave headroom for your host |
|
||||
| Disk | 50GB | Uses sparse files—only consumes actual usage |
|
||||
| Resource | Default | Notes |
|
||||
| -------- | ------- | -------------------------------------------- |
|
||||
| CPU | 4 cores | Max is your Mac's core count |
|
||||
| Memory | 8GB | Leave headroom for your host |
|
||||
| Disk | 50GB | Uses sparse files—only consumes actual usage |
|
||||
|
||||
## Change display resolution
|
||||
|
||||
@@ -128,12 +127,12 @@ lume set my-vm --display 1920x1080
|
||||
|
||||
The change takes effect on the next VM start. After starting the VM, go to **System Settings → Displays**, enable **Show all resolutions**, and select your new resolution. Common resolutions:
|
||||
|
||||
| Resolution | Aspect Ratio | Use Case |
|
||||
|------------|--------------|----------|
|
||||
| 1024x768 | 4:3 | Default, low resource usage |
|
||||
| 1280x800 | 16:10 | MacBook-style |
|
||||
| 1920x1080 | 16:9 | Full HD |
|
||||
| 2560x1440 | 16:9 | QHD |
|
||||
| Resolution | Aspect Ratio | Use Case |
|
||||
| ---------- | ------------ | --------------------------- |
|
||||
| 1024x768 | 4:3 | Default, low resource usage |
|
||||
| 1280x800 | 16:10 | MacBook-style |
|
||||
| 1920x1080 | 16:9 | Full HD |
|
||||
| 2560x1440 | 16:9 | QHD |
|
||||
|
||||
## Automate the Setup Assistant
|
||||
|
||||
@@ -143,7 +142,7 @@ Skip manual setup entirely with the `--unattended` flag:
|
||||
lume create my-vm --os macos --ipsw latest --unattended tahoe
|
||||
```
|
||||
|
||||
The `tahoe` preset runs through the Setup Assistant automatically, creating a user `lume` with password `lume` and enabling Remote Login (SSH). Once complete, you can connect with `lume ssh my-vm`. This takes 10-15 minutes but requires no interaction.
|
||||
The `tahoe` preset runs through the Setup Assistant automatically, creating a user `lume` with password `lume` and enabling SSH. This takes 10-15 minutes but requires no interaction.
|
||||
|
||||
For custom configurations, see [Unattended Setup](/lume/guide/fundamentals/unattended-setup).
|
||||
|
||||
@@ -160,7 +159,7 @@ lume run my-vm --no-display
|
||||
lume run my-vm > /dev/null 2>&1 &
|
||||
```
|
||||
|
||||
When running headless or in background, connect via `lume ssh my-vm` (if Remote Login is enabled) or a VNC client. Use `lume ls` to see running VMs and their connection details.
|
||||
When running headless or in background, connect via SSH (if enabled) or VNC client. Use `lume ls` to see running VMs and their connection details.
|
||||
|
||||
## Common operations
|
||||
|
||||
@@ -181,33 +180,6 @@ lume clone my-vm my-vm-backup
|
||||
lume delete my-vm
|
||||
```
|
||||
|
||||
## Connect via SSH
|
||||
|
||||
Access your VM from the terminal without needing the VNC window:
|
||||
|
||||
```bash
|
||||
# Interactive shell
|
||||
lume ssh my-vm
|
||||
|
||||
# Run a single command
|
||||
lume ssh my-vm "ls -la"
|
||||
|
||||
# Run multiple commands
|
||||
lume ssh my-vm "cd /tmp && pwd"
|
||||
```
|
||||
|
||||
<Callout type="warn">
|
||||
**SSH requires Remote Login to be enabled on the VM.** Either:
|
||||
- Create the VM with `--unattended` (enables SSH automatically with user `lume`, password `lume`)
|
||||
- Or manually enable it: **System Settings → General → Sharing → Remote Login**
|
||||
</Callout>
|
||||
|
||||
Custom credentials:
|
||||
|
||||
```bash
|
||||
lume ssh my-vm -u myuser -p mypassword
|
||||
```
|
||||
|
||||
## Share files with your VM
|
||||
|
||||
Mount a host directory inside the VM:
|
||||
|
||||
441
docs/content/docs/lume/reference/changelog.mdx
Normal file
441
docs/content/docs/lume/reference/changelog.mdx
Normal file
@@ -0,0 +1,441 @@
|
||||
---
|
||||
title: Changelog
|
||||
description: Release history for Lume
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/generate-changelog.ts
|
||||
Last updated: 2026-02-04
|
||||
*/}
|
||||
|
||||
# Lume Changelog
|
||||
|
||||
All notable changes to the Lume are documented here.
|
||||
|
||||
## 0.2.x
|
||||
|
||||
### v0.2.76 (2026-02-03)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.75 (2026-02-03)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.74 (2026-02-03)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.73 (2026-02-03)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.72 (2026-02-03)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.71 (2026-02-03)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.70 (2026-02-03)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.69 (2026-02-02)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.68 (2026-02-02)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.67 (2026-02-02)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.66 (2026-02-02)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.65 (2026-02-02)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.64 (2026-02-02)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.63 (2026-02-02)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.62 (2026-02-02)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.61 (2026-02-02)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.60 (2026-02-02)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.59 (2026-02-01)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.58 (2026-02-01)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.57 (2026-02-01)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.56 (2026-02-01)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.55 (2026-02-01)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.54 (2026-02-01)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.52 (2026-01-25)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.51 (2026-01-21)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.50 (2026-01-21)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.49 (2026-01-21)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.46 (2026-01-20)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.45 (2026-01-19)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.44 (2026-01-19)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.43 (2026-01-19)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.42 (2026-01-19)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.41 (2026-01-19)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.40 (2026-01-18)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.39 (2026-01-18)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.38 (2026-01-18)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.37 (2026-01-18)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.36 (2026-01-18)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.34 (2026-01-18)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.33 (2026-01-18)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.32 (2026-01-18)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.31 (2026-01-17)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.30 (2026-01-17)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.29 (2026-01-17)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.28 (2026-01-17)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.27 (2026-01-11)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.26 (2026-01-11)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.25 (2026-01-11)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.23 (2025-12-23)
|
||||
|
||||
- Update README badges with sky/emerald colors and larger logo by @f-trycua in https://github.com/trycua/cua/pull/641
|
||||
- Add QEMU Ubuntu 22.04 template with CUA computer-server support by @synacktraa in https://github.com/trycua/cua/pull/622
|
||||
- Add QEMU Windows 11 template with CUA computer-server support by @synacktraa in https://github.com/trycua/cua/pull/551
|
||||
- docs: update intro page with hero image and Geist font by @f-trycua in https://github.com/trycua/cua/pull/642
|
||||
- docs: expand CUA description with screenshot-VLM-action loop by @f-trycua in https://github.com/trycua/cua/pull/643
|
||||
- F trycua/docs hero image by @f-trycua in https://github.com/trycua/cua/pull/644
|
||||
- Introduce cua-bench-ui submodules (webview API, configurable ports, improved python RPC) by @ddupont808 in https://github.com/trycua/cua/pull/645
|
||||
- Replace PyQt6 with PySide6 by @ddupont808 in https://github.com/trycua/cua/pull/646
|
||||
- Bump cua-bench-ui version in xfce Dockerfile by @ddupont808 in https://github.com/trycua/cua/pull/647
|
||||
- Replace qt backend with gtk in xfce Docker image by @ddupont808 in https://github.com/trycua/cua/pull/648
|
||||
- fix(docs): broken link references for docs by @sarinali in https://github.com/trycua/cua/pull/652
|
||||
- fix(docs): document cloud models by @sarinali in https://github.com/trycua/cua/pull/651
|
||||
- Refactor Docker publish workflow to correctly build and publish multi-arch images by @synacktraa in https://github.com/trycua/cua/pull/653
|
||||
- Refactor Python quickstart examples to use asyncio by @LucaStngn in https://github.com/trycua/cua/pull/650
|
||||
- fix(lume): Resolve install script downloading wrong release by @synacktraa in https://github.com/trycua/cua/pull/655
|
||||
|
||||
### v0.2.22 (2025-06-17)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.16 (2025-06-16)
|
||||
|
||||
- Add .devcontainer and Dockerfile fixes by @ddupont808 in https://github.com/trycua/cua/pull/287
|
||||
- [Agent] Removed extra screenshots in OpenAI/Anthropic tools, fixed image retention bug by @ddupont808 in https://github.com/trycua/cua/pull/291
|
||||
|
||||
### v0.2.15 (2025-05-23)
|
||||
|
||||
- Lumier computer provider takes non-trycua image by @jklapacz in https://github.com/trycua/cua/pull/181
|
||||
- Added Cmake dep to playground.sh by @ddupont808 in https://github.com/trycua/cua/pull/184
|
||||
|
||||
### v0.2.14 (2025-05-14)
|
||||
|
||||
- [Computer] Add initial VM Provider by @f-trycua in https://github.com/trycua/cua/pull/162
|
||||
|
||||
### v0.2.13 (2025-05-11)
|
||||
|
||||
- Add clipboard and audio device by @f-trycua in https://github.com/trycua/cua/pull/170
|
||||
|
||||
### v0.2.12 (2025-05-07)
|
||||
|
||||
- Replaced remaining `os=` occurances with `os_type=` by @ddupont808 in https://github.com/trycua/cua/pull/159
|
||||
- Prevent install if sudo by @f-trycua in https://github.com/trycua/cua/pull/161
|
||||
|
||||
### v0.2.11 (2025-05-06)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.10 (2025-05-06)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.9 (2025-05-05)
|
||||
|
||||
- [Agent] Add standardized agent trajectory logging by @ddupont808 in https://github.com/trycua/cua/pull/155
|
||||
|
||||
### v0.2.8 (2025-05-02)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.7 (2025-04-30)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.6 (2025-04-29)
|
||||
|
||||
- docs: fix wait action in blog notebook by @FinnBorge in https://github.com/trycua/cua/pull/142
|
||||
- [Lumier] Introduce Lumier - Docker-based macOS VM Management Interface by @f-trycua in https://github.com/trycua/cua/pull/144
|
||||
|
||||
New Contributors
|
||||
|
||||
- @FinnBorge made their first contribution in https://github.com/trycua/cua/pull/142
|
||||
|
||||
### v0.2.5 (2025-04-25)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.4 (2025-04-24)
|
||||
|
||||
- [Root] Fix root py project toml by @f-trycua in https://github.com/trycua/cua/pull/133
|
||||
- Update Mac identifier during clone process by @dp221125 in https://github.com/trycua/cua/pull/130
|
||||
|
||||
New Contributors
|
||||
|
||||
- @dp221125 made their first contribution in https://github.com/trycua/cua/pull/130
|
||||
|
||||
### v0.2.3 (2025-04-23)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.2 (2025-04-22)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.1 (2025-04-22)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.2.0 (2025-04-22)
|
||||
|
||||
- [Computer] Add Gradio UI and fix interaction bugs by @ddupont808 in https://github.com/trycua/cua/pull/116
|
||||
- Docs: Add EasyOCR SSL & Lume VM Startup Troubleshooting to FAQ by @trospix in https://github.com/trycua/cua/pull/114
|
||||
- [Lume] Fix broken storage tests by @f-trycua in https://github.com/trycua/cua/pull/107
|
||||
- docs: add trospix as a contributor for code by @allcontributors in https://github.com/trycua/cua/pull/115
|
||||
- docs: add eltociear as a contributor for code by @allcontributors in https://github.com/trycua/cua/pull/121
|
||||
- docs: update computer/README.md by @eltociear in https://github.com/trycua/cua/pull/119
|
||||
- [Lume] Sparse Push & Pull Optimizations by @f-trycua in https://github.com/trycua/cua/pull/122
|
||||
|
||||
New Contributors
|
||||
|
||||
- @trospix made their first contribution in https://github.com/trycua/cua/pull/114
|
||||
- @eltociear made their first contribution in https://github.com/trycua/cua/pull/119
|
||||
|
||||
## 0.1.x
|
||||
|
||||
### v0.1.38 (2025-04-15)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.37 (2025-04-15)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.36 (2025-04-15)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.35 (2025-04-15)
|
||||
|
||||
- Update install_mcp_server.sh - remove piping to /dev/null by @rahulkarajgikar in https://github.com/trycua/cua/pull/110
|
||||
- docs: add rahulkarajgikar as a contributor for code by @allcontributors in https://github.com/trycua/cua/pull/111
|
||||
- Support py >= 3.13 by @f-trycua in https://github.com/trycua/cua/pull/112
|
||||
|
||||
New Contributors
|
||||
|
||||
- @rahulkarajgikar made their first contribution in https://github.com/trycua/cua/pull/110
|
||||
|
||||
### v0.1.34 (2025-04-14)
|
||||
|
||||
- [Lume] Add multiple VM locations and configurable cache by @f-trycua in https://github.com/trycua/cua/pull/91
|
||||
|
||||
### v0.1.33 (2025-04-14)
|
||||
|
||||
- [Agent] Improved Gradio UI by @ddupont808 in https://github.com/trycua/cua/pull/104
|
||||
|
||||
### v0.1.32 (2025-04-12)
|
||||
|
||||
- [Lume] Optimize VM image assembly by @f-trycua in https://github.com/trycua/cua/pull/102
|
||||
|
||||
### v0.1.31 (2025-04-11)
|
||||
|
||||
- [Agent] Fix leftover Gradio docs by @f-trycua in https://github.com/trycua/cua/pull/97
|
||||
- docs: add RicterZ as a contributor for code by @allcontributors in https://github.com/trycua/cua/pull/98
|
||||
- [Lume] Fix reassemble kill by @f-trycua in https://github.com/trycua/cua/pull/99
|
||||
|
||||
### v0.1.30 (2025-04-07)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.29 (2025-04-07)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.28 (2025-04-07)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.27 (2025-04-07)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.26 (2025-04-06)
|
||||
|
||||
- Fix anthropic format in omni loop by @f-trycua in https://github.com/trycua/cua/pull/94
|
||||
|
||||
### v0.1.25 (2025-04-06)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.24 (2025-04-06)
|
||||
|
||||
- [Agent] Add Gradio UI & OAI-Compatible Provider by @f-trycua in https://github.com/trycua/cua/pull/93
|
||||
|
||||
### v0.1.23 (2025-04-04)
|
||||
|
||||
- Add ai-gradio notebook by @f-trycua in https://github.com/trycua/cua/pull/85
|
||||
- Update README with gradio by @f-trycua in https://github.com/trycua/cua/pull/86
|
||||
- [SOM] Fix overlapping bounding boxes and added GPU/MPS support by @ddupont808 in https://github.com/trycua/cua/pull/87
|
||||
- Add Ollama support in Omni parser by @Lizzard1123 in https://github.com/trycua/cua/pull/76
|
||||
- docs: add ddupont808 as a contributor for code by @allcontributors in https://github.com/trycua/cua/pull/88
|
||||
- docs: add Lizzard1123 as a contributor for code by @allcontributors in https://github.com/trycua/cua/pull/89
|
||||
- [Agent] Add ollama support by @f-trycua in https://github.com/trycua/cua/pull/90
|
||||
|
||||
New Contributors
|
||||
|
||||
- @ddupont808 made their first contribution in https://github.com/trycua/cua/pull/87
|
||||
- @Lizzard1123 made their first contribution in https://github.com/trycua/cua/pull/76
|
||||
|
||||
### v0.1.22 (2025-04-02)
|
||||
|
||||
- Refactor Developer Guide by @f-trycua in https://github.com/trycua/cua/pull/77
|
||||
- Add operator blogpost - part 1 by @f-trycua in https://github.com/trycua/cua/pull/80
|
||||
- [Agent] Add OpenAI generate summary by @f-trycua in https://github.com/trycua/cua/pull/84
|
||||
|
||||
### v0.1.21 (2025-03-30)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.20 (2025-03-30)
|
||||
|
||||
- [Lume] Optimize disk image reassembly for performance and storage by @f-trycua in https://github.com/trycua/cua/pull/72
|
||||
|
||||
### v0.1.19 (2025-03-24)
|
||||
|
||||
- Add `--no-cache` option in lume pull by @aktech in https://github.com/trycua/cua/pull/67
|
||||
|
||||
### v0.1.18 (2025-03-19)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.17 (2025-03-17)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.16 (2025-03-17)
|
||||
|
||||
Maintenance release.
|
||||
|
||||
### v0.1.14 (2025-03-17)
|
||||
|
||||
- Fix url for clone endpoint by @aktech in https://github.com/trycua/computer/pull/54
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Lume CLI Reference
|
||||
title: CLI Reference
|
||||
description: Command Line Interface reference for Lume
|
||||
---
|
||||
|
||||
@@ -7,9 +7,19 @@ description: Command Line Interface reference for Lume
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/lume.ts
|
||||
Source: libs/lume/src/Commands/*.swift
|
||||
Version: 0.2.76
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
import { VersionHeader } from '@/components/version-selector';
|
||||
|
||||
<VersionHeader
|
||||
versions={[{"version":"0.2","href":"/lume/reference/cli-reference","isCurrent":true}]}
|
||||
currentVersion="0.2"
|
||||
fullVersion="0.2.76"
|
||||
packageName="lume"
|
||||
installCommand="curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh | bash"
|
||||
/>
|
||||
|
||||
A lightweight CLI and local API server to build, run and manage macOS VMs.
|
||||
|
||||
@@ -17,7 +27,7 @@ A lightweight CLI and local API server to build, run and manage macOS VMs.
|
||||
|
||||
```bash
|
||||
# Run a prebuilt macOS VM
|
||||
lume run macos-sequoia-vanilla:latest
|
||||
lume run macos-tahoe-vanilla:latest
|
||||
|
||||
# Create a custom VM
|
||||
lume create my-vm --cpu 4 --memory 8GB --disk-size 50GB
|
||||
@@ -156,24 +166,6 @@ List virtual machines
|
||||
- `-f, --format` - Output format (json or text) (default: text)
|
||||
- `--storage` - Filter by storage location name
|
||||
|
||||
## Remote Access
|
||||
|
||||
### lume ssh
|
||||
|
||||
Connect to a VM via SSH or execute commands remotely
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>` - Name of the virtual machine
|
||||
- `<command>` - Command to execute (omit for interactive shell) (optional)
|
||||
|
||||
**Options:**
|
||||
|
||||
- `-u, --user` - SSH username (default: lume)
|
||||
- `-p, --password` - SSH password (default: lume)
|
||||
- `--storage` - Storage location name or path
|
||||
- `-t, --timeout` - Command timeout in seconds (0 for no timeout) (default: 60)
|
||||
|
||||
## Image Management
|
||||
|
||||
### lume pull
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Lume HTTP API Reference
|
||||
title: API Reference
|
||||
description: HTTP API reference for Lume server
|
||||
---
|
||||
|
||||
@@ -7,10 +7,20 @@ description: HTTP API reference for Lume server
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/lume.ts
|
||||
Source: libs/lume/src/Server/*.swift
|
||||
Version: 0.2.76
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
|
||||
import { VersionHeader } from '@/components/version-selector';
|
||||
|
||||
<VersionHeader
|
||||
versions={[{"version":"0.2","href":"/lume/reference/cli-reference","isCurrent":true}]}
|
||||
currentVersion="0.2"
|
||||
fullVersion="0.2.76"
|
||||
packageName="lume"
|
||||
installCommand="curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh | bash"
|
||||
/>
|
||||
|
||||
HTTP API for managing macOS and Linux virtual machines
|
||||
|
||||
@@ -589,7 +599,7 @@ Pull a VM image from a container registry
|
||||
curl -X POST "http://localhost:7777/lume/pull" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"image": "macos-sequoia-vanilla:latest"
|
||||
"image": "macos-tahoe-vanilla:latest"
|
||||
}'
|
||||
```
|
||||
</Tab>
|
||||
@@ -598,7 +608,7 @@ curl -X POST "http://localhost:7777/lume/pull" \
|
||||
import requests
|
||||
|
||||
data = {
|
||||
"image": "macos-sequoia-vanilla:latest",
|
||||
"image": "macos-tahoe-vanilla:latest",
|
||||
}
|
||||
|
||||
response = requests.post("http://localhost:7777/lume/pull", json=data)
|
||||
@@ -611,7 +621,7 @@ const response = await fetch(`http://localhost:7777/lume/pull`, {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({
|
||||
image: "macos-sequoia-vanilla:latest",
|
||||
image: "macos-tahoe-vanilla:latest",
|
||||
}),
|
||||
});
|
||||
const data = await response.json();
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
"title": "Reference",
|
||||
"description": "CLI and API reference documentation",
|
||||
"icon": "FileText",
|
||||
"pages": ["cli-reference", "http-api"]
|
||||
"pages": ["cli-reference", "http-api", "changelog"]
|
||||
}
|
||||
|
||||
295
docs/content/docs/lume/reference/v0.2/cli-reference.mdx
Normal file
295
docs/content/docs/lume/reference/v0.2/cli-reference.mdx
Normal file
@@ -0,0 +1,295 @@
|
||||
---
|
||||
title: Lume CLI Reference
|
||||
description: Command Line Interface reference for Lume
|
||||
---
|
||||
|
||||
{/*
|
||||
AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
|
||||
Generated by: npx tsx scripts/docs-generators/lume.ts
|
||||
Source: libs/lume/src/Commands/*.swift
|
||||
Version: 0.2.75
|
||||
*/}
|
||||
|
||||
import { Callout } from 'fumadocs-ui/components/callout';
|
||||
import { VersionHeader } from '@/components/version-selector';
|
||||
|
||||
<Callout type="warn">
|
||||
This is documentation for **v0.2**. [View latest version](/lume/reference/cli-reference).
|
||||
</Callout>
|
||||
|
||||
<div className="flex items-center gap-2 mb-6">
|
||||
<span className="px-2 py-1 bg-amber-100 dark:bg-amber-900 text-amber-800 dark:text-amber-200 rounded text-sm font-mono">
|
||||
v0.2.75
|
||||
</span>
|
||||
<span className="text-sm text-fd-muted-foreground">curl -fsSL .../install.sh | bash</span>
|
||||
</div>
|
||||
|
||||
A lightweight CLI and local API server to build, run and manage macOS VMs.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Run a prebuilt macOS VM
|
||||
lume run macos-sequoia-vanilla:latest
|
||||
|
||||
# Create a custom VM
|
||||
lume create my-vm --cpu 4 --memory 8GB --disk-size 50GB
|
||||
```
|
||||
|
||||
## VM Management
|
||||
|
||||
### lume create
|
||||
|
||||
Create a new virtual machine
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>` - Name for the virtual machine
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--os` - Operating system to install (macOS or linux) (default: macOS)
|
||||
- `--cpu` - Number of CPU cores (default: 4)
|
||||
- `--memory` - Memory size (e.g., 8GB) (default: 8GB)
|
||||
- `--disk-size` - Disk size (e.g., 50GB) (default: 50GB)
|
||||
- `--display` - Display resolution (e.g., 1024x768) (default: 1024x768)
|
||||
- `--ipsw` - Path to IPSW file or 'latest' for macOS VMs
|
||||
- `--storage` - VM storage location to use
|
||||
- `--unattended` - [Preview] Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: sequoia, tahoe. Only supported for macOS VMs.
|
||||
- `--debug-dir` - Custom directory for debug screenshots during unattended setup (defaults to unique folder in system temp)
|
||||
- `--vnc-port` - Port to use for the VNC server during unattended setup. Defaults to 0 (auto-assign) (default: 0)
|
||||
|
||||
**Flags:**
|
||||
|
||||
- `--debug` - Enable debug mode for unattended setup - saves screenshots with click coordinates
|
||||
- `--no-display` - Do not open the VNC client during unattended setup (default: true for unattended)
|
||||
|
||||
### lume clone
|
||||
|
||||
Clone an existing virtual machine
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>` - Name of the source VM
|
||||
- `<new-name>` - Name for the cloned VM
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--source-storage` - Source VM storage location
|
||||
- `--dest-storage` - Destination VM storage location
|
||||
|
||||
### lume run
|
||||
|
||||
Run a virtual machine
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>` - Name of the VM or image to run (format: name or name:tag)
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--shared-dir` - Directory to share with the VM (format: path or path:ro or path:rw)
|
||||
- `--mount` - For Linux VMs only, attach a read-only disk image
|
||||
- `--usb-storage` - Disk image to attach as USB mass storage device
|
||||
- `--registry` - Container registry URL (default: ghcr.io)
|
||||
- `--organization` - Organization to pull from (default: trycua)
|
||||
- `--vnc-port` - Port for VNC server (0 for auto-assign) (default: 0)
|
||||
- `--recovery-mode` - For macOS VMs only, boot in recovery mode (default: false)
|
||||
- `--storage` - VM storage location to use
|
||||
|
||||
**Flags:**
|
||||
|
||||
- `-d, --no-display` - Do not start the VNC client
|
||||
|
||||
### lume stop
|
||||
|
||||
Stop a virtual machine
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>` - Name of the VM to stop
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--storage` - VM storage location to use
|
||||
|
||||
### lume delete
|
||||
|
||||
Delete a virtual machine
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>` - Name of the VM to delete
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--storage` - VM storage location to use
|
||||
|
||||
**Flags:**
|
||||
|
||||
- `--force` - Force deletion without confirmation
|
||||
|
||||
## VM Information and Configuration
|
||||
|
||||
### lume get
|
||||
|
||||
Get detailed information about a virtual machine
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>` - Name of the VM
|
||||
|
||||
**Options:**
|
||||
|
||||
- `-f, --format` - Output format (default: text)
|
||||
- `--storage` - VM storage location to use
|
||||
|
||||
### lume set
|
||||
|
||||
Set new values for CPU, memory, and disk size of a virtual machine
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>` - Name of the VM
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--cpu` - New number of CPU cores
|
||||
- `--memory` - New memory size (e.g., 8GB)
|
||||
- `--disk-size` - New disk size (e.g., 100GB)
|
||||
- `--display` - New display resolution
|
||||
- `--storage` - VM storage location to use
|
||||
|
||||
### lume ls
|
||||
|
||||
List virtual machines
|
||||
|
||||
**Options:**
|
||||
|
||||
- `-f, --format` - Output format (json or text) (default: text)
|
||||
- `--storage` - Filter by storage location name
|
||||
|
||||
## Image Management
|
||||
|
||||
### lume pull
|
||||
|
||||
Pull a macOS image from GitHub Container Registry
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<image>` - Image to pull (format: name:tag)
|
||||
- `<name>` - Name for the resulting VM (optional)
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--registry` - Container registry URL (default: ghcr.io)
|
||||
- `--organization` - Organization to pull from (default: trycua)
|
||||
- `--storage` - VM storage location to use
|
||||
|
||||
### lume push
|
||||
|
||||
Push a macOS VM to GitHub Container Registry
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>` - Name of VM to push
|
||||
- `<image>` - Image tag (format: name:tag)
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--additional-tags` - Additional tags to push
|
||||
- `--registry` - Container registry URL (default: ghcr.io)
|
||||
- `--organization` - Organization to push to (default: trycua)
|
||||
- `--storage` - VM storage location to use
|
||||
- `--chunk-size-mb` - Chunk size for upload in MB (default: 512)
|
||||
|
||||
**Flags:**
|
||||
|
||||
- `--verbose` - Enable verbose logging
|
||||
- `--dry-run` - Prepare files without uploading
|
||||
- `--reassemble` - Verify integrity by reassembling chunks
|
||||
|
||||
### lume images
|
||||
|
||||
List available macOS images from local cache
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--organization` - Organization to list images for (default: trycua)
|
||||
|
||||
### lume ipsw
|
||||
|
||||
Get macOS restore image IPSW URL
|
||||
|
||||
### lume prune
|
||||
|
||||
Remove cached images
|
||||
|
||||
## Configuration and Server
|
||||
|
||||
### lume serve
|
||||
|
||||
Start the VM management server
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--port` - Port to listen on (default: 7777)
|
||||
|
||||
### lume config
|
||||
|
||||
Get or set lume configuration
|
||||
|
||||
**Subcommands:**
|
||||
|
||||
- `lume config get` - Get current configuration
|
||||
- `lume config storage` - Manage VM storage locations
|
||||
- `lume config storage add` - Add a new VM storage location
|
||||
- `lume config storage remove` - Remove a VM storage location
|
||||
- `lume config storage list` - List all VM storage locations
|
||||
- `lume config storage default` - Set the default VM storage location
|
||||
- `lume config cache` - Manage cache settings
|
||||
- `lume config cache get` - Get current cache directory
|
||||
- `lume config cache set` - Set cache directory
|
||||
- `lume config caching` - Manage image caching settings
|
||||
- `lume config caching get` - Show current caching status
|
||||
- `lume config caching set` - Enable or disable image caching
|
||||
|
||||
### lume logs
|
||||
|
||||
View lume serve logs
|
||||
|
||||
**Subcommands:**
|
||||
|
||||
- `lume logs info` - View info logs from the daemon
|
||||
- `-n, --lines` - Number of lines to display
|
||||
- `lume logs error` - View error logs from the daemon
|
||||
- `-n, --lines` - Number of lines to display
|
||||
- `lume logs all` - View both info and error logs
|
||||
- `-n, --lines` - Number of lines to display
|
||||
|
||||
### lume setup
|
||||
|
||||
[Preview] Run unattended Setup Assistant automation on a macOS VM
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>` - Name of the virtual machine
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--unattended` - Preset name or path to YAML config file for unattended macOS Setup Assistant automation. Built-in presets: sequoia, tahoe.
|
||||
- `--storage` - VM storage location to use or direct path to VM location
|
||||
- `--vnc-port` - Port to use for the VNC server. Defaults to 0 (auto-assign) (default: 0)
|
||||
- `--debug-dir` - Custom directory for debug screenshots (defaults to unique folder in system temp)
|
||||
|
||||
**Flags:**
|
||||
|
||||
- `--no-display` - Do not open the VNC client automatically
|
||||
- `--debug` - Enable debug mode - saves screenshots with click coordinates
|
||||
|
||||
## Global Options
|
||||
|
||||
These options are available for all commands:
|
||||
|
||||
- `--help` - Show help information
|
||||
- `--version` - Show version number
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user