@cuylabs/computer-http

HTTP service for remote computer control. Wraps @cuylabs/computer and exposes it via REST API.

Architecture

This package provides two parts:

1. Server - Runs in a separate Node.js process with native dependencies
2. Client - Pure HTTP client, safe to use in Next.js/bundled environments

┌─────────────────────────────────────────────────────────────────┐
│  Next.js App (no native modules)                                │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ import { ComputerClient } from "@cuylabs/computer-http/client"│
│  │ const client = new ComputerClient("http://localhost:3001")  ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
                              │
                         HTTP API
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│  Computer HTTP Server (separate process)                         │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ @cuylabs/computer (native modules OK)                       ││
│  │ Docker containers                                            ││
│  │ noVNC for live viewing                                       ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

Quick Start

1. Start the server (in a separate terminal)

npx @cuylabs/computer-http --port 3001

Or programmatically:

import { createServer } from "@cuylabs/computer-http";

const server = createServer({ port: 3001 });
server.start();

2. Use the client in your app

import { ComputerClient } from "@cuylabs/computer-http/client";

const client = new ComputerClient("http://localhost:3001");

// Create a session
const session = await client.createSession({
  image: "cuylabs/desktop:latest",
});

// Display in iframe
console.log(session.novncUrl);
// → "http://localhost:6901/vnc.html?autoconnect=true&resize=scale"

// Perform actions
await client.click(session.id, { x: 100, y: 200 });
await client.type(session.id, { text: "Hello World" });
await client.key(session.id, { key: "Return" });

// Take screenshot
const screenshot = await client.screenshot(session.id);
console.log(screenshot.data); // base64

// Clean up
await client.stopSession(session.id);

API Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Health check | | GET | /sessions | List all sessions | | POST | /sessions | Create a new session | | GET | /sessions/:id | Get session info | | DELETE | /sessions/:id | Stop session | | GET | /sessions/:id/screenshot | Take screenshot | | POST | /sessions/:id/action | Execute action |

Create Session

curl -X POST http://localhost:3001/sessions \
  -H "Content-Type: application/json" \
  -d '{"image": "cuylabs/desktop:latest"}'

Response:

{
  "session": {
    "id": "abc123",
    "novncUrl": "http://localhost:6901/vnc.html?autoconnect=true&resize=scale",
    "vncPort": 7901,
    "display": { "width": 1024, "height": 768 },
    "status": "running",
    "createdAt": "2025-02-04T..."
  }
}

Execute Action

curl -X POST http://localhost:3001/sessions/abc123/action \
  -H "Content-Type: application/json" \
  -d '{"action": "click", "params": {"x": 100, "y": 200}}'

Available actions:

• click - { x, y, button? }
• doubleClick - { x, y }
• move - { x, y }
• type - { text }
• key - { key }
• scroll - { x, y, direction, amount? }
• drag - { startX, startY, endX, endY }
• exec - { command }

License

MIT