mirror of
https://github.com/trycua/lume.git
synced 2025-12-31 01:19:57 -06:00
change vm/container to sandbox
This commit is contained in:
Sarina Li
@@ -29,4 +29,7 @@ venv/
|
||||
*.db
|
||||
*.sqlite
|
||||
pnpm-lock.yaml
|
||||
uv.lock
|
||||
uv.lock
|
||||
|
||||
# Docs with complex JSX formatting
|
||||
docs/content/docs/get-started/quickstart.mdx
|
||||
@@ -89,7 +89,7 @@ Use the following environment variables to configure the agent and its access to
|
||||
|
||||
```bash
|
||||
# Computer instance (cloud)
|
||||
export CUA_CONTAINER_NAME="your-container-name"
|
||||
export CUA_SANDBOX_NAME="your-sandbox-name"
|
||||
export CUA_API_KEY="your-cua-api-key"
|
||||
|
||||
# LLM API keys
|
||||
|
||||
@@ -1,17 +1,17 @@
|
||||
---
|
||||
title: Cloud VM Management
|
||||
description: Manage your Cua Cloud sandboxes (VMs) via Python SDK or HTTP API
|
||||
title: Cloud Sandbox Management
|
||||
description: Manage your Cua Cloud sandboxes via Python SDK or HTTP API
|
||||
---
|
||||
|
||||
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
|
||||
|
||||
Using the Cua Cloud API, you can manage your Cua Cloud sandboxes (VMs) with Python or HTTP (curl).
|
||||
Using the Cua Cloud API, you can manage your Cua Cloud sandboxes with Python or HTTP (curl).
|
||||
|
||||
All examples require a CUA API key. You can obtain one from the [Dashboard](https://www.cua.ai/dashboard/keys).
|
||||
|
||||
---
|
||||
|
||||
## List VMs
|
||||
## List Sandboxes
|
||||
|
||||
<Tabs items={['Python', 'curl']}>
|
||||
<Tab value="Python">
|
||||
@@ -51,7 +51,7 @@ curl -H "Authorization: Bearer $CUA_API_KEY" \
|
||||
|
||||
Responses:
|
||||
|
||||
- 200: Array of minimal VM objects with fields `{ name, password, status }`
|
||||
- 200: Array of minimal sandbox objects with fields `{ name, password, status }`
|
||||
- 401: Unauthorized (missing/invalid API key)
|
||||
|
||||
```json
|
||||
@@ -66,11 +66,11 @@ Responses:
|
||||
|
||||
Status values:
|
||||
|
||||
- `pending`: VM deployment in progress
|
||||
- `running`: VM is active and accessible
|
||||
- `stopped`: VM is stopped but not terminated
|
||||
- `terminated`: VM has been permanently destroyed
|
||||
- `failed`: VM deployment or operation failed
|
||||
- `pending`: Sandbox deployment in progress
|
||||
- `running`: Sandbox is active and accessible
|
||||
- `stopped`: Sandbox is stopped but not terminated
|
||||
- `terminated`: Sandbox has been permanently destroyed
|
||||
- `failed`: Sandbox deployment or operation failed
|
||||
|
||||
---
|
||||
|
||||
@@ -80,9 +80,9 @@ Status values:
|
||||
|
||||
---
|
||||
|
||||
## Start a VM
|
||||
## Start a Sandbox
|
||||
|
||||
Provide the VM name you want to start.
|
||||
Provide the sandbox name you want to start.
|
||||
|
||||
<Tabs items={["Python", "curl"]}>
|
||||
<Tab value="Python">
|
||||
@@ -118,7 +118,7 @@ Responses:
|
||||
|
||||
- 204: No Content (start accepted)
|
||||
- 401: Unauthorized (missing/invalid API key)
|
||||
- 404: VM not found or not owned by the user
|
||||
- 404: Sandbox not found or not owned by the user
|
||||
|
||||
```text
|
||||
HTTP/1.1 204 No Content
|
||||
@@ -129,9 +129,9 @@ HTTP/1.1 204 No Content
|
||||
|
||||
---
|
||||
|
||||
## Stop a VM
|
||||
## Stop a Sandbox
|
||||
|
||||
Stops the VM asynchronously.
|
||||
Stops the sandbox asynchronously.
|
||||
|
||||
<Tabs items={["Python", "curl"]}>
|
||||
<Tab value="Python">
|
||||
@@ -167,7 +167,7 @@ Responses:
|
||||
|
||||
- 202: Accepted with `{ "status": "stopping" }`
|
||||
- 401: Unauthorized (missing/invalid API key)
|
||||
- 404: VM not found or not owned by the user
|
||||
- 404: Sandbox not found or not owned by the user
|
||||
|
||||
```json
|
||||
{ "status": "stopping" }
|
||||
@@ -178,9 +178,9 @@ Responses:
|
||||
|
||||
---
|
||||
|
||||
## Restart a VM
|
||||
## Restart a Sandbox
|
||||
|
||||
Restarts the VM asynchronously.
|
||||
Restarts the sandbox asynchronously.
|
||||
|
||||
<Tabs items={["Python", "curl"]}>
|
||||
<Tab value="Python">
|
||||
@@ -216,7 +216,7 @@ Responses:
|
||||
|
||||
- 202: Accepted with `{ "status": "restarting" }`
|
||||
- 401: Unauthorized (missing/invalid API key)
|
||||
- 404: VM not found or not owned by the user
|
||||
- 404: Sandbox not found or not owned by the user
|
||||
|
||||
```json
|
||||
{ "status": "restarting" }
|
||||
@@ -227,9 +227,9 @@ Responses:
|
||||
|
||||
---
|
||||
|
||||
## Query a VM by name
|
||||
## Query a Sandbox by name
|
||||
|
||||
Query the computer-server running on the VM. Useful for checking details like status or OS type.
|
||||
Query the computer-server running on the sandbox. Useful for checking details like status or OS type.
|
||||
|
||||
<Tabs items={["Python", "curl"]}>
|
||||
<Tab value="Python">
|
||||
|
||||
@@ -18,7 +18,7 @@ Execute shell commands and get detailed results:
|
||||
# Run shell command
|
||||
result = await computer.interface.run_command(cmd) # result.stdout, result.stderr, result.returncode
|
||||
```
|
||||
|
||||
|
||||
</Tab>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
@@ -230,7 +230,7 @@ Control desktop environment features like wallpaper:
|
||||
env = await computer.interface.get_desktop_environment()
|
||||
print(env) # "xfce4"
|
||||
|
||||
# Set desktop wallpaper to an image file accessible on the VM
|
||||
# Set desktop wallpaper to an image file accessible on the sandbox
|
||||
await computer.interface.set_wallpaper("/home/cua/shared/wallpaper.png")
|
||||
```
|
||||
|
||||
@@ -241,7 +241,7 @@ Control desktop environment features like wallpaper:
|
||||
const env = await computer.interface.getDesktopEnvironment();
|
||||
print(env) # "xfce4"
|
||||
|
||||
// Set desktop wallpaper to an image file accessible on the VM
|
||||
// Set desktop wallpaper to an image file accessible on the sandbox
|
||||
await computer.interface.setWallpaper('/home/cua/shared/wallpaper.png');
|
||||
```
|
||||
|
||||
|
||||
@@ -8,13 +8,13 @@ description: Understanding Cua computer types and connection methods
|
||||
|
||||
Before we can automate apps using AI, we need to first connect to a Computer Server to give the AI a safe environment to execute workflows in.
|
||||
|
||||
Cua Computers are preconfigured virtual machines running the Computer Server. They can be either macOS, Linux, or Windows. They're found in either a cloud-native container, or on your host desktop.
|
||||
Cua Computers are preconfigured sandboxes running the Computer Server. They can be either macOS, Linux, or Windows. They're found in either a cloud-native sandbox, or on your host desktop.
|
||||
|
||||
## Cloud Sandbox
|
||||
|
||||
**Easiest & safest way to get started - works on any host OS**
|
||||
|
||||
This is a Cloud Sandbox running the Computer Server. Get a container at [cua.ai](https://cua.ai/).
|
||||
This is a Cloud Sandbox running the Computer Server. Get a sandbox at [cua.ai](https://cua.ai/).
|
||||
|
||||
<Tabs items={['Python', 'TypeScript']}>
|
||||
<Tab value="Python">
|
||||
@@ -76,7 +76,7 @@ Cua provides two Docker images for running Linux desktops:
|
||||
os_type="linux",
|
||||
provider_type="docker",
|
||||
image="trycua/cua-xfce:latest",
|
||||
name="my-xfce-container"
|
||||
name="my-xfce-sandbox"
|
||||
)
|
||||
|
||||
await computer.run() # Launch & connect to Docker sandbox
|
||||
@@ -109,7 +109,7 @@ Cua provides two Docker images for running Linux desktops:
|
||||
os_type="linux",
|
||||
provider_type="docker",
|
||||
image="trycua/cua-ubuntu:latest",
|
||||
name="my-kasm-container"
|
||||
name="my-kasm-sandbox"
|
||||
)
|
||||
|
||||
await computer.run() # Launch & connect to Docker sandbox
|
||||
@@ -143,7 +143,7 @@ computer = Computer(
|
||||
await computer.run() # Launch & connect to Windows Sandbox
|
||||
```
|
||||
|
||||
## macOS VM
|
||||
## macOS Sandbox
|
||||
|
||||
**macOS hosts only - requires Lume CLI**
|
||||
|
||||
@@ -153,7 +153,7 @@ await computer.run() # Launch & connect to Windows Sandbox
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
|
||||
```
|
||||
|
||||
2. Start a local Cua macOS VM
|
||||
2. Start a local Cua macOS sandbox
|
||||
|
||||
```bash
|
||||
lume run macos-sequoia-cua:latest
|
||||
|
||||
@@ -33,7 +33,7 @@ def read_file(location: str) -> str:
|
||||
return f.read()
|
||||
|
||||
async def main():
|
||||
async with Computer(os_type="linux", provider_type="cloud", name="my-container", api_key="...") as computer:
|
||||
async with Computer(os_type="linux", provider_type="cloud", name="my-sandbox", api_key="...") as computer:
|
||||
# Call the sandboxed function (runs remotely)
|
||||
result = await read_file("/etc/hostname")
|
||||
print(result)
|
||||
@@ -60,7 +60,7 @@ await my_computer.venv_install("myenv", ["requests"])
|
||||
You can use sandboxed functions to interact with macOS applications on a local Cua Computer (requires `os_type="darwin"`). This is particularly useful for automation tasks that involve GUI applications.
|
||||
|
||||
```python
|
||||
# Example: Use sandboxed functions to execute code in a Cua Container
|
||||
# Example: Use sandboxed functions to execute code in a Cua Sandbox
|
||||
from computer.helpers import sandboxed
|
||||
|
||||
await computer.venv_install("demo_venv", ["macos-pyxa"]) # Install packages in a virtual environment
|
||||
@@ -71,10 +71,10 @@ def greet_and_print(name):
|
||||
import PyXA
|
||||
safari = PyXA.Application("Safari")
|
||||
html = safari.current_document.source()
|
||||
print(f"Hello from inside the container, {name}!")
|
||||
print(f"Hello from inside the sandbox, {name}!")
|
||||
return {"greeted": name, "safari_html": html}
|
||||
|
||||
# When a @sandboxed function is called, it will execute in the container
|
||||
# When a @sandboxed function is called, it will execute in the sandbox
|
||||
result = await greet_and_print("Cua")
|
||||
# Result: {"greeted": "Cua", "safari_html": "<html>...</html>"}
|
||||
# stdout and stderr are also captured and printed / raised
|
||||
|
||||
@@ -44,7 +44,7 @@ Select the environment you want to run the code in (_click on the underlined val
|
||||
key="cloud-tab"
|
||||
lang="python"
|
||||
defaultValues={{
|
||||
"container-name": "m-linux-...",
|
||||
"sandbox-name": "m-linux-...",
|
||||
"api_key": "sk_cua-api01..."
|
||||
}}
|
||||
>
|
||||
@@ -70,7 +70,7 @@ try:
|
||||
async with Computer(
|
||||
os_type="linux",
|
||||
provider_type=VMProviderType.CLOUD,
|
||||
name="`}<EditableValue placeholder="container-name" />{`",
|
||||
name="`}<EditableValue placeholder="sandbox-name" />{`",
|
||||
api_key="`}<EditableValue placeholder="api_key" />{`",
|
||||
verbosity=logging.INFO,
|
||||
) as computer:
|
||||
@@ -159,7 +159,7 @@ main()`}
|
||||
key="lume-tab"
|
||||
lang="python"
|
||||
defaultValues={{
|
||||
"container-name": "macos-sequoia-cua:latest"
|
||||
"sandbox-name": "macos-sequoia-cua:latest"
|
||||
}}
|
||||
>
|
||||
{`import asyncio
|
||||
@@ -184,7 +184,7 @@ try:
|
||||
async with Computer(
|
||||
os_type="macos",
|
||||
provider_type=VMProviderType.LUME,
|
||||
name="`}<EditableValue placeholder="container-name" />{`",
|
||||
name="`}<EditableValue placeholder="sandbox-name" />{`",
|
||||
verbosity=logging.INFO,
|
||||
) as computer:
|
||||
|
||||
@@ -370,7 +370,7 @@ main()`}
|
||||
key="docker-tab"
|
||||
lang="python"
|
||||
defaultValues={{
|
||||
"container-name": "trycua/cua-ubuntu:latest"
|
||||
"sandbox-name": "trycua/cua-ubuntu:latest"
|
||||
}}
|
||||
>
|
||||
{`import asyncio
|
||||
@@ -395,7 +395,7 @@ try:
|
||||
async with Computer(
|
||||
os_type="linux",
|
||||
provider_type=VMProviderType.DOCKER,
|
||||
name="`}<EditableValue placeholder="container-name" />{`",
|
||||
name="`}<EditableValue placeholder="sandbox-name" />{`",
|
||||
verbosity=logging.INFO,
|
||||
) as computer:
|
||||
|
||||
|
||||
@@ -27,10 +27,10 @@ Choose how you want to run your Cua computer. This will be the environment where
|
||||
|
||||
You can run your Cua computer in the cloud (recommended for easiest setup), locally on macOS with Lume, locally on Windows with a Windows Sandbox, or in a Docker container on any platform. Choose the option that matches your system and needs.
|
||||
|
||||
<Tabs items={['Cloud Sandbox', 'Linux on Docker', 'macOS VM', 'Windows Sandbox']}>
|
||||
<Tabs items={['Cloud Sandbox', 'Linux on Docker', 'macOS Sandbox', 'Windows Sandbox']}>
|
||||
<Tab value="Cloud Sandbox">
|
||||
|
||||
Cua Cloud Sandbox provides virtual machines that run Linux (Ubuntu) or Windows.
|
||||
Cua Cloud Sandbox provides sandboxes that run Linux (Ubuntu) or Windows.
|
||||
|
||||
1. Go to [cua.ai/signin](https://cua.ai/signin)
|
||||
2. Navigate to **Dashboard > Containers > Create Instance**
|
||||
@@ -57,7 +57,7 @@ You can run your Cua computer in the cloud (recommended for easiest setup), loca
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab value="macOS VM">
|
||||
<Tab value="macOS Sandbox">
|
||||
|
||||
macOS hosts only - requires Lume CLI.
|
||||
|
||||
@@ -111,7 +111,7 @@ Connect to your Cua computer and perform basic interactions, such as taking scre
|
||||
|
||||
Then, connect to your desired computer environment:
|
||||
|
||||
<Tabs items={['Cloud Sandbox', 'Linux on Docker', 'macOS VM', 'Windows Sandbox', 'Your host desktop']}>
|
||||
<Tabs items={['Cloud Sandbox', 'Linux on Docker', 'macOS Sandbox', 'Windows Sandbox', 'Your host desktop']}>
|
||||
<Tab value="Cloud Sandbox">
|
||||
```python
|
||||
from computer import Computer
|
||||
@@ -134,10 +134,10 @@ Connect to your Cua computer and perform basic interactions, such as taking scre
|
||||
provider_type="docker",
|
||||
image="trycua/cua-xfce:latest" # or "trycua/cua-ubuntu:latest"
|
||||
)
|
||||
await computer.run() # Launch & connect to the container
|
||||
await computer.run() # Launch & connect to the sandbox
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="macOS VM">
|
||||
<Tab value="macOS Sandbox">
|
||||
```python
|
||||
from computer import Computer
|
||||
|
||||
@@ -146,7 +146,7 @@ Connect to your Cua computer and perform basic interactions, such as taking scre
|
||||
provider_type="lume",
|
||||
name="macos-sequoia-cua:latest"
|
||||
)
|
||||
await computer.run() # Launch & connect to the container
|
||||
await computer.run() # Launch & connect to the sandbox
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Windows Sandbox">
|
||||
@@ -157,7 +157,7 @@ Connect to your Cua computer and perform basic interactions, such as taking scre
|
||||
os_type="windows",
|
||||
provider_type="windows_sandbox"
|
||||
)
|
||||
await computer.run() # Launch & connect to the container
|
||||
await computer.run() # Launch & connect to the sandbox
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Your host desktop">
|
||||
@@ -199,7 +199,7 @@ Connect to your Cua computer and perform basic interactions, such as taking scre
|
||||
|
||||
Then, connect to your desired computer environment:
|
||||
|
||||
<Tabs items={['Cloud Sandbox', 'Linux on Docker', 'macOS VM', 'Windows Sandbox', 'Your host desktop']}>
|
||||
<Tabs items={['Cloud Sandbox', 'Linux on Docker', 'macOS Sandbox', 'Windows Sandbox', 'Your host desktop']}>
|
||||
<Tab value="Cloud Sandbox">
|
||||
```typescript
|
||||
import { Computer, OSType } from '@trycua/computer';
|
||||
@@ -221,10 +221,10 @@ Connect to your Cua computer and perform basic interactions, such as taking scre
|
||||
providerType: ProviderType.DOCKER,
|
||||
image: "trycua/cua-xfce:latest" // or "trycua/cua-ubuntu:latest"
|
||||
});
|
||||
await computer.run(); // Launch & connect to the container
|
||||
await computer.run(); // Launch & connect to the sandbox
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="macOS VM">
|
||||
<Tab value="macOS Sandbox">
|
||||
```typescript
|
||||
import { Computer, OSType, ProviderType } from '@trycua/computer';
|
||||
|
||||
@@ -233,7 +233,7 @@ Connect to your Cua computer and perform basic interactions, such as taking scre
|
||||
providerType: ProviderType.LUME,
|
||||
name: "macos-sequoia-cua:latest"
|
||||
});
|
||||
await computer.run(); // Launch & connect to the container
|
||||
await computer.run(); // Launch & connect to the sandbox
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Windows Sandbox">
|
||||
@@ -244,7 +244,7 @@ Connect to your Cua computer and perform basic interactions, such as taking scre
|
||||
osType: OSType.WINDOWS,
|
||||
providerType: ProviderType.WINDOWS_SANDBOX
|
||||
});
|
||||
await computer.run(); // Launch & connect to the container
|
||||
await computer.run(); // Launch & connect to the sandbox
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Your host desktop">
|
||||
@@ -359,19 +359,20 @@ Get started quickly with the CUA CLI - the easiest way to manage cloud VMs and r
|
||||
```bash
|
||||
# Install Bun (macOS/Linux)
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
|
||||
|
||||
# Install Bun (Windows)
|
||||
# powershell -c "irm bun.sh/install.ps1|iex"
|
||||
|
||||
|
||||
# Clone the repo
|
||||
git clone https://github.com/trycua/cua
|
||||
cd cua/libs/typescript/cua-cli
|
||||
|
||||
|
||||
# Install the CLI
|
||||
bun install
|
||||
bun link
|
||||
bun link cua-cli
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@@ -397,22 +398,23 @@ If you don't have a CUA account yet, sign up at [cua.ai/signin](https://cua.ai/s
|
||||
|
||||
<Step>
|
||||
|
||||
### Create Your First VM
|
||||
### Create Your First Sandbox
|
||||
|
||||
Create a cloud sandbox where your AI agents will run:
|
||||
|
||||
```bash
|
||||
# Create a Linux VM (recommended for most use cases)
|
||||
# Create a Linux sandbox (recommended for most use cases)
|
||||
cua vm create --os linux --configuration small --region north-america
|
||||
|
||||
# Or create a Windows VM
|
||||
# Or create a Windows sandbox
|
||||
cua vm create --os windows --configuration small --region north-america
|
||||
|
||||
```
|
||||
|
||||
Your VM will be created and you'll see output like:
|
||||
Your sandbox will be created and you'll see output like:
|
||||
|
||||
```
|
||||
VM created and ready: my-vm-abc123
|
||||
Sandbox created and ready: my-vm-abc123
|
||||
Password: secure-password-here
|
||||
Host: my-vm-abc123.containers.cloud.trycua.com
|
||||
```
|
||||
@@ -421,32 +423,37 @@ Host: my-vm-abc123.containers.cloud.trycua.com
|
||||
|
||||
<Step>
|
||||
|
||||
### Start Using Your VM
|
||||
### Start Using Your Sandbox
|
||||
|
||||
You can now interact with your VM in multiple ways:
|
||||
You can now interact with your sandbox in multiple ways:
|
||||
|
||||
#### Option 1: Open the AI Playground (Recommended)
|
||||
|
||||
```bash
|
||||
cua vm chat my-vm-abc123
|
||||
```
|
||||
This opens the full CUA playground in your browser where you can chat with AI agents that control your VM.
|
||||
|
||||
This opens the full CUA playground in your browser where you can chat with AI agents that control your sandbox.
|
||||
|
||||
#### Option 2: Access VNC Desktop
|
||||
|
||||
```bash
|
||||
cua vm vnc my-vm-abc123
|
||||
```
|
||||
This opens a remote desktop connection to your VM.
|
||||
|
||||
#### Option 3: List and Manage VMs
|
||||
This opens a remote desktop connection to your sandbox.
|
||||
|
||||
#### Option 3: List and Manage Sandboxes
|
||||
|
||||
```bash
|
||||
# List all your VMs
|
||||
# List all your sandboxes
|
||||
cua vm list
|
||||
|
||||
# Start/stop VMs as needed
|
||||
# Start/stop sandboxes as needed
|
||||
cua vm stop my-vm-abc123
|
||||
cua vm start my-vm-abc123
|
||||
|
||||
# Delete VMs when done
|
||||
# Delete sandboxes when done
|
||||
cua vm delete my-vm-abc123
|
||||
```
|
||||
|
||||
@@ -464,7 +471,7 @@ Once you have the playground open (`cua vm chat`), try asking the AI to:
|
||||
- "Install Python and run a simple script"
|
||||
- "Take a screenshot of the desktop"
|
||||
|
||||
The AI agent will automatically control your VM to complete these tasks!
|
||||
The AI agent will automatically control your sandbox to complete these tasks!
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@@ -5,7 +5,7 @@ description: Installation instructions for the current version of the Lume CLI.
|
||||
|
||||
## Quickstart
|
||||
|
||||
Install and run a prebuilt macOS VM in two commands:
|
||||
Install and run a prebuilt macOS sandbox in two commands:
|
||||
|
||||
```bash
|
||||
# Install Lume
|
||||
|
||||
Reference in New Issue
Block a user