API Reference layout refactor, start implementing specific guides

This commit is contained in:
Morgan Dean
2025-07-04 13:46:04 -07:00
parent c93ff469a8
commit a11d86fb16
37 changed files with 444 additions and 87 deletions
+14
View File
@@ -0,0 +1,14 @@
---
title: v0.2.0
description: Api reference for version 0.2.0 of the agent library
---
The Agent API reference documentation is currently under development.
## Overview
The Agent library provides programmatic interfaces for AI agent interactions.
## API Documentation
Coming soon.
@@ -1,5 +1,6 @@
---
title: Agent
description: Current api reference for the agent library
---
The Agent API reference documentation is currently under development.
+5
View File
@@ -0,0 +1,5 @@
---
title: API Reference
description: This is where the api referece goes
icon: CodeXml
---
+6
View File
@@ -0,0 +1,6 @@
{
"title": "API Reference",
"description": "API Reference",
"root": true,
"pages": ["index", "---", "..."]
}
@@ -0,0 +1,76 @@
---
title: Compatibility
description: Compatibility information for running c/ua services.
---
# Host OS Compatibility
_This section shows compatibility based on your **host operating system** (the OS you're running C/ua on)._
## macOS Host
| Installation Method | Requirements | Lume | Cloud | Notes |
| ------------------------ | ------------------------- | ------- | ------- | --------------------------- |
| **playground-docker.sh** | Docker Desktop | ✅ Full | ✅ Full | Recommended for quick setup |
| **Dev Container** | VS Code/WindSurf + Docker | ✅ Full | ✅ Full | Best for development |
| **PyPI packages** | Python 3.12+ | ✅ Full | ✅ Full | Most flexible |
### macOS Host Requirements:
- macOS 15+ (Sequoia) for local VM support
- Apple Silicon (M1/M2/M3/M4) recommended for best performance
- Docker Desktop for containerized installations
## Ubuntu/Linux Host
| Installation Method | Requirements | Lume | Cloud | Notes |
| ------------------------ | ------------------------- | ------- | ------- | --------------------------- |
| **playground-docker.sh** | Docker Engine | ✅ Full | ✅ Full | Recommended for quick setup |
| **Dev Container** | VS Code/WindSurf + Docker | ✅ Full | ✅ Full | Best for development |
| **PyPI packages** | Python 3.12+ | ✅ Full | ✅ Full | Most flexible |
### Ubuntu/Linux Host Requirements:
- Ubuntu 20.04+ or equivalent Linux distribution
- Docker Engine or Docker Desktop
- Python 3.12+ for PyPI installation
## Windows Host
| Installation Method | Requirements | Lume | Winsandbox | Cloud | Notes |
| ------------------------ | -------------------------------- | ---------------- | ---------------- | ------- | ------------- |
| **playground-docker.sh** | Docker Desktop + WSL2 | ❌ Not supported | ❌ Not supported | ✅ Full | Requires WSL2 |
| **Dev Container** | VS Code/WindSurf + Docker + WSL2 | ❌ Not supported | ❌ Not supported | ✅ Full | Requires WSL2 |
| **PyPI packages** | Python 3.12+ | ❌ Not supported | ✅ Full | ✅ Full | |
### Windows Host Requirements:
- Windows 10/11 with WSL2 enabled for shell script execution
- Docker Desktop with WSL2 backend
- Windows Sandbox feature enabled (for Winsandbox support)
- Python 3.12+ installed in WSL2 or Windows
- **Note**: Lume CLI is not available on Windows - use Cloud or Winsandbox providers
---
# VM Emulation Support
_This section shows which **virtual machine operating systems** each provider can emulate._
| Provider | macOS VM | Ubuntu/Linux VM | Windows VM | Notes |
| -------------- | ---------------- | ------------------ | ------------------ | ------------------------------------------------------ |
| **Lume** | ✅ Full support | ⚠️ Limited support | ⚠️ Limited support | macOS: native; Ubuntu/Linux/Windows: need custom image |
| **Cloud** | 🚧 Coming soon | ✅ Full support | 🚧 Coming soon | Currently Ubuntu only, macOS/Windows in development |
| **Winsandbox** | ❌ Not supported | ❌ Not supported | ✅ Windows only | Windows 10/11 environments only |
# Model Provider Compatibility
_This section shows which **AI model providers** are supported on each host operating system._
| Provider | macOS Host | Ubuntu/Linux Host | Windows Host | Notes |
| --------------------- | --------------- | ----------------- | ---------------- | ----------------------------------------------- |
| **Anthropic** | ✅ Full support | ✅ Full support | ✅ Full support | Cloud-based API |
| **OpenAI** | ✅ Full support | ✅ Full support | ✅ Full support | Cloud-based API |
| **Ollama** | ✅ Full support | ✅ Full support | ✅ Full support | Local model serving |
| **OpenAI Compatible** | ✅ Full support | ✅ Full support | ✅ Full support | Any OpenAI-compatible API endpoint |
| **MLX VLM** | ✅ macOS only | ❌ Not supported | ❌ Not supported | Apple Silicon required. PyPI installation only. |
@@ -0,0 +1,76 @@
---
title: Comuter-Use Agent Quickstart
description: Launch a computer-use agent UI interface with Docker, Dev Container, or Python.
---
## Docker
_Best for a simple, fully managed installation for testing and experimentation._
**macOS/Linux/Windows (via WSL):**
Run the following command to setup the Docker containers and launch the Computer-Use Agent UI:
```bash
# Requires Docker
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/scripts/playground-docker.sh)"
```
## Dev Container
_Best for contributors and active development._
This repository includes a [Dev Container](./.devcontainer/README.md) configuration that simplifies setup to a few steps:
1. **Install the Dev Containers extension ([VSCode](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) or [WindSurf](https://docs.windsurf.com/windsurf/advanced#dev-containers-beta))**
2. **Open the repository in the Dev Container:**
- Press `Ctrl+Shift+P` (or `⌘+Shift+P` on macOS)
- **If you have _not_ cloned the repo:**
- Select `Dev Containers: Clone Repository in Container Volume...` and paste the repository URL:
```
https://github.com/trycua/cua.git
```
- **If you have already cloned the repo:**
- Select `Dev Containers: Open Folder in Container...` and choose your local folder.
> **Note**: On WindSurf, the post install hook might not run automatically. If it doesn't, run:
>
> ```
> /bin/bash .devcontainer/post-install.sh
> ```
3. **Open the VS Code workspace:** Once the post-install.sh is done running, open the python workspace located at `.vscode/py.code-workspace`.
4. **Run the Agent UI example:** Click <img src="https://github.com/user-attachments/assets/7a61ef34-4b22-4dab-9864-f86bf83e290b" className='inline-block mt-1 mb-1 rounded-md mx-1'/>
to start the Gradio UI. If prompted to install **debugpy (Python Debugger)** for remote debugging, select 'Yes' to proceed.
5. **Access the Gradio UI:** The Gradio UI will now be accessible http://localhost:7860.
## PyPI
_Direct Python package installation_
```bash
# conda create -yn cua python==3.12
pip install -U "cua-computer[all]" "cua-agent[all]"
python -m agent.ui # Start the agent UI
```
Or check out the [Usage Guide](#-usage-guide) to learn how to use our Python SDK in your own code.
---
# Supported [Agent Loops](../libraries/agent#agent-loops)
- [UITARS-1.5](https://github.com/bytedance/UI-TARS) - Run locally on Apple Silicon with MLX, or use cloud providers
- [OpenAI CUA](https://openai.com/index/computer-using-agent/) - Use OpenAI's Computer-Use Preview model
- [Anthropic CUA](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/computer-use-tool) - Use Anthropic's Computer-Use capabilities
- [OmniParser-v2.0](https://github.com/microsoft/OmniParser) - Control UI with [Set-of-Marks prompting](https://som-gpt4v.github.io/) using any vision model
---
# Compatibility
For detailed compatibility information including host OS support, VM emulation capabilities, and model provider compatibility, see the [Compatibility Guide](./compatibility).
+5
View File
@@ -0,0 +1,5 @@
{
"title": "C/ua",
"description": "C/ua",
"icon": "House"
}
@@ -0,0 +1,83 @@
---
title: C/ua Usage Guide
descrption: Follow these steps to use C/ua in your own Python code.
---
import { Step, Steps } from 'fumadocs-ui/components/steps';
<Steps>
<Step>
### Install the Lume CLI
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
```
Lume CLI manages high-performance macOS/Linux VMs with near-native speed on Apple Silicon.
</Step>
<Step>
### Pull the macOS CUA Image
```bash
lume pull macos-sequoia-cua:latest
```
The macOS CUA image contains the default macOS apps and the Computer Server for easy automation.
</Step>
<Step>
### Install the Python SDK
```bash
pip install "cua-computer[all]" "cua-agent[all]"
```
</Step>
<Step>
### Integrate with Your Own Projects
```python
from computer import Computer
from agent import ComputerAgent, LLM
async def main():
# Start a local macOS VM
computer = Computer(os_type="macos")
await computer.run()
# Or with C/ua Cloud Container
computer = Computer(
os_type="linux",
api_key="your_cua_api_key_here",
name="your_container_name_here"
)
# Example: Direct control of a macOS VM with Computer
computer.interface.delay = 0.1 # Wait 0.1 seconds between kb/m actions
await computer.interface.left_click(100, 200)
await computer.interface.type_text("Hello, world!")
screenshot_bytes = await computer.interface.screenshot()
# Example: Create and run an agent locally using mlx-community/UI-TARS-1.5-7B-6bit
agent = ComputerAgent(
computer=computer,
loop="uitars",
model=LLM(provider="mlxvlm", name="mlx-community/UI-TARS-1.5-7B-6bit")
)
async for result in agent.run("Find the trycua/cua repository on GitHub and follow the quick start guide"):
print(result)
if __name__ == "__main__":
asyncio.run(main())
```
For ready-to-use examples, check out our [Notebooks](https://github.com/trycua/cua/tree/main/notebooks) collection.
</Step>
</Steps>
@@ -0,0 +1,16 @@
{
"title": "Libraries",
"description": "Libraries",
"icon": "Library",
"pages": [
"agent",
"computer",
"computer-server",
"cloud",
"core",
"lume",
"lumier",
"mcp-server",
"som"
]
}
+12
View File
@@ -0,0 +1,12 @@
{
"title": "Home",
"description": "Documentation Home",
"root": true,
"defaultOpen": true,
"pages": [
"---[House]c/ua---",
"...cua",
"---[Library]Libraries---",
"...libraries"
]
}
-14
View File
@@ -1,14 +0,0 @@
{
"title": "API Reference",
"description": "API Reference",
"pages": [
"agent",
"computer",
"computer-server",
"core",
"lume",
"lumier",
"mcp-server",
"som"
]
}
@@ -1,5 +0,0 @@
---
title: Getting Started
description: Getting started with c/ua
icon: Home
---
-9
View File
@@ -1,9 +0,0 @@
{
"title": "C/ua",
"description": "C/ua",
"icon": "House",
"pages": [
"getting-started",
"faq"
]
}
-16
View File
@@ -1,16 +0,0 @@
{
"title": "Libraries",
"description": "Libraries",
"icon": "Library",
"pages": [
"agent",
"computer",
"computer-server",
"cloud",
"core",
"lume",
"lumier",
"mcp-server",
"som"
]
}
-14
View File
@@ -1,14 +0,0 @@
{
"title": "v1",
"description": "Documentation v1",
"root": true,
"defaultOpen": true,
"pages": [
"---[House]c/ua---",
"...cua",
"---[Library]Libraries---",
"...libraries",
"---[CodeXml]API Reference---",
"...api"
]
}
+4
View File
@@ -17,6 +17,10 @@ const config = {
protocol: 'https',
hostname: 'starchart.cc',
},
{
protocol: 'https',
hostname: 'github.com',
},
],
},
};
+93 -8
View File
@@ -1,26 +1,111 @@
import { source } from '@/lib/source';
import { getApiVersions, source } from '@/lib/source';
import { getMDXComponents } from '@/mdx-components';
import { buttonVariants } from 'fumadocs-ui/components/ui/button';
import {
Popover,
PopoverContent,
PopoverTrigger,
} from 'fumadocs-ui/components/ui/popover';
import { createRelativeLink } from 'fumadocs-ui/mdx';
import {
DocsPage,
DocsBody,
DocsDescription,
DocsPage,
DocsTitle,
} from 'fumadocs-ui/page';
import { notFound, redirect } from 'next/navigation';
import { createRelativeLink } from 'fumadocs-ui/mdx';
import { getMDXComponents } from '@/mdx-components';
import { cn } from 'fumadocs-ui/utils/cn';
import { ChevronDown } from 'lucide-react';
import Link from 'next/link';
import { notFound } from 'next/navigation';
export default async function Page(props: {
params: Promise<{ slug?: string[] }>;
}) {
const params = await props.params;
const page = source.getPage(params.slug);
if (!page) redirect('/v1');
const slug = params.slug || [];
const page = source.getPage(slug);
if (!page) notFound();
// Detect if this is an API reference page: /docs/api/[section] or /docs/api/[section]/[version]
let apiSection: string | null = null;
let apiVersionSlug: string[] = [];
if (slug[0] === 'api' && slug.length >= 2) {
apiSection = slug[1];
if (slug.length > 2) {
apiVersionSlug = slug.slice(2);
}
}
let versionItems: { label: string; slug: string[] }[] = [];
if (apiSection) {
versionItems = await getApiVersions(apiSection);
}
const MDXContent = page.data.body;
return (
<DocsPage toc={page.data.toc} full={page.data.full}>
<DocsTitle>{page.data.title}</DocsTitle>
<div className="flex flex-row w-full">
<DocsTitle>{page.data.title}</DocsTitle>
<div className="ml-auto">
{apiSection && versionItems.length > 1 && (
<Popover>
<PopoverTrigger
className={cn(
buttonVariants({
color: 'secondary',
size: 'sm',
className: 'gap-2',
})
)}>
{(() => {
// Find the current version label
let currentLabel = 'Current';
if (apiVersionSlug.length > 0) {
const found = versionItems.find(
(item) =>
item.label !== 'Current' &&
apiVersionSlug[0] === item.label
);
if (found) currentLabel = found.label;
}
return (
<>
API Version: {currentLabel}
<ChevronDown className="size-3.5 text-fd-muted-foreground" />
</>
);
})()}
</PopoverTrigger>
<PopoverContent className="flex flex-col overflow-auto">
{versionItems.map((item) => {
// Build the href for each version
const href =
item.label === 'Current'
? `/api/${apiSection}`
: `/api/${apiSection}/${item.label}`;
// Highlight current version
const isCurrent =
(item.label === 'Current' && apiVersionSlug.length === 0) ||
(item.label !== 'Current' &&
apiVersionSlug[0] === item.label);
return (
<Link
key={item.label}
href={href}
className={cn(
'px-3 py-1 rounded hover:bg-fd-muted',
isCurrent && 'font-bold bg-fd-muted'
)}>
API version: {item.label}
</Link>
);
})}
</PopoverContent>
</Popover>
)}
</div>
</div>
<DocsDescription>{page.data.description}</DocsDescription>
<DocsBody>
<MDXContent
+11 -16
View File
@@ -1,8 +1,8 @@
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import type { ReactNode } from 'react';
import { baseOptions } from '@/app/layout.config';
import { source } from '@/lib/source';
import { CodeXml } from 'lucide-react';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { CodeXml, Home } from 'lucide-react';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
@@ -11,19 +11,14 @@ export default function Layout({ children }: { children: ReactNode }) {
sidebar={{
tabs: [
{
url: '/v1',
title: 'API v1',
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>
),
url: '/home',
title: 'Home',
icon: <Home className="ml-1" />,
},
{
url: '/api',
title: 'API Reference',
icon: <CodeXml className="ml-1" />,
},
],
}}
+42 -5
View File
@@ -1,12 +1,49 @@
import { docs } from "@/.source";
import { loader } from "fumadocs-core/source";
import { icons } from "lucide-react";
import { createElement } from "react";
import { docs } from '@/.source';
import { loader } from 'fumadocs-core/source';
import { icons } from 'lucide-react';
import { createElement } from 'react';
import fs from 'node:fs/promises';
import path from 'node:path';
/**
* Returns available API doc versions for a given section (e.g., 'agent').
* Each version is an object: { label, slug }
* - 'Current' (index.mdx) → slug: []
* - '[version].mdx' → slug: [version]
*/
export async function getApiVersions(
section: string
): Promise<{ label: string; slug: string[] }[]> {
const dir = path.join(process.cwd(), 'content/docs/api', section);
let files: string[] = [];
try {
files = (await fs.readdir(dir)).filter((f) => f.endsWith('.mdx'));
} catch (_e) {
return [];
}
const versions = files.map((file) => {
if (file === 'index.mdx') {
return { label: 'Current', slug: [] };
}
const version = file.replace(/\.mdx$/, '');
return { label: version, slug: [version] };
});
// Always put 'Current' first, then others sorted descending (semver-ish)
return [
...versions.filter((v) => v.label === 'Current'),
...versions
.filter((v) => v.label !== 'Current')
.sort((a, b) =>
b.label.localeCompare(a.label, undefined, { numeric: true })
),
];
}
// See https://fumadocs.vercel.app/docs/headless/source-api for more info
export const source = loader({
// it assigns a URL to your pages
baseUrl: "/",
baseUrl: '/',
source: docs.toFumadocsSource(),
icon(icon) {
if (!icon) return;