Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

5.2 KB
Raw Blame

docs

Public documentation content and assets live in this repository. The production renderer, redirects, analytics, and site configuration live in trycua/cloud. This app is a local MDX preview for contributors to the public repository.

Install the docs dependencies and run the local preview from this directory:

pnpm install --frozen-lockfile
pnpm dev

Open http://localhost:8090 with your browser to see the result. The docs app has its own lockfile; installing dependencies at the repository root is not enough.

Validate a change

Curated MDX pages use the content checks and production build:

pnpm docs:check-hygiene
pnpm docs:check-links
pnpm docs:check-blocks
pnpm build

Every fenced code block declares what it is, and pnpm docs:check-blocks enforces it. Put exactly one disposition in the fence's meta string:

Disposition Meaning
test="<lane>" id="<id>" CI runs the block in that lane; id is stable and unique per page
skip="<reason>" not run; the reason comes from docs/code-block-policy.json
output program output, a listing or other text that is not code

Lanes and skip reasons live in docs/code-block-policy.json. Generated pages are exempt because their generator's check owns them. The lanes:

Lane Runs When
cli-shape every cua, cua-driver and lume command parses against the CLI's generated definition every PR (docs:check-blocks)
config JSON, YAML and TOML parse, and match schema="<name>" every PR (docs:check-blocks, needs uv)
docs Python and TypeScript blocks, hermetically; prelude="fakefleet" runs cloud code against a fake Fleet PR (tests/e2e/cua-sdk)
container blocks that start local sandboxes (Docker, gVisor) PR (tests/e2e/cua-sdk)
fleet whole scripts against live Fleet nightly
windows, lume shell blocks on a disposable Windows or macOS machine nightly
terraform terraform init and validate PR
swift, kotlin the block compiles against libs/cua/swift or libs/cua/kotlin (statements wrapped in a function; nothing runs) PR (docs-compile-lanes.yml)
rust the block type-checks (cargo check) against libs/cua/crates/cua-sdk; a block without fn main is wrapped in an async function returning Result PR (docs-compile-lanes.yml)
excerpt the block is byte-identical to source="<path>#<region>" in a sample CI builds every PR (docs:check-blocks)

Run the Python and container lanes with python3 tests/e2e/cua-sdk/run.py --lanes docs --langs py --strict (add container with Docker running). session="..." scopes blocks that build on each other; prelude="..." adds hidden setup (see tests/e2e/cua-sdk/docs/preludes/README.md). Blocks that predate the rule are listed in docs/code-block-baseline.json, which may only shrink: after deciding a baselined block, run python3 ../tests/e2e/cua-sdk/docs/extract.py --update-baseline. A new or edited block must be decided before it merges.

For generated reference changes, also run the owning component check:

pnpm docs:check:cua-driver
pnpm docs:check:lume
pnpm docs:check:cua-cli

pnpm docs:generate:cua-driver regenerates the shared CLI reference and only the host's native reference: mcp-tools-linux.mdx on Linux, mcp-tools.mdx on macOS, and mcp-tools-windows.mdx on Windows. The existing macOS URL and anchors are preserved. The corresponding check compares those same two files without writing them. Shared guidance stays in the hand-maintained mcp-tool-notes.mdx. Use the native reference for the machine running the driver, not the agent's machine. The generator omits CUA_DRIVER_POLICY_FILE and CUA_DRIVER_MANAGED_POLICY_FILE only from its finite dump-docs child process so the reference includes every registered native tool. It does not change policy files, the parent environment, normal tool discovery, or action authorization.

Native generation requires Rust and the component's native build dependencies. Lume generation and checking require macOS. pnpm docs:check remains the explicit full Cua Driver and Lume audit, not a portable curated-page check. On Windows, install the Rust MSVC toolchain and Visual Studio C++ Build Tools with a Windows SDK and MSVC Spectre-mitigated libraries. These commands work from PowerShell or Command Prompt; Git Bash is not required.

Docs conventions

Public docs live in content/docs/ and follow the Diátaxis modes:

  • tutorials/ teach a guided first success.
  • how-to-guides/ give steps for a specific goal.
  • concepts/ contains Diátaxis explanations of concepts, constraints, and tradeoffs.
  • reference/ is dry lookup: commands, APIs, contracts, limits.

Place content by what the reader is trying to do, not by topic. Do not mix modes in one page; move reference tables to reference pages and link to them from how-to guides or explanations.

Learn More

To learn more about Next.js and Fumadocs, take a look at the following resources: