### Quick Start with cmux-devbox-cli

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

A step-by-step guide to setting up your API key, starting the daemon, creating a workspace, and interacting with cloud VMs.

```bash
# 1. Set your API key
export MORPH_API_KEY="your-api-key"

# 2. Start the daemon
cmux daemon start

# 3. Create a workspace
cmux create my-app --template=node

# 4. Get your workspace ID
cmux list
# Find your workspace ID (e.g., ws_abc123)

# 5. Start the Morph Cloud VM
cmux computer start -w ws_abc123
# Output shows URLs for VS Code, VNC, and App

# 6. Open a website in the cloud browser
cmux computer open "https://example.com" -w ws_abc123

# 7. Get interactive elements (THE KEY FEATURE!)
cmux computer snapshot -i -w ws_abc123
# Output:
# @e1: link "More information..."

# 8. Interact with elements using refs
cmux computer click @e1 -w ws_abc123

# 9. Take a screenshot to verify
cmux computer screenshot --output=result.png -w ws_abc123

# 10. Save state for later
cmux computer save --name=my-checkpoint -w ws_abc123

# 11. Stop when done
cmux computer stop -w ws_abc123

# 12. Later, resume exactly where you left off
cmux computer start --from=my-checkpoint -w ws_abc123
# Browser state, processes - everything restored!
```

--------------------------------

### cmux Quick Start Commands

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/npm/cmux/README.md

A set of essential commands to get started with cmux, including login, VM creation, access, command execution, and lifecycle management.

```bash
# Login
cmux login

# Create a VM
cmux start                     # Returns ID like cmux_abc123

# Access the VM
cmux code cmux_abc123          # Open VS Code in browser
cmux ssh cmux_abc123           # SSH into VM

# Run commands
cmux exec cmux_abc123 "npm install"

# Manage lifecycle
cmux pause cmux_abc123         # Pause (preserves state)
cmux resume cmux_abc123        # Resume
cmux delete cmux_abc123        # Delete permanently

# List all VMs
cmux ls
```

--------------------------------

### cmux CLI Quick Start Guide

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

A comprehensive guide to using the cmux CLI for common development VM tasks, including authentication, creation, access, execution, synchronization, and lifecycle management.

```bash
# 1. Login
cmux auth login

# 2. Create a VM
cmux start                     # Creates VM, returns ID (e.g., cmux_abc123)
cmux start ./my-project        # Creates VM and syncs directory

# 3. Access the VM
cmux code cmux_abc123           # Open VS Code in browser
cmux ssh cmux_abc123            # SSH into VM
cmux vnc cmux_abc123            # Open VNC desktop in browser

# 4. Work with the VM
cmux exec cmux_abc123 "npm install"    # Run commands
cmux sync cmux_abc123 ./my-project     # Sync files to VM

# 5. Manage VM lifecycle
cmux pause cmux_abc123          # Pause (preserves state, saves cost)
cmux resume cmux_abc123         # Resume paused VM
cmux delete cmux_abc123         # Delete VM permanently

# 6. List VMs
cmux ls                        # List all your VMs
```

--------------------------------

### Install and Use Cloudrouter CLI

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cloudrouter/template/README.md

Installs the Cloudrouter CLI and demonstrates how to start a sandbox, open the VNC desktop, and access VSCode. Replace <team> and <id> with your specific values.

```bash
# Install CLI
cd packages/cloudrouter
make build-dev && make install-dev

# Create sandbox
cloudrouter start --name test -t <team>

# Open VNC (Chrome opens automatically)
cloudrouter vnc <id>

# Open VSCode
cloudrouter code <id>
```

--------------------------------

### Create VM and Run Dev Server

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/npm/cmux/llms.txt

Demonstrates creating a new VM, syncing a local directory, executing commands within the VM to install dependencies and start a development server, and then opening VS Code in the browser for that VM.

```bash
cmux start ./my-app
cmux exec cmux_abc123 "npm install && npm run dev"
cmux code cmux_abc123
```

--------------------------------

### Manual Testing Walkthrough with Manaflow Devbox

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

A step-by-step guide for manual testing, covering build, daemon start, workspace creation, VM operation, browser interaction, element discovery, and cleanup.

```bash
# 1. Build and prepare
cd dba # Note: the package directory is still named 'dba'
make build
export PATH="$PWD/bin:$PATH"
export MORPH_API_KEY="your-api-key"
```

```bash
# 2. Start the daemon
cmux daemon start
```

```bash
# 3. Create a test workspace
cmux create test-manual --template=node
cmux list
# Note the workspace ID (e.g., ws_9fce9a7e)
export WS_ID=ws_9fce9a7e  # Replace with your actual ID
```

```bash
# 4. Start the Morph VM
cmux computer start -w $WS_ID
```

```bash
# 5. Test browser navigation
cmux computer open "https://example.com" -w $WS_ID
cmux computer get url -w $WS_ID
cmux computer get title -w $WS_ID
```

```bash
# 6. Test element discovery
cmux computer snapshot -i -w $WS_ID
```

```bash
# 7. Test element interaction
cmux computer click @e1 -w $WS_ID
```

```bash
# 8. Test screenshot
cmux computer screenshot --output=/tmp/test.png -w $WS_ID
ls -la /tmp/test.png
```

```bash
# 9. Clean up
cmux computer stop -w $WS_ID
cmux destroy test-manual --force
cmux daemon stop

echo "All tests passed!"
```

--------------------------------

### Zsh Autocompletion Setup

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Provides methods for setting up Zsh autocompletion. This includes ensuring compinit is loaded and installing the completion script to the fpath or Homebrew's site-functions directory.

```bash
echo "autoload -U compinit; compinit" >> ~/.zshrc
```

```bash
source <(cmux completion zsh)
```

```bash
cmux completion zsh > "${fpath[1]}/_cmux"
```

```bash
cmux completion zsh > $(brew --prefix)/share/zsh/site-functions/_cmux
```

--------------------------------

### Fish Autocompletion Setup

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Provides two methods for setting up Fish shell autocompletion. The first sources the completion script directly, and the second installs it to the Fish completions directory.

```bash
cmux completion fish | source
```

```bash
cmux completion fish > ~/.config/fish/completions/cmux.fish
```

--------------------------------

### Execute Python Setup Script

Source: https://github.com/manaflow-ai/manaflow/blob/main/scripts/hello-morph/docker-buildkit-example/README.md

Runs the Python setup script using the `uv` command-line tool.

```bash
./docker-buildkit_setup.py
```

--------------------------------

### Bash Autocompletion Setup

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Provides two methods for setting up bash autocompletion for Cmux. The first sources the completion script directly, while the second installs it for system-wide use.

```bash
source <(cmux completion bash)
```

```bash
cmux completion bash > /etc/bash_completion.d/cmux
```

```bash
cmux completion bash > $(brew --prefix)/etc/bash_completion.d/cmux
```

--------------------------------

### Start Workspace Services with cmux

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Use `cmux up` to start services within a workspace. Specify individual services or start all.

```bash
cmux up -w $WS_ID           # Start all services
```

```bash
cmux up web api -w $WS_ID   # Start specific services
```

--------------------------------

### Start Development Server with Bun

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/preview-proxy/README.md

Run this command to start the development server for the project. This is typically used during active development.

```bash
bun dev
```

--------------------------------

### Save and Resume from Checkpoints (Bash)

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Use 'save' to create checkpoints after complex setup phases. If an error occurs, 'start --from' can resume execution from the last saved checkpoint, saving time and effort.

```bash
# After complex setup
cmux computer save --name=setup-complete -w $WS_ID

# If something goes wrong, resume from checkpoint
cmux computer start --from=setup-complete -w $WS_ID
```

--------------------------------

### Start and Develop in a Sandbox

Source: https://github.com/manaflow-ai/manaflow/blob/main/skills/cmux/SKILL.md

Use these commands to create a new sandbox, upload project files, open VS Code, and start a development server within the sandbox.

```bash
cmux start ./my-project        # Creates sandbox, uploads files
```

```bash
cmux code cmux_abc123          # Open VS Code
```

```bash
cmux pty cmux_abc123           # Open terminal to run commands (e.g. npm install && npm run dev)
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/worker/README.md

Use this command to install all necessary project dependencies.

```bash
pnpm install
```

--------------------------------

### Create and Access VM Workflow

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/npm/cmux/AGENTS.md

Example of creating a VM, syncing a local directory, and opening VS Code in the VM.

```bash
cmux start ./my-project    # Creates VM, syncs directory, returns ID
cmux code cmux_abc123      # Opens VS Code
```

--------------------------------

### Install Cloudrouter as a Standalone CLI

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cloudrouter/README.md

Install cloudrouter as a global command-line interface tool. After installation, you will need to authenticate.

```bash
npm install -g @manaflow-ai/cloudrouter
```

--------------------------------

### Start cmux

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux/README.md

Run the cmux command to start the local Convex backend and web server. The browser will automatically open to the web UI.

```bash
cmux
```

--------------------------------

### Install cmux-devbox-cli

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Clone the repository, build the CLI using make, and optionally add the binary to your PATH.

```bash
# Clone the repository
git clone https://github.com/anthropics/cmux-devbox-cli.git
cd cmux-devbox-cli/dba

# Build the CLI
make build

# Add to PATH (optional)
export PATH="$PWD/bin:$PATH"

# Verify installation
./bin/cmux-devbox --help
```

--------------------------------

### Start Morph Cloud VM

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Starts the Morph Cloud VM. Can start from a base snapshot, a saved snapshot, or a specific snapshot ID. Requires a workspace ID.

```bash
cmux computer start -w $WS_ID

```

```bash
cmux computer start --from=logged-in -w $WS_ID

```

```bash
cmux computer start --snapshot=snap_abc123 -w $WS_ID

```

--------------------------------

### Run Commands Remotely Workflow

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/npm/cmux/AGENTS.md

Examples of executing commands like npm install and npm run dev within a remote VM.

```bash
cmux exec cmux_abc123 "npm install"
cmux exec cmux_abc123 "npm run dev"
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/preview-proxy/README.md

Use this command to install all project dependencies using the Bun package manager.

```bash
bun install
```

--------------------------------

### Browser Automation Workflow

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/npm/cmux/AGENTS.md

Examples of navigating to a URL, taking a snapshot of elements, and clicking an element in the VM's browser.

```bash
cmux computer open cmux_abc123 "https://localhost:3000"
cmux computer snapshot cmux_abc123   # See clickable elements
cmux computer click cmux_abc123 @e1  # Click first element
```

--------------------------------

### HTTP Proxying Example

Source: https://github.com/manaflow-ai/manaflow/blob/main/crates/cmux-proxy/README.md

Demonstrates how to proxy HTTP requests using the X-Cmux-Port-Internal header. Proxies to the specified internal port.

```bash
curl -v -H 'X-Cmux-Port-Internal: 3000' http://127.0.0.1:8080/api
```

--------------------------------

### Typical Development Workflow with Cmux

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Demonstrates the daily workflow of starting, coding in, executing commands on, syncing, pausing, and resuming a Cmux VM.

```bash
# Start of day: create or resume a VM
cmux start ./my-project
# → cmux_abc123

# Work on your code
cmux code cmux_abc123        # Opens VS Code in browser

# Run commands
cmux exec cmux_abc123 "npm run dev"

# Sync changes
cmux sync cmux_abc123 ./my-project

# End of day: pause to save costs
cmux pause cmux_abc123

# Next day: resume where you left off
cmux resume cmux_abc123
```

--------------------------------

### Quick Start Cloudrouter Commands

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cloudrouter/README.md

Common cloudrouter commands for starting sandboxes, accessing them via VS Code or terminal, and executing commands within them.

```bash
# Create a sandbox from the current directory
cloudrouter start .

# Open VS Code in the browser
cloudrouter code cr_abc123

# Or get a terminal
cloudrouter pty cr_abc123

# Run a command
cloudrouter exec cr_abc123 "npm install && npm run dev"

# Open VNC desktop
cloudrouter vnc cr_abc123

# Open Jupyter Lab
cloudrouter jupyter cr_abc123
```

--------------------------------

### Install Zod OpenAPI Hono

Source: https://github.com/manaflow-ai/manaflow/blob/main/docs-ai/hono-openapi.md

Install the necessary packages for Zod OpenAPI Hono. Ensure hono and zod are also installed.

```sh
npm i hono zod @hono/zod-openapi
```

--------------------------------

### Run Development Server

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/www/README.md

Use these commands to start the Next.js development server. Open http://localhost:3000 in your browser to view the application.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Install agent-browser and Worker Daemon

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Steps to manually install the agent-browser and upload/start the worker daemon script on a VM. This is required for browser automation testing.

```bash
# 1. Install agent-browser
./bin/cmux-devbox exec <id> "npm install -g agent-browser"
```

```bash
# 2. Upload the worker daemon script
cat packages/cmux-devbox/worker/server.js | base64 | tr -d '\n' > /tmp/worker_b64.txt
B64=$(cat /tmp/worker_b64.txt)
./bin/cmux-devbox exec <id> "echo '$B64' | base64 -d > /usr/local/bin/cmux-devbox-worker && chmod +x /usr/local/bin/cmux-devbox-worker"
```

```bash
# 3. Create token directory and start worker
./bin/cmux-devbox exec <id> "mkdir -p /var/run/cmux"
./bin/cmux-devbox exec <id> "nohup node /usr/local/bin/cmux-devbox-worker > /var/log/cmux-devbox-worker.log 2>&1 &"
```

```bash
# 4. Verify worker is running
./bin/cmux-devbox exec <id> "curl -s http://localhost:39377/health"
```

```bash
# 5. Get the auth token
./bin/cmux-devbox exec <id> "cat /var/run/cmux/worker-token"
```

--------------------------------

### Install cmux-proxy with curl (latest release)

Source: https://github.com/manaflow-ai/manaflow/blob/main/crates/cmux-proxy/README.md

Installs the latest release of cmux-proxy using a curl command. The script places the binary in /usr/local/bin by default.

```bash
curl -fsSL https://raw.githubusercontent.com/lawrencecchen/cmux-proxy/main/scripts/install.sh | bash
```

--------------------------------

### Run Production Build with Bun

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/preview-proxy/README.md

Execute this command to start the application in production mode. This command is used after building the project for deployment.

```bash
bun start
```

--------------------------------

### Build Cloudrouter from Source

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cloudrouter/README.md

Build and install the cloudrouter development version from source. Navigate to the package directory and run the provided make commands.

```bash
cd packages/cloudrouter
make build-dev
make install-dev
```

--------------------------------

### Create a New Sandbox

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cloudrouter/README.md

Starts a new sandbox. Options include creating an empty sandbox, from the current directory, specifying a GPU type, or a smaller size.

```bash
# Create sandboxes
cloudrouter start                      # Empty sandbox
```

```bash
cloudrouter start .                    # From current directory
```

```bash
cloudrouter start --gpu T4             # With GPU
```

```bash
cloudrouter start --size small         # Smaller sandbox
```

--------------------------------

### Go Install for cmux Devbox CLI

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/internal/README.md

Installs the cmux devbox CLI to a user-defined bin directory using 'go install'. The PATH environment variable must be updated to include this directory for the command to be accessible.

```bash
cd packages/cmux-devbox
GOBIN="$HOME/.local/bin" go install ./cmd/cmux-devbox
export PATH="$HOME/.local/bin:$PATH"
```

--------------------------------

### Install cmux-proxy with curl (specific version)

Source: https://github.com/manaflow-ai/manaflow/blob/main/crates/cmux-proxy/README.md

Installs a specific version of cmux-proxy by setting the CMUX_PROXY_VERSION environment variable before running the install script.

```bash
CMUX_PROXY_VERSION=v0.0.1 curl -fsSL https://raw.githubusercontent.com/lawrencecchen/cmux-proxy/main/scripts/install.sh | bash
```

--------------------------------

### End of Session Workflow

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/npm/cmux/AGENTS.md

Examples for pausing a VM to save costs or deleting it permanently.

```bash
cmux pause cmux_abc123    # Pause to save costs (can resume later)
# OR
cmux delete cmux_abc123   # Delete permanently
```

--------------------------------

### Makefile Install for cmux Devbox CLI

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/internal/README.md

Installs the cmux devbox CLI by building the binary and copying it to /usr/local/bin using the Makefile. Ensure you are in the correct directory before running.

```bash
cd packages/cmux-devbox
make build
sudo make install
```

--------------------------------

### Verify cmux CLI Installation

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/internal/README.md

Confirms that the cmux CLI has been successfully installed and is available on the system's PATH.

```bash
cmux --help
cmux version
```

--------------------------------

### Start the envd Daemon

Source: https://github.com/manaflow-ai/manaflow/blob/main/crates/cmux-env/README.md

Starts the cmux-env daemon in the background. This is the first step to enable environment variable coordination.

```sh
cargo run --bin envd
```

--------------------------------

### Cloudrouter Sandbox Size Presets

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cloudrouter/README.md

Start cloudrouter sandboxes with predefined size presets for CPU, RAM, and disk. GPU options are also available.

```bash
cloudrouter start --size small       # 2 vCPU,  8 GB RAM,  20 GB disk
cloudrouter start --size medium      # 4 vCPU, 16 GB RAM,  40 GB disk
cloudrouter start --size large       # 8 vCPU, 32 GB RAM,  80 GB disk (default)
cloudrouter start --gpu T4           # GPU sandbox with NVIDIA T4
cloudrouter start --gpu B200         # GPU sandbox with NVIDIA B200
```

--------------------------------

### WebSocket Proxying Example

Source: https://github.com/manaflow-ai/manaflow/blob/main/crates/cmux-proxy/README.md

Illustrates proxying WebSocket connections using the X-Cmux-Port-Internal header. The upgrade is tunneled.

```bash
websocat -H 'X-Cmux-Port-Internal: 3001' ws://127.0.0.1:8080/ws
```

--------------------------------

### Shell Completion Setup for Cmux

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Provides commands to set up shell completion for Cmux in Bash, Zsh, Fish, and PowerShell environments.

```bash
# Bash
cmux completion bash > /etc/bash_completion.d/cmux

# Zsh
cmux completion zsh > "${fpath[1]}/_cmux"

# Fish
cmux completion fish > ~/.config/fish/completions/cmux.fish

# PowerShell
cmux completion powershell | Out-String | Invoke-Expression
```

--------------------------------

### PowerShell Autocompletion Setup

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Sets up PowerShell autocompletion by piping the completion script output to Invoke-Expression.

```bash
cmux completion powershell | Out-String | Invoke-Expression
```

--------------------------------

### Run cmux-proxy locally

Source: https://github.com/manaflow-ai/manaflow/blob/main/crates/cmux-proxy/README.md

Starts the cmux-proxy executable after building it locally. The default listen address is 0.0.0.0:8080.

```bash
./target/release/cmux-proxy --listen 0.0.0.0:8080
```

--------------------------------

### Make Python Script Executable

Source: https://github.com/manaflow-ai/manaflow/blob/main/scripts/hello-morph/docker-buildkit-example/README.md

Changes the permissions of the setup script to allow execution.

```bash
chmod +x docker-buildkit_setup.py
```

--------------------------------

### Workspace File Strategy Example

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/www/scripts/pr-review/README.md

Append review tags to changed diff lines in workspace files for automated annotation collection.

```shell
// review <float 0.0-1.0> "verbatim snippet"
```

--------------------------------

### Bracket Strategy Example

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/www/scripts/pr-review/README.md

Use this format to wrap critical spans inline with `{|` and `|}` and append review scores.

```shell
// review <float 0.0-1.0> <optional comment>
```

--------------------------------

### cmux-devbox-cli Configuration File

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

An example of a YAML configuration file for Morph Cloud settings, including API key, base snapshot, and VM resource allocation.

```yaml
# Morph Cloud settings
morph:
  api_key: "${MORPH_API_KEY}"
  base_snapshot_id: "snapshot_3namut0l"
  vm:
    vcpus: 2
    memory: 4096
    disk_size: 32768
    ttl_seconds: 3600  # Auto-stop after 1 hour idle
```

--------------------------------

### Prewarm Query Example

Source: https://github.com/manaflow-ai/manaflow/blob/main/prompts/task-runs-lazy.md

Use `prewarmQuery` to fetch query data proactively. This is useful for prefetching data on hover to reduce latency when the user actually needs the data.

```typescript
convexQueryClient.convexClient.prewarmQuery({
  query: api.github_prs.listPullRequests,
  args: { teamSlugOrId, state: "open", search: "" },
});
```

--------------------------------

### RPC Mode Example

Source: https://github.com/manaflow-ai/manaflow/blob/main/docs-ai/hono-openapi.md

Illustrates how to use Hono's RPC mode with Zod OpenAPI Hono, defining types for the Hono Client.

```APIDOC
## POST /rpc/example

### Description
An example RPC endpoint that accepts a JSON payload with an ID and returns a JSON response with the ID and a success message.

### Method
POST

### Endpoint
/rpc/example

### Parameters
None

#### Request Body
- **id** (string) - Required - The identifier for the RPC call.

### Response
#### Success Response (200)
- **id** (string) - The ID received in the request.
- **message** (string) - A success message.

### Request Example
```json
{
  "id": "rpc-call-123"
}
```

### Response Example
#### Success Response (200)
```json
{
  "id": "rpc-call-123",
  "message": "Success"
}
```
```

--------------------------------

### Start cmux on a Custom Port

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux/README.md

Use the --port option to specify a different port for the cmux web server. This is useful if the default port is already in use.

```bash
cmux --port 8080
```

--------------------------------

### Sync Files Workflow

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/npm/cmux/AGENTS.md

Demonstrates pushing the current directory to the VM and pulling build output from the VM.

```bash
cmux sync cmux_abc123 .              # Push current dir to VM
cmux sync cmux_abc123 ./dist --pull  # Pull build output from VM
```

--------------------------------

### Install cmux Globally

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux/README.md

Install the cmux package globally using npm. This command is used for setting up the tool on your system.

```bash
npm install -g cmux
```

--------------------------------

### Managing Multiple VMs with Cmux

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Shows how to create and manage multiple VMs for different development tasks and list all active VMs.

```bash
# Create multiple VMs for different tasks
cmux start ./frontend    # → cmux_frontend1
cmux start ./backend     # → cmux_backend1

# Work on them independently
cmux code cmux_frontend1
cmux code cmux_backend1

# List all
cmux ls
```

--------------------------------

### Build and Help Command

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Builds the cmux-devbox project and displays the help message.

```bash
cd packages/cmux-devbox
make build
./bin/cmux-devbox --help
```

--------------------------------

### Install Cloudrouter as a Skill

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cloudrouter/README.md

Install cloudrouter as a skill for coding agents like Claude Code or Codex. This command adds the cloudrouter skill to your agent.

```bash
npx skills add manaflow-ai/cloudrouter
```

--------------------------------

### Display cmux Help Options

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux/README.md

Execute the --help flag to view all available command-line options for cmux. This is useful for discovering advanced configurations.

```bash
cmux --help
```

--------------------------------

### Start the Manaflow Daemon

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Starts the background daemon responsible for managing workspace state and IPC. The output includes the process ID, socket path, and status.

```bash
cmux daemon start
# Output: {"pid": 12345, "socket": "/Users/.../.cmux/daemon.sock", "status": "started"}
```

--------------------------------

### Install Shell Prompt Hook

Source: https://github.com/manaflow-ai/manaflow/blob/main/crates/cmux-env/README.md

Installs the prompt hook for the specified shell to keep interactive shells synchronized with the daemon. This modifies your shell's rc file.

```sh
envctl install-hook bash
```

```sh
envctl install-hook zsh
```

```sh
envctl install-hook fish
```

--------------------------------

### Quick Test for JWT Authentication

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Follow these steps to build, login, create a VM, verify auth configuration, check worker status, and test browser commands using JWT authentication.

```bash
cd packages/cmux-devbox
make build
./bin/cmux-devbox login
```

```bash
./bin/cmux-devbox start
# Output: cmux_abc123
```

```bash
./bin/cmux-devbox exec cmux_abc123 "cat /var/run/cmux/owner-id"
# Should output your user ID (UUID format)
```

```bash
./bin/cmux-devbox exec cmux_abc123 "cat /var/run/cmux/stack-project-id"
# Should output the Stack Auth project ID
```

```bash
./bin/cmux-devbox exec cmux_abc123 "systemctl status cmux-devbox-worker"
# Should show: "Auth config loaded: owner=..., project=..."
```

```bash
./bin/cmux-devbox computer snapshot cmux_abc123
# Should return accessibility tree (e.g., "- document")
```

```bash
./bin/cmux-devbox computer open cmux_abc123 "https://example.com"
# Should output: "Navigated to: https://example.com"
```

```bash
./bin/cmux-devbox computer snapshot cmux_abc123
# Should show Example Domain content with refs like @e1, @e2
```

--------------------------------

### Verify Actions with Get Value (Bash)

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

After performing an action like filling a form field, use 'get value' to verify that the action was successful and the data was applied correctly.

```bash
cmux computer fill @e2 "test@example.com" -w $WS_ID
cmux computer get value @e2 -w $WS_ID  # Verify it was filled
```

--------------------------------

### Follow Log Files

Source: https://github.com/manaflow-ai/manaflow/blob/main/CLAUDE.md

Use `tail -f` to follow the live output of service logs. This is helpful for monitoring backend, frontend, or Convex development servers during active development.

```bash
tail -f logs/<file>
```

--------------------------------

### Create a New VM

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Creates a new virtual machine. Optionally syncs a local directory to the VM. Supports creating from a snapshot.

```bash
cmux start                       # Create VM (no sync)
cmux start .                     # Create VM, sync current directory
cmux start ./my-project          # Create VM, sync specific directory
cmux start --snapshot=snap_xxx   # Create from specific snapshot
```

--------------------------------

### cmux computer open

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Navigates the browser instance to a specified URL.

```APIDOC
## cmux computer open <id> <url>

### Description
Navigate the browser to a URL.

### Usage
```bash
cmux computer open cmux_abc123 https://google.com
```
```

--------------------------------

### Authenticate Cloudrouter CLI

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cloudrouter/README.md

Authenticate the cloudrouter CLI after installation. This is a required step before using the CLI commands.

```bash
cloudrouter login
```

--------------------------------

### Navigate to URL

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Navigates the browser within the VM to a specified URL.

```bash
cmux computer open "https://example.com" -w $WS_ID

```

```bash
cmux computer open "http://localhost:10000" -w $WS_ID

```

--------------------------------

### Sync PR Dataset

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/www/scripts/pr-review/evals/README.md

Fetches all PRs from the dataset, including diffs and metadata. Run this command to initialize the dataset.

```bash
bun run apps/www/scripts/pr-review/evals/sync-dataset.ts
```

--------------------------------

### GET /users/{id}

Source: https://github.com/manaflow-ai/manaflow/blob/main/docs-ai/hono-openapi.md

Retrieves a user by their ID. This endpoint demonstrates path parameter validation and JSON response generation.

```APIDOC
## GET /users/{id}

### Description
Retrieves the user specified by the ID in the path.

### Method
GET

### Endpoint
/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the user to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The user's ID.
- **name** (string) - The user's name.
- **age** (number) - The user's age.

### Response Example
```json
{
  "id": "123",
  "name": "John Doe",
  "age": 42
}
```
```

--------------------------------

### Inline-Comment Format Example

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/www/scripts/pr-review/README.md

Use this format for inline comments to provide review scores and verbatim snippets from changed lines.

```shell
// review <float 0.0-1.0> "verbatim snippet" <optional comment>
```

--------------------------------

### Automate Browser Testing with cmux

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/npm/cmux/llms.txt

Shows how to automate browser actions within a VM. This includes navigating to a URL, capturing a snapshot of the accessibility tree, clicking an element identified by a reference, and taking a screenshot.

```bash
cmux computer open cmux_abc123 "http://localhost:3000"
cmux computer snapshot cmux_abc123
cmux computer click cmux_abc123 @e1
cmux computer screenshot cmux_abc123 test.png
```

--------------------------------

### Build and Run cmux-devbox

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Commands to build the cmux-devbox project and run it with help information. Includes building with the race detector.

```bash
# Build
make build
```

```bash
# Run directly
./bin/cmux-devbox --help
```

```bash
# Build with race detector
make build-race
```

--------------------------------

### Check MORPH_API_KEY and Daemon Status (Bash)

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Troubleshoot VM startup issues by first checking if the MORPH_API_KEY environment variable is set. Then, verify the cmux daemon's status to ensure it's running correctly.

```bash
# Check if MORPH_API_KEY is set
echo $MORPH_API_KEY

# Verify API connection
cmux daemon status
```

--------------------------------

### Build and Run Command with LD_PRELOAD Shim

Source: https://github.com/manaflow-ai/manaflow/blob/main/crates/cmux-proxy/README.md

Build the LD_PRELOAD shim and then run an application within a workspace directory, automatically binding it to the workspace's IP. Optional environment variables can override the detected workspace or disable the shim.

```bash
make -C ldpreload
cd /root/workspace-1 && LD_PRELOAD=./ldpreload/libworkspace_net.so your-app
```

--------------------------------

### Setup Bearer Authentication Scheme

Source: https://github.com/manaflow-ai/manaflow/blob/main/docs-ai/hono-openapi.md

Register a 'Bearer' HTTP security scheme for authentication. This scheme is commonly used for token-based authorization.

```typescript
app.openAPIRegistry.registerComponent("securitySchemes", "Bearer", {
  type: "http",
  scheme: "bearer",
});
```

--------------------------------

### Get Morph Cloud VM Status

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Displays the status and accessible URLs of the Morph Cloud VM. Can output in JSON format.

```bash
cmux computer status -w $WS_ID

```

```bash
cmux computer status --json -w $WS_ID

```

--------------------------------

### Open Application in Browser

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Opens the application in the browser and displays interactive elements. Can auto-detect the app port or specify a port.

```bash
cmux computer app -w $WS_ID               # Auto-detect app port

```

```bash
cmux computer app --port=3000 -w $WS_ID   # Specific port

```

--------------------------------

### Browser Automation with Cmux Computer

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Illustrates how to automate browser interactions, including navigation, element identification, form filling, and taking screenshots.

```bash
# Navigate to a website
cmux computer open cmux_abc123 https://github.com/login

# Get interactive elements
cmux computer snapshot cmux_abc123
# Output:
# @e1: textbox "Username or email address"
# @e2: textbox "Password"
# @e3: button "Sign in"

# Fill in the login form
cmux computer fill cmux_abc123 @e1 "username"
cmux computer fill cmux_abc123 @e2 "password"

# Click the submit button
cmux computer click cmux_abc123 @e3

# Wait for page to load
cmux computer wait cmux_abc123 ".dashboard"

# Take a screenshot
cmux computer screenshot cmux_abc123 result.png
```

--------------------------------

### Using Hono Middleware

Source: https://github.com/manaflow-ai/manaflow/blob/main/docs-ai/hono-openapi.md

Demonstrates how to use standard Hono middleware with Zod OpenAPI Hono, including global usage.

```APIDOC
## Middleware Usage (Global)

### Description
Applies Hono middleware globally to specific path prefixes, such as `/doc/*`.

### Method
N/A (Applies to all methods under the path prefix)

### Endpoint
/doc/*

### Parameters
None

### Response
N/A

### Request Example
None

### Response Example
None
```

--------------------------------

### Configure Browser Settings

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cloudrouter/README.md

Commands to set viewport size, emulate devices, change color scheme, set geolocation, toggle offline mode, custom headers, and HTTP authentication. Requires a browser instance ID.

```bash
cloudrouter browser set-viewport <id> <w> <h>         # Set viewport size
```

```bash
cloudrouter browser set-device <id> <device>           # Emulate device
```

```bash
cloudrouter browser set-media <id> <dark|light>        # Set color scheme
```

```bash
cloudrouter browser set-geo <id> <lat> <lng>           # Set geolocation
```

```bash
cloudrouter browser set-offline <id> [on|off]          # Toggle offline mode
```

```bash
cloudrouter browser set-headers <id> <json>            # Set custom headers
```

```bash
cloudrouter browser set-credentials <id> <user> <pass> # Set HTTP auth
```

--------------------------------

### VM Lifecycle Commands

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Commands to manage the lifecycle of the Morph Cloud VM, including starting, stopping, checking status, and saving snapshots.

```APIDOC
## `cmux computer start`

### Description
Start the Morph Cloud VM.

### Usage
```bash
# Start from base snapshot
cmux computer start -w $WS_ID

# Start from a saved snapshot
cmux computer start --from=logged-in -w $WS_ID

# Start from specific snapshot ID
cmux computer start --snapshot=snap_abc123 -w $WS_ID
```

### Output Example
```
Starting Morph VM...
VM started successfully!
Status: running
Instance: morphvm-xyz
VS Code: https://ws-abc123.morph.so/code/
VNC:     https://ws-abc123.morph.so/vnc/
```
```

```APIDOC
## `cmux computer stop`

### Description
Stop the VM.

### Usage
```bash
cmux computer stop -w $WS_ID

# Save snapshot before stopping
cmux computer stop --save=my-state -w $WS_ID
```
```

```APIDOC
## `cmux computer status`

### Description
Show VM status and URLs.

### Usage
```bash
cmux computer status -w $WS_ID
cmux computer status --json -w $WS_ID
```
```

```APIDOC
## `cmux computer save`

### Description
Save current state as a snapshot.

### Usage
```bash
cmux computer save --name=after-login -w $WS_ID
```
```

```APIDOC
## `cmux computer vnc`

### Description
Open VNC viewer in browser.

### Usage
```bash
cmux computer vnc -w $WS_ID
```
```

--------------------------------

### Pulling Files from VM with Cmux Sync

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Demonstrates how to pull generated or built files from a VM to the local machine after executing a build command.

```bash
# After building/generating files in VM
cmux exec cmux_abc123 "npm run build"

# Pull the output
cmux sync cmux_abc123 ./dist --pull
```

--------------------------------

### Get Current Page URL or Title

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Retrieves the current URL or the title of the web page loaded in the browser. This is useful for verification or logging.

```bash
cmux computer url cmux_abc123     # Output: https://example.com
```

```bash
cmux computer title cmux_abc123   # Output: Example Domain
```

--------------------------------

### Get Interactive Elements Snapshot

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Captures a snapshot of interactive elements on the current page within the VM. This is crucial for AI agent interactions.

```bash
cmux computer snapshot -i -w $WS_ID

```

--------------------------------

### Run Go Unit Tests

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/devbox/README.md

Execute unit tests for Go packages using `go test`. Options include running all tests, specific packages, and generating coverage reports.

```bash
cd dba # Note: the package directory is still named 'dba'

# Run all unit tests
go test ./... -v
```

```bash
# Run tests for a specific package
go test ./internal/morph/... -v
go test ./internal/browser/... -v
```

```bash
# Run with coverage
go test ./... -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html
```

--------------------------------

### cmux CLI Commands

Source: https://github.com/manaflow-ai/manaflow/blob/main/skills/cmux/SKILL.md

Common cmux commands for managing cloud sandboxes. Authenticate, start, access, sync, and manage remote development environments.

```bash
cmux login                      # Authenticate (opens browser)
```

```bash
cmux start ./my-project         # Create sandbox, upload directory → returns ID
```

```bash
cmux start .                    # Or use current directory
```

```bash
cmux code <id>                  # Open VS Code
```

```bash
cmux pty <id>                   # Open terminal session
```

```bash
cmux upload <id> ./my-project   # Upload files/directories to sandbox
```

```bash
cmux download <id> ./output     # Download files from sandbox
```

```bash
cmux computer screenshot <id>   # Take browser screenshot
```

```bash
cmux stop <id>                  # Stop sandbox
```

```bash
cmux delete <id>                # Delete sandbox
```

```bash
cmux ls                         # List all sandboxes
```

--------------------------------

### Navigate Browser to URL

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cmux-devbox/README.md

Directs the browser to a specified URL. Ensure the browser instance is identified by its ID.

```bash
cmux computer open cmux_abc123 https://google.com
```

--------------------------------

### Add New PR Entry

Source: https://github.com/manaflow-ai/manaflow/blob/main/apps/www/scripts/pr-review/evals/README.md

Example structure for adding a new PR to the dataset in `dataset.ts`. Includes fields for PR details, metadata, and expected issues.

```typescript
{
  id: "my-pr-123",
  url: "https://github.com/owner/repo/pull/123/files",
  title: "Fix memory leak in cache",
  description: "Addresses memory leak when cache grows unbounded",
  tags: ["go", "performance", "bug-fix"],
  metadata: {
    owner: "owner",
    repo: "repo",
    number: 123,
    language: "go",
    filesChanged: 0, // Will be populated by sync
    additions: 0,
    deletions: 0,
  },
  expectedIssues: [
    {
      file: "cache/cache.go",
      type: "bug",
      severity: "high",
      description: "Memory leak from unbounded map growth",
      lineRange: { start: 45, end: 52 },
      snippet: "// Missing eviction logic",
    },
  ],
}
```

--------------------------------

### Manual Release Steps

Source: https://github.com/manaflow-ai/manaflow/blob/main/crates/cmux-env/README.md

Provides manual steps for releasing, including updating the version in Cargo.toml, committing changes, and running the release script.

```sh
# 1. Update version in Cargo.toml
# 2. Commit: git commit -am "chore: bump version to 0.0.4"
# 3. Run: scripts/release.sh 0.0.4
```

--------------------------------

### Browser Automation: Login to a Website

Source: https://github.com/manaflow-ai/manaflow/blob/main/skills/cmux/SKILL.md

Automate browser interactions like logging into a website by filling form fields and clicking buttons. Use 'snapshot' to identify elements.

```bash
cmux computer open cmux_abc123 "https://example.com/login"
cmux computer snapshot cmux_abc123
# Output: @e1 [input] Email, @e2 [input] Password, @e3 [button] Sign In

cmux computer fill cmux_abc123 @e1 "user@example.com"
cmux computer fill cmux_abc123 @e2 "password123"
cmux computer click cmux_abc123 @e3
cmux computer screenshot cmux_abc123 result.png
```

--------------------------------

### Cloudrouter Browser Automation: Snapshot

Source: https://github.com/manaflow-ai/manaflow/blob/main/packages/cloudrouter/README.md

Get the accessibility tree of a sandbox's browser content, optionally filtering for interactive elements. This helps in identifying elements for automation.

```bash
# Get the accessibility tree with element refs
cloudrouter browser snapshot cr_abc123
# → @e1 [link] About  @e2 [input] Search  @e3 [button] Submit

# Interactive elements only
cloudrouter browser snapshot -i cr_abc123
```