mirror/computer
1
0
Fork 0
mirror of https://github.com/trycua/computer.git synced 2026-01-01 11:00:31 -06:00
Code Issues Packages Projects Releases Wiki Activity

More adjustments to the docs -- new organization

Browse Source
This commit is contained in:
Morgan Dean
2025-06-24 14:24:08 -07:00
parent 00beab966f
commit 2d7b5d7abc
30 changed files with 685 additions and 1430 deletions
Download Patch File Download Diff File Expand all files Collapse all files

290
docs/content/docs/v1/Developer-Guide.mdx
View File

@@ -1,290 +0,0 @@
---
title: Developer Guide
description: Cua Monorepo Developer Guide
---
# Getting Started
## Project Structure
The project is organized as a monorepo with these main packages:
- `libs/core/` - Base package with telemetry support
- `libs/computer/` - Computer-use interface (CUI) library
- `libs/agent/` - AI agent library with multi-provider support
- `libs/som/` - Set-of-Mark parser
- `libs/computer-server/` - Server component for VM
- `libs/lume/` - Lume CLI
- `libs/pylume/` - Python bindings for Lume
Each package has its own virtual environment and dependencies, managed through PDM.
## Local Development Setup
1. Install Lume CLI:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
```
2. Clone the repository:
```bash
git clone https://github.com/trycua/cua.git
cd cua
```
3. Create a `.env.local` file in the root directory with your API keys:
```bash
# Required for Anthropic provider
ANTHROPIC_API_KEY=your_anthropic_key_here
# Required for OpenAI provider
OPENAI_API_KEY=your_openai_key_here
```
4. Open the workspace in VSCode or Cursor:
```bash
# For Cua Python development
code .vscode/py.code-workspace
# For Lume (Swift) development
code .vscode/lume.code-workspace
```
Using the workspace file is strongly recommended as it:
- Sets up correct Python environments for each package
- Configures proper import paths
- Enables debugging configurations
- Maintains consistent settings across packages
## Lume Development
Refer to the [Lume README](../libs/lume/docs/Development.md) for instructions on how to develop the Lume CLI.
## Python Development
There are two ways to install Lume:
### Run the build script
Run the build script to set up all packages:
```bash
./scripts/build.sh
```
The build script creates a shared virtual environment for all packages. The workspace configuration automatically handles import paths with the correct Python path settings.
This will:
- Create a virtual environment for the project
- Install all packages in development mode
- Set up the correct Python path
- Install development tools
### Install with PDM
If PDM is not already installed, you can follow the installation instructions [here](https://pdm-project.org/en/latest/#installation).
To install with PDM, simply run:
```console
pdm install -G:all
```
This installs all the dependencies for development, testing, and building the docs. If you'd only like development dependencies, you can run:
```console
pdm install -d
```
## Running Examples
The Python workspace includes launch configurations for all packages:
- "Run Computer Examples" - Runs computer examples
- "Run Computer API Server" - Runs the computer-server
- "Run Agent Examples" - Runs agent examples
- "SOM" configurations - Various settings for running SOM
To run examples from VSCode / Cursor:
1. Press F5 or use the Run/Debug view
2. Select the desired configuration
The workspace also includes compound launch configurations:
- "Run Computer Examples + Server" - Runs both the Computer Examples and Server simultaneously
## Docker Development Environment
As an alternative to installing directly on your host machine, you can use Docker for development. This approach has several advantages:
### Prerequisites
- Docker installed on your machine
- Lume server running on your host (port 7777): `lume serve`
### Setup and Usage
1. Build the development Docker image:
```bash
./scripts/run-docker-dev.sh build
```
2. Run an example in the container:
```bash
./scripts/run-docker-dev.sh run computer_examples.py
```
3. Get an interactive shell in the container:
```bash
./scripts/run-docker-dev.sh run --interactive
```
4. Stop any running containers:
```bash
./scripts/run-docker-dev.sh stop
```
### How it Works
The Docker development environment:
- Installs all required Python dependencies in the container
- Mounts your source code from the host at runtime
- Automatically configures the connection to use host.docker.internal:7777 for accessing the Lume server on your host machine
- Preserves your code changes without requiring rebuilds (source code is mounted as a volume)
> **Note**: The Docker container doesn't include the macOS-specific Lume executable. Instead, it connects to the Lume server running on your host machine via host.docker.internal:7777. Make sure to start the Lume server on your host before running examples in the container.
## Cleanup and Reset
If you need to clean up the environment (non-docker) and start fresh:
```bash
./scripts/cleanup.sh
```
This will:
- Remove all virtual environments
- Clean Python cache files and directories
- Remove build artifacts
- Clean PDM-related files
- Reset environment configurations
## Code Formatting Standards
The cua project follows strict code formatting standards to ensure consistency across all packages.
### Python Code Formatting
#### Tools
The project uses the following tools for code formatting and linting:
- **[Black](https://black.readthedocs.io/)**: Code formatter
- **[Ruff](https://beta.ruff.rs/docs/)**: Fast linter and formatter
- **[MyPy](https://mypy.readthedocs.io/)**: Static type checker
These tools are automatically installed when you set up the development environment using the `./scripts/build.sh` script.
#### Configuration
The formatting configuration is defined in the root `pyproject.toml` file:
```toml
[tool.black]
line-length = 100
target-version = ["py311"]
[tool.ruff]
line-length = 100
target-version = "py311"
select = ["E", "F", "B", "I"]
fix = true
[tool.ruff.format]
docstring-code-format = true
[tool.mypy]
strict = true
python_version = "3.11"
ignore_missing_imports = true
disallow_untyped_defs = true
check_untyped_defs = true
warn_return_any = true
show_error_codes = true
warn_unused_ignores = false
```
#### Key Formatting Rules
- **Line Length**: Maximum of 100 characters
- **Python Version**: Code should be compatible with Python 3.11+
- **Imports**: Automatically sorted (using Ruff's "I" rule)
- **Type Hints**: Required for all function definitions (strict mypy mode)
#### IDE Integration
The repository includes VSCode workspace configurations that enable automatic formatting. When you open the workspace files (as recommended in the setup instructions), the correct formatting settings are automatically applied.
Python-specific settings in the workspace files:
```json
"[python]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "ms-python.black-formatter",
"editor.codeActionsOnSave": {
"source.organizeImports": "explicit"
}
}
```
Recommended VS Code extensions:
- Black Formatter (ms-python.black-formatter)
- Ruff (charliermarsh.ruff)
- Pylance (ms-python.vscode-pylance)
#### Manual Formatting
To manually format code:
```bash
# Format all Python files using Black
pdm run black .
# Run Ruff linter with auto-fix
pdm run ruff check --fix .
# Run type checking with MyPy
pdm run mypy .
```
#### Pre-commit Validation
Before submitting a pull request, ensure your code passes all formatting checks:
```bash
# Run all checks
pdm run black --check .
pdm run ruff check .
pdm run mypy .
```
### Swift Code (Lume)
For Swift code in the `libs/lume` directory:
- Follow the [Swift API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/)
- Use SwiftFormat for consistent formatting
- Code will be automatically formatted on save when using the lume workspace

128
docs/content/docs/v1/FAQ.mdx
View File

@@ -1,128 +0,0 @@
---
title: FAQs
description: Frequenty Asked Questions
---
# FAQs
### Why a local sandbox?
A local sandbox is a dedicated environment that is isolated from the rest of the system. As AI agents rapidly evolve towards 70-80% success rates on average tasks, having a controlled and secure environment becomes crucial. Cua's Computer-Use AI agents run in a local sandbox to ensure reliability, safety, and controlled execution.
Benefits of using a local sandbox rather than running the Computer-Use AI agent in the host system:
- **Reliability**: The sandbox provides a reproducible environment - critical for benchmarking and debugging agent behavior. Frameworks like [OSWorld](https://github.com/xlang-ai/OSWorld), [Simular AI](https://github.com/simular-ai/Agent-S), Microsoft's [OmniTool](https://github.com/microsoft/OmniParser/tree/master/omnitool), [WindowsAgentArena](https://github.com/microsoft/WindowsAgentArena) and more are using Computer-Use AI agents running in local sandboxes.
- **Safety & Isolation**: The sandbox is isolated from the rest of the system, protecting sensitive data and system resources. As CUA agent capabilities grow, this isolation becomes increasingly important for preventing potential safety breaches.
- **Control**: The sandbox can be easily monitored and terminated if needed, providing oversight for autonomous agent operation.
### Where are the sandbox images stored?
Sandbox are stored in `~/.lume`, and cached images are stored in `~/.lume/cache`.
### Which image is Computer using?
Computer uses an optimized macOS image for Computer-Use interactions, with pre-installed apps and settings for optimal performance.
The image is available on our [ghcr registry](https://github.com/orgs/trycua/packages/container/package/macos-sequoia-cua).
### Are Sandbox disks taking up all the disk space?
No, macOS uses sparse files, which only allocate space as needed. For example, VM disks totaling 50 GB may only use 20 GB on disk.
### How do I delete a VM?
```bash
lume delete <name>
```
### How do I fix EasyOCR `[SSL: CERTIFICATE_VERIFY_FAILED]` errors?
**Symptom:**
When running an agent that uses OCR (e.g., with `AgentLoop.OMNI`), you might encounter an error during the first run or initialization phase that includes:
```
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)
```
**Cause:**
This usually happens when EasyOCR attempts to download its language models over HTTPS for the first time. Python's SSL module cannot verify the server's certificate because it can't locate the necessary root Certificate Authority (CA) certificates in your environment's trust store.
**Solution:**
You need to explicitly tell Python where to find a trusted CA bundle. The `certifi` package provides one. Before running your Python agent script **the first time it needs to download models**, set the following environment variables in the *same terminal session*:
```bash
# Ensure certifi is installed: pip show certifi
export SSL_CERT_FILE=$(python -m certifi)
export REQUESTS_CA_BUNDLE=$(python -m certifi)
# Now run your Python script that uses the agent...
# python your_agent_script.py
```
This directs Python to use the CA bundle provided by `certifi` for SSL verification. **Note:** Once EasyOCR has successfully downloaded its models, you typically do not need to set these environment variables before every subsequent run.
### How do I troubleshoot the agent failing to get the VM IP address or getting stuck on "VM status changed to: stopped"?
**Symptom:**
When running your agent script (e.g., using `Computer().run(...)`), the script might hang during the VM startup phase, logging messages like:
* `Waiting for VM to be ready...`
* `VM status changed to: stopped (after 0.0s)`
* `Still waiting for VM IP address... (elapsed: XX.Xs)`
* Eventually, it might time out, or you might notice the VM window never appears or closes quickly.
**Cause:**
This is typically due to known instability issues with the `lume serve` background daemon process, as documented in the main `README.md`:
1. **`lume serve` Crash:** The `lume serve` process might terminate unexpectedly shortly after launch or when the script tries to interact with it. If it's not running, the script cannot get VM status updates or the IP address.
2. **Incorrect Status Reporting:** Even if `lume serve` is running, its API sometimes incorrectly reports the VM status as `stopped` immediately after startup is initiated. While the underlying `Computer` library tries to poll and wait for the correct `running` status, this initial incorrect report can cause delays or failures if the status doesn't update correctly within the timeout or if `lume serve` crashes during the polling.
**Troubleshooting Steps:**
1. **Check `lume serve`:** Is the `lume serve` process still running in its terminal? Did it print any errors or exit? If it's not running, stop your agent script (`Ctrl+C`) and proceed to step 2.
2. **Force Cleanup:** Before *every* run, perform a rigorous cleanup to ensure no old `lume` processes or VM states interfere. Open a **new terminal** and run:
```bash
# Stop any running Lume VM gracefully first (replace <vm_name> if needed)
lume stop macos-sequoia-cua_latest
# Force kill lume serve and related processes
pkill -f "lume serve"
pkill -9 -f "lume"
pkill -9 -f "VzVirtualMachine" # Kills underlying VM process
# Optional: Verify they are gone
# ps aux | grep -E 'lume|VzVirtualMachine' | grep -v grep
```
3. **Restart Sequence:**
* **Terminal 1:** Start `lume serve` cleanly:
```bash
lume serve
```
*(Watch this terminal to ensure it stays running).*
* **Terminal 2:** Run your agent script (including the `export SSL_CERT_FILE...` commands if *first time* using OCR):
```bash
# export SSL_CERT_FILE=$(python -m certifi) # Only if first run with OCR
# export REQUESTS_CA_BUNDLE=$(python -m certifi) # Only if first run with OCR
python your_agent_script.py
```
4. **Retry:** Due to the intermittent nature of the Lume issues, sometimes simply repeating steps 2 and 3 allows the run to succeed if the timing avoids the status reporting bug or the `lume serve` crash.
**Related Issue: "No route to host" Error (macOS Sequoia+)**
* **Symptom:** Even if the `Computer` library logs show the VM has obtained an IP address, you might encounter connection errors like `No route to host` when the agent tries to connect to the internal server, especially when running the agent script from within an IDE (like VS Code or Cursor).
* **Cause:** This is often due to macOS Sequoia's enhanced local network privacy controls. Applications need explicit permission to access the local network, which includes communicating with the VM.
* **Solution:** Grant "Local Network" access to the application you are running the script from (e.g., your IDE or terminal application). Go to **System Settings > Privacy & Security > Local Network**, find your application in the list, and toggle the switch ON. You might need to trigger a connection attempt from the application first for it to appear in the list. See [GitHub Issue #61](https://github.com/trycua/cua/issues/61) for more details and discussion.
**Note:** Improving the stability of `lume serve` is an ongoing development area.
### How do I troubleshoot Computer not connecting to lume daemon?
If you're experiencing connection issues between Computer and the lume daemon, it could be because the port 7777 (used by lume) is already in use by an orphaned process. You can diagnose this issue with:
```bash
sudo lsof -i :7777
```
This command will show all processes using port 7777. If you see a lume process already running, you can terminate it with:
```bash
kill <PID>
```
Where `<PID>` is the process ID shown in the output of the `lsof` command. After terminating the process, run `lume serve` again to start the lume daemon.
### What information does Cua track?
Cua tracks anonymized usage and error report statistics; we ascribe to Posthog's approach as detailed [here](https://posthog.com/blog/open-source-telemetry-ethical). If you would like to opt out of sending anonymized info, you can set `telemetry_enabled` to false in the Computer or Agent constructor. Check out our [Telemetry](/home/telemetry) documentation for more details.

82
docs/content/docs/v1/Telemetry.mdx
View File

@@ -1,82 +0,0 @@
---
title: Telemetry in C/ua
description: This document explains how telemetry works in C/ua libraries and how you can control it.
---
# Telemetry in C/ua
This document explains how telemetry works in C/ua libraries and how you can control it.
C/ua tracks anonymized usage and error report statistics; we ascribe to Posthog's approach as detailed [here](https://posthog.com/blog/open-source-telemetry-ethical). If you would like to opt out of sending anonymized info, you can set `telemetry_enabled` to false.
## What telemetry data we collect
C/ua libraries collect minimal anonymous usage data to help improve our software. The telemetry data we collect is specifically limited to:
- Basic system information:
- Operating system (e.g., 'darwin', 'win32', 'linux')
- Python version (e.g., '3.11.0')
- Module initialization events:
- When a module (like 'computer' or 'agent') is imported
- Version of the module being used
We do NOT collect:
- Personal information
- Contents of files
- Specific text being typed
- Actual screenshots or screen contents
- User-specific identifiers
- API keys
- File contents
- Application data or content
- User interactions with the computer
- Information about files being accessed
## Controlling Telemetry
We are committed to transparency and user control over telemetry. There are two ways to control telemetry:
## 1. Environment Variable (Global Control)
Telemetry is enabled by default. To disable telemetry, set the `CUA_TELEMETRY_ENABLED` environment variable to a falsy value (`0`, `false`, `no`, or `off`):
```bash
# Disable telemetry before running your script
export CUA_TELEMETRY_ENABLED=false
# Or as part of the command
CUA_TELEMETRY_ENABLED=1 python your_script.py
```
Or from Python:
```python
import os
os.environ["CUA_TELEMETRY_ENABLED"] = "false"
```
## 2. Instance-Level Control
You can control telemetry for specific C/ua instances by setting `telemetry_enabled` when creating them:
```python
# Disable telemetry for a specific Computer instance
computer = Computer(telemetry_enabled=False)
# Enable telemetry for a specific Agent instance
agent = ComputerAgent(telemetry_enabled=True)
```
You can check if telemetry is enabled for an instance:
```python
print(computer.telemetry_enabled) # Will print True or False
```
Note that telemetry settings must be configured during initialization and cannot be changed after the object is created.
## Transparency
We believe in being transparent about the data we collect. If you have any questions about our telemetry practices, please open an issue on our GitHub repository.

13
docs/content/docs/v1/api/agent.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: Agent
---
The Agent API reference documentation is currently under development.
## Overview
The Agent library provides programmatic interfaces for AI agent interactions.
## API Documentation
Coming soon.

13
docs/content/docs/v1/api/computer-server.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: Computer
---
The Computer Server API reference documentation is currently under development.
## Overview
The Computer Server provides HTTP API endpoints for remote computer control and automation.
## API Documentation
Coming soon.

13
docs/content/docs/v1/api/computer.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: Computer
---
The Computer API reference documentation is currently under development.
## Overview
The Computer library provides programmatic interfaces for computer automation and control.
## API Documentation
Coming soon.

13
docs/content/docs/v1/api/core.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: Core
---
The Core API reference documentation is currently under development.
## Overview
The Core library provides foundational utilities and shared functionality across the CUA ecosystem.
## API Documentation
Coming soon.

4
docs/content/docs/v1/api/index.mdx
View File

@@ -1,4 +0,0 @@
---
title: API Reference Home
description: API Reference
---

207
docs/content/docs/v1/api/lume.mdx Normal file
View File

@@ -0,0 +1,207 @@
---
title: Lume
---
Lume exposes a local HTTP API server that listens on `http://localhost:7777/lume`, enabling automated management of VMs.
## Base URL
```
http://localhost:7777/lume
```
## Endpoints
<details open>
<summary><strong>Create VM</strong> - POST /vms</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
-H "Content-Type: application/json" \
-d '{
"name": "lume_vm",
"os": "macOS",
"cpu": 2,
"memory": "4GB",
"diskSize": "64GB",
"display": "1024x768",
"ipsw": "latest",
"storage": "ssd"
}' \
http://localhost:7777/lume/vms
```
</details>
<details open>
<summary><strong>Run VM</strong> - POST /vms/:name/run</summary>
```bash
# Basic run
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
http://localhost:7777/lume/vms/my-vm-name/run
# Run with VNC client started and shared directory
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
-H "Content-Type: application/json" \
-d '{
"noDisplay": false,
"sharedDirectories": [
{
"hostPath": "~/Projects",
"readOnly": false
}
],
"recoveryMode": false,
"storage": "ssd"
}' \
http://localhost:7777/lume/vms/lume_vm/run
```
</details>
<details open>
<summary><strong>List VMs</strong> - GET /vms</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
http://localhost:7777/lume/vms
```
```json
[
{
"name": "my-vm",
"state": "stopped",
"os": "macOS",
"cpu": 2,
"memory": "4GB",
"diskSize": "64GB"
},
{
"name": "my-vm-2",
"state": "stopped",
"os": "linux",
"cpu": 2,
"memory": "4GB",
"diskSize": "64GB"
}
]
```
</details>
<details open>
<summary><strong>Get VM Details</strong> - GET /vms/:name</summary>
```bash
# Basic get
curl --connect-timeout 6000 \
--max-time 5000 \
http://localhost:7777/lume/vms/lume_vm
# Get with specific storage
curl --connect-timeout 6000 \
--max-time 5000 \
http://localhost:7777/lume/vms/lume_vm?storage=ssd
```
```json
{
"name": "lume_vm",
"state": "stopped",
"os": "macOS",
"cpu": 2,
"memory": "4GB",
"diskSize": "64GB",
"display": "1024x768",
"ipAddress": "192.168.65.2",
"vncPort": 5900,
"sharedDirectories": [
{
"hostPath": "~/Projects",
"readOnly": false,
"tag": "com.apple.virtio-fs.automount"
}
]
}
```
</details>
<details open>
<summary><strong>Update VM Configuration</strong> - PUT /vms/:name</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X PUT \
-H "Content-Type: application/json" \
-d '{
"cpu": 4,
"memory": "8GB",
"diskSize": "100GB",
"display": "1920x1080",
"storage": "ssd"
}' \
http://localhost:7777/lume/vms/lume_vm
```
</details>
<details open>
<summary><strong>Stop VM</strong> - POST /vms/:name/stop</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
http://localhost:7777/lume/vms/lume_vm/stop
```
</details>
<details open>
<summary><strong>Delete VM</strong> - DELETE /vms/:name</summary>
```bash
# Basic delete
curl --connect-timeout 6000 \
--max-time 5000 \
-X DELETE \
http://localhost:7777/lume/vms/lume_vm
# Delete with specific storage
curl --connect-timeout 6000 \
--max-time 5000 \
-X DELETE \
http://localhost:7777/lume/vms/lume_vm?storage=ssd
```
</details>
<details open>
<summary><strong>Pull VM Image</strong> - POST /images/pull</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
-H "Content-Type: application/json" \
-d '{
"image": "macos-sequoia-vanilla:latest",
"registry": "ghcr.io",
"organization": "trycua",
"storage": "ssd"
}' \
http://localhost:7777/lume/images/pull
```
</details>

13
docs/content/docs/v1/api/lumier.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: Lumier
---
The Lumier API reference documentation is currently under development.
## Overview
The Lumier library provides Docker-based virtual machine management capabilities.
## API Documentation
Coming soon.

13
docs/content/docs/v1/api/mcp-server.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: MCP Server
---
The MCP Server API reference documentation is currently under development.
## Overview
The MCP Server provides Model Context Protocol endpoints for AI model integration.
## API Documentation
Coming soon.

12
docs/content/docs/v1/api/meta.json
View File

@@ -1,5 +1,15 @@
{
"title": "API Reference",
"description": "API Reference",
"root": true
"pages": [
"agent",
"computer",
"computer-server",
"core",
"lume",
"lumier",
"mcp-server",
"pylume",
"som"
]
}

13
docs/content/docs/v1/api/pylume.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: PyLume
---
The PyLume API reference documentation is currently under development.
## Overview
PyLume provides Python bindings for the Lume virtual machine management system.
## API Documentation
Coming soon.

13
docs/content/docs/v1/api/som.mdx Normal file
View File

@@ -0,0 +1,13 @@
---
title: Set-of-Mark
---
The SOM (Set-of-Mark) API reference documentation is currently under development.
## Overview
The SOM library provides visual element detection and interaction capabilities.
## API Documentation
Coming soon.

4
docs/content/docs/v1/libraries/agent.mdx
View File

@@ -14,7 +14,7 @@ title: Agent
>
<a href="#">
<img
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=333333"
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=blue"
alt="Python"
/>
</a>
@@ -32,7 +32,7 @@ title: Agent
</a>
<a href="https://pypi.org/project/cua-computer/">
<img
src="https://img.shields.io/pypi/v/cua-computer?color=333333"
src="https://img.shields.io/pypi/v/cua-computer?color=blue"
alt="PyPI"
/>
</a>

4
docs/content/docs/v1/libraries/computer-server.mdx
View File

@@ -14,7 +14,7 @@ title: Computer Server
>
<a href="#">
<img
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=333333"
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=blue"
alt="Python"
/>
</a>
@@ -32,7 +32,7 @@ title: Computer Server
</a>
<a href="https://pypi.org/project/cua-computer-server/">
<img
src="https://img.shields.io/pypi/v/cua-computer-server?color=333333"
src="https://img.shields.io/pypi/v/cua-computer-server?color=blue"
alt="PyPI"
/>
</a>

265
docs/content/docs/v1/libraries/computer.mdx Normal file
View File

@@ -0,0 +1,265 @@
---
title: Computer
---
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
<div
align="center"
style={{
display: 'flex',
gap: '10px',
margin: '0 auto',
width: '100%',
justifyContent: 'center',
}}
>
<a href="#">
<img
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=blue"
alt="Python"
/>
</a>
<a href="https://pypi.org/project/cua-computer/">
<img
src="https://img.shields.io/pypi/v/cua-computer?color=blue"
alt="PyPI"
/>
</a>
<a href="#">
<img
src="https://img.shields.io/badge/TypeScript-333333?logo=typescript&logoColor=white&labelColor=3178C6"
alt="TypeScript"
/>
</a>
<a href="https://www.npmjs.com/package/@cua/computer">
<img
alt="NPM Version"
src="https://img.shields.io/npm/v/react?color=CB3837"
/>
</a>
</div>
**cua-computer** is a Computer-Use Interface (CUI) framework powering Cua for interacting with local macOS and Linux sandboxes. It's PyAutoGUI-compatible and pluggable with any AI agent systems (Cua, Langchain, CrewAI, AutoGen). Computer relies on [Lume](https://github.com/trycua/lume) for creating and managing sandbox environments.
<div align="center">
<img src="/img/computer.png" />
</div>
## Key Features
- Create and manage virtual machine sandboxes
- Take screenshots of the virtual machine
- Control mouse movements and clicks
- Simulate keyboard input
- Manage clipboard content
- Interact with the operating system interface
- Support for macOS and Linux environments
## Installation
<Tabs groupId='language' persist items={['Python', 'TypeScript']}>
<Tab value="Python">
To install the Computer-Use Interface (CUI) for Python:
```bash
pip install "cua-computer[all]"
```
The `cua-computer` PyPi package pulls automatically the latest executable version of Lume through [pylume](https://github.com/trycua/pylume).
</Tab>
<Tab value="TypeScript">
To install the Computer-Use Interface (CUI) for TypeScript:
```bash
npm install @cua/computer
```
</Tab>
</Tabs>
## Quick Start
<Tabs groupId='language' persist items={['Python', 'TypeScript']}>
<Tab value="Python">
```python
from computer import Computer
computer = Computer(os_type="macos", display="1024x768", memory="8GB", cpu="4")
try:
await computer.run()
screenshot = await computer.interface.screenshot()
with open("screenshot.png", "wb") as f:
f.write(screenshot)
await computer.interface.move_cursor(100, 100)
await computer.interface.left_click()
await computer.interface.right_click(300, 300)
await computer.interface.double_click(400, 400)
await computer.interface.type("Hello, World!")
await computer.interface.press_key("enter")
await computer.interface.set_clipboard("Test clipboard")
content = await computer.interface.copy_to_clipboard()
print(f"Clipboard content: {content}")
finally:
await computer.stop()
```
</Tab>
<Tab value="TypeScript">
```typescript
import { Computer, OSType } from '@cua/computer';
const main = async () => {
// Create a cloud-based computer
const computer = new Computer({
name: 'cloud-vm',
osType: OSType.Linux,
apiKey: 'your-api-key',
});
// Access the interface
const interface = computer.interface;
// Screenshot operations
const screenshot = await interface.screenshot();
// Mouse operations
await interface.moveCursor(100, 100);
await interface.leftClick();
await interface.rightClick(300, 300);
await interface.doubleClick(400, 400);
await interface.dragTo(500, 500, 'left', 1000); // Drag with left button for 1 second
// Keyboard operations
await interface.typeText('Hello from TypeScript!');
await interface.pressKey('enter');
await interface.hotkey('command', 'a'); // Select all
// Clipboard operations
await interface.setClipboard('Clipboard content');
const content = await interface.copyToClipboard();
// File operations
await interface.writeText('/tmp/test.txt', 'Hello world');
const fileContent = await interface.readText('/tmp/test.txt');
// Run a command in the VM
const [stdout, stderr] = await interface.runCommand('ls -la');
// Disconnect from the cloud VM
await computer.disconnect();
};
main().catch(console.error);
```
</Tab>
</Tabs>
## Getting Started
<Tabs groupId='language' persist items={['Python', 'TypeScript']}>
<Tab value="Python">
Refer to this notebook for a step-by-step guide on how to use the Computer-Use Interface (CUI):
- [Computer-Use Interface (CUI)](https://github.com/trycua/cua/tree/main/notebooks/samples/computer_nb.ipynb)
</Tab>
<Tab value="TypeScript">
Check out the examples in the repository for more detailed usage patterns and advanced scenarios.
</Tab>
</Tabs>
## Using the Gradio Computer UI (Python Only)
The computer module includes a Gradio UI for creating and sharing demonstration data. We make it easy for people to build community datasets for better computer use models with an upload to Huggingface feature.
```bash
# Install with UI support
pip install "cua/computer[ui]"
```
> **Note:** For precise control of the computer, we recommend using VNC or Screen Sharing instead of the Computer Gradio UI.
### Building and Sharing Demonstrations with Huggingface
Follow these steps to contribute your own demonstrations:
#### 1. Set up Huggingface Access
Set your HF_TOKEN in a .env file or in your environment variables:
```bash
# In .env file
HF_TOKEN=your_huggingface_token
```
#### 2. Launch the Computer UI
```python
# launch_ui.py
from computer.ui.gradio.app import create_gradio_ui
from dotenv import load_dotenv
load_dotenv('.env')
app = create_gradio_ui()
app.launch(share=False)
```
For examples, see [Computer UI Examples](https://github.com/trycua/cua/tree/main/examples/computer_ui_examples.py)
#### 3. Record Your Tasks
<details open>
<summary>View demonstration video</summary>
<video
src="https://github.com/user-attachments/assets/de3c3477-62fe-413c-998d-4063e48de176"
controls
width="600"
></video>
</details>
Record yourself performing various computer tasks using the UI.
#### 4. Save Your Demonstrations
<details open>
<summary>View demonstration video</summary>
<video
src="https://github.com/user-attachments/assets/5ad1df37-026a-457f-8b49-922ae805faef"
controls
width="600"
></video>
</details>
Save each task by picking a descriptive name and adding relevant tags (e.g., "office", "web-browsing", "coding").
#### 5. Record Additional Demonstrations
Repeat steps 3 and 4 until you have a good amount of demonstrations covering different tasks and scenarios.
#### 6. Upload to Huggingface
<details open>
<summary>View demonstration video</summary>
<video
src="https://github.com/user-attachments/assets/c586d460-3877-4b5f-a736-3248886d2134"
controls
width="600"
></video>
</details>
Upload your dataset to Huggingface by:
- Naming it as `{your_username}/{dataset_name}`
- Choosing public or private visibility
- Optionally selecting specific tags to upload only tasks with certain tags
#### Examples and Resources
- Example Dataset: [ddupont/test-dataset](https://huggingface.co/datasets/ddupont/test-dataset)
- Find Community Datasets: 🔍 [Browse CUA Datasets on Huggingface](https://huggingface.co/datasets?other=cua)

32
docs/content/docs/v1/libraries/computer/index.mdx
View File

@@ -1,32 +0,0 @@
---
title: Computer
---
**@cua/computer** is a Computer-Use Interface (CUI) framework powering Cua for interacting with local macOS and Linux sandboxes. It's PyAutoGUI-compatible and pluggable with any AI agent systems (Cua, Langchain, CrewAI, AutoGen). Computer relies on [Lume](https://github.com/trycua/lume) for creating and managing sandbox environments.
<div align="center">
<img src="/img/computer.png" />
</div>
## Available Implementations
The Computer library is available in multiple programming languages:
- [Python Implementation](/home/libraries/computer/python) - For Python developers
- [TypeScript Implementation](/home/libraries/computer/typescript) - For TypeScript/JavaScript developers
Both implementations offer equivalent functionality with language-specific syntax and conventions.
## Key Features
- Create and manage virtual machine sandboxes
- Take screenshots of the virtual machine
- Control mouse movements and clicks
- Simulate keyboard input
- Manage clipboard content
- Interact with the operating system interface
- Support for macOS and Linux environments
## Getting Started
Select your preferred language implementation from the links above to get started with installation instructions and usage examples.

173
docs/content/docs/v1/libraries/computer/python.mdx
View File

@@ -1,173 +0,0 @@
---
title: Computer (Python)
---
<div
align="center"
style={{
display: 'flex',
gap: '10px',
margin: '0 auto',
width: '100%',
justifyContent: 'center',
}}
>
<a href="#">
<img
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=333333"
alt="Python"
/>
</a>
<a href="#">
<img
src="https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=F0F0F0"
alt="macOS"
/>
</a>
<a href="https://discord.com/invite/mVnXXpdE85">
<img
src="https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white"
alt="Discord"
/>
</a>
<a href="https://pypi.org/project/cua-computer/">
<img
src="https://img.shields.io/pypi/v/cua-computer?color=333333"
alt="PyPI"
/>
</a>
</div>
## Python API
```python
from computer import Computer
computer = Computer(os_type="macos", display="1024x768", memory="8GB", cpu="4")
try:
await computer.run()
screenshot = await computer.interface.screenshot()
with open("screenshot.png", "wb") as f:
f.write(screenshot)
await computer.interface.move_cursor(100, 100)
await computer.interface.left_click()
await computer.interface.right_click(300, 300)
await computer.interface.double_click(400, 400)
await computer.interface.type("Hello, World!")
await computer.interface.press_key("enter")
await computer.interface.set_clipboard("Test clipboard")
content = await computer.interface.copy_to_clipboard()
print(f"Clipboard content: {content}")
finally:
await computer.stop()
```
## Install
To install the Computer-Use Interface (CUI) for Python:
```bash
pip install "@cua/computer[all]"
```
The `@cua/computer` PyPi package pulls automatically the latest executable version of Lume through [pylume](https://github.com/trycua/pylume).
## Run
Refer to this notebook for a step-by-step guide on how to use the Computer-Use Interface (CUI):
- [Computer-Use Interface (CUI)](https://github.com/trycua/cua/tree/main/notebooks/samples/computer_nb.ipynb)
## Using the Gradio Computer UI
The computer module includes a Gradio UI for creating and sharing demonstration data. We make it easy for people to build community datasets for better computer use models with an upload to Huggingface feature.
```bash
# Install with UI support
pip install "@cua/computer[ui]"
```
> **Note:** For precise control of the computer, we recommend using VNC or Screen Sharing instead of the Computer Gradio UI.
### Building and Sharing Demonstrations with Huggingface
Follow these steps to contribute your own demonstrations:
#### 1. Set up Huggingface Access
Set your HF_TOKEN in a .env file or in your environment variables:
```bash
# In .env file
HF_TOKEN=your_huggingface_token
```
#### 2. Launch the Computer UI
```python
# launch_ui.py
from computer.ui.gradio.app import create_gradio_ui
from dotenv import load_dotenv
load_dotenv('.env')
app = create_gradio_ui()
app.launch(share=False)
```
For examples, see [Computer UI Examples](https://github.com/trycua/cua/tree/main/examples/computer_ui_examples.py)
#### 3. Record Your Tasks
<details open>
<summary>View demonstration video</summary>
<video
src="https://github.com/user-attachments/assets/de3c3477-62fe-413c-998d-4063e48de176"
controls
width="600"
></video>
</details>
Record yourself performing various computer tasks using the UI.
#### 4. Save Your Demonstrations
<details open>
<summary>View demonstration video</summary>
<video
src="https://github.com/user-attachments/assets/5ad1df37-026a-457f-8b49-922ae805faef"
controls
width="600"
></video>
</details>
Save each task by picking a descriptive name and adding relevant tags (e.g., "office", "web-browsing", "coding").
#### 5. Record Additional Demonstrations
Repeat steps 3 and 4 until you have a good amount of demonstrations covering different tasks and scenarios.
#### 6. Upload to Huggingface
<details open>
<summary>View demonstration video</summary>
<video
src="https://github.com/user-attachments/assets/c586d460-3877-4b5f-a736-3248886d2134"
controls
width="600"
></video>
</details>
Upload your dataset to Huggingface by:
- Naming it as `{your_username}/{dataset_name}`
- Choosing public or private visibility
- Optionally selecting specific tags to upload only tasks with certain tags
#### Examples and Resources
- Example Dataset: [ddupont/test-dataset](https://huggingface.co/datasets/ddupont/test-dataset)
- Find Community Datasets: 🔍 [Browse CUA Datasets on Huggingface](https://huggingface.co/datasets?other=cua)

98
docs/content/docs/v1/libraries/computer/typescript.mdx
View File

@@ -1,98 +0,0 @@
---
title: Computer (TypeScript)
---
<div
align="center"
style={{
display: 'flex',
gap: '10px',
margin: '0 auto',
width: '100%',
justifyContent: 'center',
}}
>
<a href="#">
<img
src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white&labelColor=3178C6"
alt="TypeScript"
/>
</a>
<a href="#">
<img
src="https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=F0F0F0"
alt="macOS"
/>
</a>
<a href="https://discord.com/invite/mVnXXpdE85">
<img
src="https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white"
alt="Discord"
/>
</a>
<a href="https://www.npmjs.com/package/@cua/computer">
<img
src="https://img.shields.io/npm/v/@cua/computer?color=3178C6"
alt="npm"
/>
</a>
</div>
## TypeScript API
## Install
To install the Computer-Use Interface (CUI) for TypeScript:
```bash
npm install @cua/computer
# or
yarn add @cua/computer
```
```typescript
import { CloudComputer, OSType } from '@cua/computer';
const main = async () => {
// Create a cloud-based computer
const computer = new CloudComputer({
name: 'cloud-vm',
osType: OSType.Linux,
apiKey: 'your-api-key',
});
// Access the interface
const interface = computer.interface;
// Screenshot operations
const screenshot = await interface.screenshot();
// Mouse operations
await interface.moveCursor(100, 100);
await interface.leftClick();
await interface.rightClick(300, 300);
await interface.doubleClick(400, 400);
await interface.dragTo(500, 500, 'left', 1000); // Drag with left button for 1 second
// Keyboard operations
await interface.typeText('Hello from TypeScript!');
await interface.pressKey('enter');
await interface.hotkey('command', 'a'); // Select all
// Clipboard operations
await interface.setClipboard('Clipboard content');
const content = await interface.copyToClipboard();
// File operations
await interface.writeText('/tmp/test.txt', 'Hello world');
const fileContent = await interface.readText('/tmp/test.txt');
// Run a command in the VM
const [stdout, stderr] = await interface.runCommand('ls -la');
// Disconnect from the cloud VM
await computer.disconnect();
};
main().catch(console.error);
```

4
docs/content/docs/v1/libraries/core.mdx
View File

@@ -14,7 +14,7 @@ title: c/ua Core
>
<a href="#">
<img
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=333333"
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=blue"
alt="Python"
/>
</a>
@@ -32,7 +32,7 @@ title: c/ua Core
</a>
<a href="https://pypi.org/project/cua-computer-server/">
<img
src="https://img.shields.io/pypi/v/cua-computer-server?color=333333"
src="https://img.shields.io/pypi/v/cua-computer-server?color=blue"
alt="PyPI"
/>
</a>

101
docs/content/docs/v1/libraries/lume/index.mdx → docs/content/docs/v1/libraries/lume.mdx
View File

@@ -44,16 +44,23 @@ title: Lume
lume run macos-sequoia-vanilla:latest
```
## Development Environment
## Install
If you're working on Lume in the context of the C/ua monorepo, we recommend using the dedicated VS Code workspace configuration:
Install with a single command:
```bash
# Open VS Code workspace from the root of the monorepo
code .vscode/lume.code-workspace
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
```
This workspace is preconfigured with Swift language support, build tasks, and debug configurations.
By default, Lume is installed as a background service that starts automatically on login. If you prefer to start the Lume API service manually when needed, you can use the `--no-background-service` option:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh) --no-background-service"
```
**Note:** With this option, you'll need to manually start the Lume API service by running `lume serve` in your terminal whenever you need to use tools or libraries that rely on the Lume API (such as the Computer-Use Agent).
You can also download the `lume.pkg.tar.gz` archive from the [latest release](https://github.com/trycua/lume/releases), extract it, and install the package manually.
## Usage
@@ -156,24 +163,6 @@ Command Options:
--port <port> Port to listen on (default: 7777)
```
## Install
Install with a single command:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
```
By default, Lume is installed as a background service that starts automatically on login. If you prefer to start the Lume API service manually when needed, you can use the `--no-background-service` option:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh) --no-background-service"
```
**Note:** With this option, you'll need to manually start the Lume API service by running `lume serve` in your terminal whenever you need to use tools or libraries that rely on the Lume API (such as the Computer-Use Agent).
You can also download the `lume.pkg.tar.gz` archive from the [latest release](https://github.com/trycua/lume/releases), extract it, and install the package manually.
## Prebuilt Images
Pre-built images are available in the registry [ghcr.io/trycua](https://github.com/orgs/trycua/packages).
@@ -201,13 +190,69 @@ For additional disk space, resize the VM disk after pulling the image using the
lume serve
```
For detailed API documentation, please refer to [API Reference](./api-reference).
For detailed API documentation, see the [API Reference](/v1/api/lume).
## Docs
## Development
- [API Reference](./api-reference)
- [Development](./development)
- [FAQ](./faq)
If you're working on Lume in the context of the C/ua monorepo, we recommend using the dedicated VS Code workspace configuration:
```bash
# Open VS Code workspace from the root of the monorepo
code .vscode/lume.code-workspace
```
This workspace is preconfigured with Swift language support, build tasks, and debug configurations.
## FAQ
### What is Lume?
Lume is a lightweight Command Line Interface and local API server to create, run and manage macOS and Linux virtual machines (VMs) with near-native performance on Apple Silicon, using Apple's `Virtualization.Framework`.
### What are the system requirements?
- Apple Silicon Mac (M1, M2, M3, etc.)
- macOS 13.0 or later
- At least 8GB of RAM (16GB recommended)
- At least 50GB of free disk space
### How do I change the default password for VMs?
The default password for all prebuilt images is `lume`. For security, change it immediately after your first login using the `passwd` command.
### Can I run multiple VMs simultaneously?
Yes, you can run multiple VMs at the same time as long as your system has sufficient resources (CPU, memory, and disk space).
### How do I share files between the host and VM?
Use the `--shared-dir` option when running a VM:
```bash
lume run my-vm --shared-dir ~/Projects:rw
```
The shared directory will be automatically mounted in the VM.
### Where are VM files stored?
By default, VMs are stored in `~/.lume/vms/`. You can configure additional storage locations using the `lume config storage` commands.
### How do I access the VM's display?
Lume automatically starts a VNC client when you run a VM. You can also connect manually using any VNC client to the port shown in the VM details.
### Can I use Lume programmatically?
Yes, Lume provides a local HTTP API server. Start it with `lume serve` and access it at `http://localhost:7777/lume`.
### How do I update Lume?
Run the install script again to update to the latest version:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
```
## Contributing

405
docs/content/docs/v1/libraries/lume/API-Reference.mdx
View File

@@ -1,405 +0,0 @@
---
title: API Reference
## API Reference
---
<details open>
<summary><strong>Create VM</strong> - POST /vms</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
-H "Content-Type: application/json" \
-d '{
"name": "lume_vm",
"os": "macOS",
"cpu": 2,
"memory": "4GB",
"diskSize": "64GB",
"display": "1024x768",
"ipsw": "latest",
"storage": "ssd"
}' \
http://localhost:7777/lume/vms
```
</details>
<details open>
<summary><strong>Run VM</strong> - POST /vms/:name/run</summary>
```bash
# Basic run
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
http://localhost:7777/lume/vms/my-vm-name/run
# Run with VNC client started and shared directory
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
-H "Content-Type: application/json" \
-d '{
"noDisplay": false,
"sharedDirectories": [
{
"hostPath": "~/Projects",
"readOnly": false
}
],
"recoveryMode": false,
"storage": "ssd"
}' \
http://localhost:7777/lume/vms/lume_vm/run
```
</details>
<details open>
<summary><strong>List VMs</strong> - GET /vms</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
http://localhost:7777/lume/vms
```
```
[
{
"name": "my-vm",
"state": "stopped",
"os": "macOS",
"cpu": 2,
"memory": "4GB",
"diskSize": "64GB"
},
{
"name": "my-vm-2",
"state": "stopped",
"os": "linux",
"cpu": 2,
"memory": "4GB",
"diskSize": "64GB"
}
]
```
</details>
<details open>
<summary><strong>Get VM Details</strong> - GET /vms/:name</summary>
```bash
# Basic get
curl --connect-timeout 6000 \
--max-time 5000 \
http://localhost:7777/lume/vms/lume_vm
# Get with storage location specified
curl --connect-timeout 6000 \
--max-time 5000 \
http://localhost:7777/lume/vms/lume_vm?storage=ssd
```
```
{
"name": "lume_vm",
"state": "running",
"os": "macOS",
"cpu": 2,
"memory": "4GB",
"diskSize": "64GB"
}
```
</details>
<details open>
<summary><strong>Update VM Settings</strong> - PATCH /vms/:name</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X PATCH \
-H "Content-Type: application/json" \
-d '{
"cpu": 4,
"memory": "8GB",
"diskSize": "128GB",
"storage": "ssd"
}' \
http://localhost:7777/lume/vms/my-vm-name
```
</details>
<details open>
<summary><strong>Stop VM</strong> - POST /vms/:name/stop</summary>
```bash
# Basic stop
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
http://localhost:7777/lume/vms/my-vm-name/stop
# Stop with storage location specified
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
http://localhost:7777/lume/vms/my-vm-name/stop?storage=ssd
```
</details>
<details open>
<summary><strong>Delete VM</strong> - DELETE /vms/:name</summary>
```bash
# Basic delete
curl --connect-timeout 6000 \
--max-time 5000 \
-X DELETE \
http://localhost:7777/lume/vms/my-vm-name
# Delete with storage location specified
curl --connect-timeout 6000 \
--max-time 5000 \
-X DELETE \
http://localhost:7777/lume/vms/my-vm-name?storage=ssd
```
</details>
<details open>
<summary><strong>Pull Image</strong> - POST /pull</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
-H "Content-Type: application/json" \
-d '{
"image": "macos-sequoia-vanilla:latest",
"name": "my-vm-name",
"registry": "ghcr.io",
"organization": "trycua",
"storage": "ssd"
}' \
http://localhost:7777/lume/pull
```
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
-H "Content-Type: application/json" \
-d '{
"image": "macos-sequoia-vanilla:15.2",
"name": "macos-sequoia-vanilla"
}' \
http://localhost:7777/lume/pull
```
</details>
<details open>
<summary><strong>Push Image (Async)</strong> - POST /vms/push</summary>
```bash
# Push VM 'my-local-vm' to 'my-org/my-image:latest' and 'my-org/my-image:v1'
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
-H "Content-Type: application/json" \
-d '{
"name": "my-local-vm",
"imageName": "my-image",
"tags": ["latest", "v1"],
"organization": "my-org",
"registry": "ghcr.io",
"chunkSizeMb": 512,
"storage": null
}' \
http://localhost:7777/lume/vms/push
```
**Response (202 Accepted):**
```json
{
"message": "Push initiated in background",
"name": "my-local-vm",
"imageName": "my-image",
"tags": ["latest", "v1"]
}
```
</details>
<details open>
<summary><strong>Clone VM</strong> - POST /vms/:name/clone</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
-H "Content-Type: application/json" \
-d '{
"name": "source-vm",
"newName": "cloned-vm",
"sourceLocation": "default",
"destLocation": "ssd"
}' \
http://localhost:7777/lume/vms/clone
```
</details>
<details open>
<summary><strong>Get Latest IPSW URL</strong> - GET /ipsw</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
http://localhost:7777/lume/ipsw
```
</details>
<details open>
<summary><strong>List Images</strong> - GET /images</summary>
```bash
# List images with default organization (trycua)
curl --connect-timeout 6000 \
--max-time 5000 \
http://localhost:7777/lume/images
```
```json
{
"local": ["macos-sequoia-xcode:latest", "macos-sequoia-vanilla:latest"]
}
```
</details>
<details open>
<summary><strong>Prune Images</strong> - POST /lume/prune</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
http://localhost:7777/lume/prune
```
</details>
<details open>
<summary><strong>Get Configuration</strong> - GET /lume/config</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
http://localhost:7777/lume/config
```
```json
{
"homeDirectory": "~/.lume",
"cacheDirectory": "~/.lume/cache",
"cachingEnabled": true
}
```
</details>
<details open>
<summary><strong>Update Configuration</strong> - POST /lume/config</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
-H "Content-Type: application/json" \
-d '{
"homeDirectory": "~/custom/lume",
"cacheDirectory": "~/custom/lume/cache",
"cachingEnabled": true
}' \
http://localhost:7777/lume/config
```
</details>
<details open>
<summary><strong>Get VM Storage Locations</strong> - GET /lume/config/locations</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
http://localhost:7777/lume/config/locations
```
```json
[
{
"name": "default",
"path": "~/.lume/vms",
"isDefault": true
},
{
"name": "ssd",
"path": "/Volumes/SSD/lume/vms",
"isDefault": false
}
]
```
</details>
<details open>
<summary><strong>Add VM Storage Location</strong> - POST /lume/config/locations</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
-H "Content-Type: application/json" \
-d '{
"name": "ssd",
"path": "/Volumes/SSD/lume/vms"
}' \
http://localhost:7777/lume/config/locations
```
</details>
<details open>
<summary><strong>Remove VM Storage Location</strong> - DELETE /lume/config/locations/:name</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X DELETE \
http://localhost:7777/lume/config/locations/ssd
```
</details>
<details open>
<summary><strong>Set Default VM Storage Location</strong> - POST /lume/config/locations/default/:name</summary>
```bash
curl --connect-timeout 6000 \
--max-time 5000 \
-X POST \
http://localhost:7777/lume/config/locations/default/ssd
```
</details>

50
docs/content/docs/v1/libraries/lume/Development.mdx
View File

@@ -1,50 +0,0 @@
---
title: Development Guide
---
# Development Guide
This guide will help you set up your development environment and understand the process for contributing code to lume.
## Environment Setup
Lume development requires:
- Swift 6 or higher
- Xcode 15 or higher
- macOS Sequoia 15.2 or higher
- (Optional) VS Code with Swift extension
## Setting Up the Repository Locally
1. **Fork the Repository**: Create your own fork of lume
2. **Clone the Repository**:
```bash
git clone https://github.com/trycua/lume.git
cd lume
```
3. **Install Dependencies**:
```bash
swift package resolve
```
4. **Build the Project**:
```bash
swift build
```
## Development Workflow
1. Create a new branch for your changes
2. Make your changes
3. Run the tests: `swift test`
4. Build and test your changes locally
5. Commit your changes with clear commit messages
## Submitting Pull Requests
1. Push your changes to your fork
2. Open a Pull Request with:
- A clear title and description
- Reference to any related issues
- Screenshots or logs if relevant
3. Respond to any feedback from maintainers

122
docs/content/docs/v1/libraries/lume/FAQ.mdx
View File

@@ -1,122 +0,0 @@
---
title: FAQs
---
# FAQs
### Where are the VMs stored?
VMs are stored in `~/.lume` by default. You can configure additional storage locations using the `lume config` command.
### How are images cached?
Images are cached in `~/.lume/cache`. When doing `lume pull <image>`, it will check if the image is already cached. If not, it will download the image and cache it, removing any older versions.
### Where is the configuration file stored?
Lume follows the XDG Base Directory specification for the configuration file:
- Configuration is stored in `$XDG_CONFIG_HOME/lume/config.yaml` (defaults to `~/.config/lume/config.yaml`)
By default, other data is stored in:
- VM data: `~/.lume`
- Cache files: `~/.lume/cache`
The config file contains settings for:
- VM storage locations and the default location
- Cache directory location
- Whether caching is enabled
You can view and modify these settings using the `lume config` commands:
```bash
# View current configuration
lume config get
# Manage VM storage locations
lume config storage list # List all VM storage locations
lume config storage add <name> <path> # Add a new VM storage location
lume config storage remove <name> # Remove a VM storage location
lume config storage default <name> # Set the default VM storage location
# Manage cache settings
lume config cache get # Get current cache directory
lume config cache set <path> # Set cache directory
# Manage image caching settings
lume config caching get # Show current caching status
lume config caching set <boolean> # Enable or disable image caching
```
### How do I use multiple VM storage locations?
Lume supports storing VMs in different locations (e.g., internal drive, external SSD). After configuring storage locations, you can specify which location to use with the `--storage` parameter in various commands:
```bash
# Create a VM in a specific storage location
lume create my-vm --os macos --ipsw latest --storage ssd
# Run a VM from a specific storage location
lume run my-vm --storage ssd
# Delete a VM from a specific storage location
lume delete my-vm --storage ssd
# Pull an image to a specific storage location
lume pull macos-sequoia-vanilla:latest --name my-vm --storage ssd
# Clone a VM between storage locations
lume clone source-vm cloned-vm --source-storage default --dest-storage ssd
```
If you don't specify a storage location, Lume will use the default one or search across all configured locations.
### Are VM disks taking up all the disk space?
No, macOS uses sparse files, which only allocate space as needed. For example, VM disks totaling 50 GB may only use 20 GB on disk.
### How do I get the latest macOS restore image URL?
```bash
lume ipsw
```
### How do I delete a VM?
```bash
lume delete <name>
```
### How to Install macOS from an IPSW Image
#### Create a new macOS VM using the latest supported IPSW image:
Run the following command to create a new macOS virtual machine using the latest available IPSW image:
```bash
lume create <name> --os macos --ipsw latest
```
#### Create a new macOS VM using a specific IPSW image:
To create a macOS virtual machine from an older or specific IPSW file, first download the desired IPSW (UniversalMac) from a trusted source.
Then, use the downloaded IPSW path:
```bash
lume create <name> --os macos --ipsw <downloaded_ipsw_path>
```
### How do I install a custom Linux image?
The process for creating a custom Linux image differs than macOS, with IPSW restore files not being used. You need to create a linux VM first, then mount a setup image file to the VM for the first boot.
```bash
lume create <name> --os linux
lume run <name> --mount <path-to-setup-image>
lume run <name>
```

2
docs/content/docs/v1/libraries/mcp-server.mdx
View File

@@ -32,7 +32,7 @@ title: MCP Server
</a>
<a href="https://pypi.org/project/cua-computer/">
<img
src="https://img.shields.io/pypi/v/cua-computer?color=333333"
src="https://img.shields.io/pypi/v/cua-computer?color=blue"
alt="Python"
/>
</a>

4
docs/content/docs/v1/libraries/pylume.mdx
View File

@@ -14,7 +14,7 @@ title: PyLume
>
<a href="#">
<img
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=333333"
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=blue"
alt="Python"
/>
</a>
@@ -31,7 +31,7 @@ title: PyLume
/>
</a>
<a href="https://pypi.org/project/pylume/">
<img src="https://img.shields.io/pypi/v/pylume?color=333333" alt="PyPI" />
<img src="https://img.shields.io/pypi/v/pylume?color=blue" alt="PyPI" />
</a>
</div>

4
docs/content/docs/v1/libraries/som.mdx
View File

@@ -14,7 +14,7 @@ title: Set-of-Mark
>
<a href="#">
<img
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=333333"
src="https://img.shields.io/badge/Python-333333?logo=python&logoColor=white&labelColor=blue"
alt="Python"
/>
</a>
@@ -32,7 +32,7 @@ title: Set-of-Mark
</a>
<a href="https://pypi.org/project/cua-computer/">
<img
src="https://img.shields.io/pypi/v/cua-computer?color=333333"
src="https://img.shields.io/pypi/v/cua-computer?color=blue"
alt="PyPI"
/>
</a>

9
docs/content/docs/v1/meta.json
View File

@@ -4,10 +4,9 @@
"root": true,
"defaultOpen": true,
"pages": [
"libraries",
"api",
"faq",
"developer-guide",
"telemetry"
"---Libraries---",
"...libraries",
"---API Reference---",
"...api"
]
}

11
docs/src/app/(home)/layout.tsx
View File

@@ -13,7 +13,16 @@ export default function Layout({ children }: { children: ReactNode }) {
{
url: "/v1",
title: "API v1",
icon: <CodeXml />,
icon: <div
className="rounded-lg bg-blue-500/10 border max-md:p-1.5 p-1"
style={
{
color: 'var(--color-blue-500)',
} as object
}
>
<CodeXml />
</div>
},
],
}}