@rmbk/compeek 0.2.0 → 0.2.3

package/README.md

@@ -1,75 +1,91 @@
 # compeek — AI Eyes & Hands for Any Desktop
 
-> A computer use agent framework powered by Claude. Define goals in natural language, point at any software, watch the agent work.
+> Tell the AI what to do. Point it at any software. Watch it work.
+>
+> No APIs. No plugins. No integrations. Just screen and keyboard.
 
-**No APIs. No plugins. No integrations. Just screen and keyboard.**
+[Try the Dashboard](https://compeek.rmbk.me) | [Docker Image](https://ghcr.io/uburuntu/compeek) | [npm](https://www.npmjs.com/package/@rmbk/compeek)
 
-[Dashboard](https://compeek.rmbk.me) | [Docker Image](https://ghcr.io/uburuntu/compeek) | [npm](https://www.npmjs.com/package/compeek)
+![compeek — AI agent controlling a Linux desktop](docs/hero.png)
+
+## What can it do?
+
+**compeek** (компик + peek) turns Claude into a desktop agent that can use any application — just like a person sitting at a computer.
+
+- **See** any application through screenshots
+- **Think** through complex tasks step by step (you can watch it reason)
+- **Act** with mouse clicks, keyboard typing, and scrolling
+- **Read** documents like passports, IDs, and invoices
+- **Validate** its own work by checking what it filled in
+- **Show you everything** — a real-time dashboard shows what the AI sees and thinks
 
 ## Quick Start
 
+### Option 1: One command (recommended)
+
+```bash
+npx @rmbk/compeek start --open
+```
+
+This downloads a virtual desktop, starts it, and opens the dashboard in your browser.
+
+### Option 2: Install script
+
 ```bash
-# One-line install (Linux/macOS/WSL2)
 curl -fsSL https://compeek.rmbk.me/install.sh | bash
+```
 
-# Or via npx
-npx compeek start --open
+### Option 3: Docker
 
-# Or docker directly
+```bash
 docker run -d -p 3001:3000 -p 6081:6080 --shm-size=512m ghcr.io/uburuntu/compeek
 ```
 
-The container prints a **connection string** and a **clickable dashboard link** — no manual port entry needed. Check `docker logs compeek-1`.
+After starting, check the terminal for a **clickable link** that connects the dashboard automatically. Or run `docker logs compeek-1` to see it.
 
 Open the [dashboard](https://compeek.rmbk.me), paste your Anthropic API key in Settings, and start a workflow.
 
-## What is compeek?
+## How It Works
 
-**compeek** (компик + peek) turns Claude into an autonomous desktop agent. It sees any application through screenshots, interacts via mouse and keyboard, and validates its own work — all without requiring any integration with the target software.
+![Architecture: browser-native agent loop communicates with Docker containers via HTTP](docs/architecture.png)
 
-- **See** — screenshot any application + zoom into details
-- **Think** — extended thinking for transparent reasoning
-- **Act** — mouse clicks, keyboard input, scrolling
-- **Read** — extract data from document photos (passports, IDs, invoices)
-- **Validate** — self-check by comparing filled forms against expected data
-- **Observe** — real-time dashboard showing what the AI sees and thinks
+The AI runs **in your browser** — it looks at the virtual desktop, decides what to do, and sends mouse/keyboard commands. The virtual desktop is just a Linux computer in a container — no AI runs inside it.
 
-## Architecture
+<details>
+<summary>Technical architecture details</summary>
 
-```
-Browser (React dashboard)          Docker Container
-┌──────────────────────┐          ┌──────────────────────┐
-│  Agent Loop          │          │  Xvfb + Mutter       │
-│  ├─ Anthropic API    │  HTTP    │  ├─ Firefox          │
-│  └─ Tool dispatch ───┼─────────┼─▸ Tool Server :3000  │
-│                      │          │  │  └─ xdotool/scrot │
-│  Session Manager     │          │  ├─ noVNC :6080      │
-│  Settings (API key)  │          │  └─ VNC :5900        │
-└──────────────────────┘          └──────────────────────┘
-```
+The agent loop runs in the browser via `@anthropic-ai/sdk` with `dangerouslyAllowBrowser: true`.
+It uses `computer_20250124`, `bash_20250124`, and `text_editor_20250728` tools.
+Extended thinking is enabled with a 10240 token budget.
+
+Each container runs Ubuntu 24.04 with Xvfb (1280x720), XFWM4, x11vnc, noVNC, and Firefox (with uBlock Origin).
+The container exposes a minimal Express tool server with endpoints:
+`GET /api/health`, `GET /api/info`, `POST /api/tool`, `POST /api/bash`.
+
+Communication is HTTP-only. No WebSocket, no state in containers.
 
-The agent loop runs **in the browser** — it calls the Anthropic API directly and sends mouse/keyboard commands to Docker containers via HTTP. Each container is a stateless virtual desktop with a lightweight tool server. No backend needed.
+</details>
 
 ## Desktop Modes
 
 Set `DESKTOP_MODE` when starting a container:
 
-| Mode | What starts | Use case |
+| Mode | What you get | Best for |
 |------|-------------|----------|
-| `full` (default) | Xvfb + Mutter + Tint2 + Firefox + target app | QA testing with pre-loaded app |
-| `browser` | Xvfb + Mutter + Firefox | General web browsing agent |
-| `minimal` | Xvfb + Mutter only | Agent launches everything itself |
-| `headless` | Xvfb + tool server only | API-only, bash commands only |
+| `full` (default) | Desktop + browser + sample app | Testing forms and web apps |
+| `browser` | Desktop + browser | General web browsing |
+| `minimal` | Desktop only | Let the AI install what it needs |
+| `headless` | No visual — commands only | Automated scripts |
 
 ```bash
-npx compeek start --mode browser
+npx @rmbk/compeek start --mode browser
 # or
 docker run -d -e DESKTOP_MODE=browser -p 3001:3000 -p 6081:6080 --shm-size=512m ghcr.io/uburuntu/compeek
 ```
 
-## Connection Strings
+## Connecting to a Desktop
 
-Containers print a base64-encoded config and a dashboard link on startup:
+The container prints a **connection code** and a **clickable link** when it starts:
 
 ```
 Connection string: eyJuYW1lIj...
@@ -77,23 +93,53 @@ Dashboard link:    https://compeek.rmbk.me/#config=eyJuYW1lIj...
 ```
 
 Three ways to connect:
-1. **Click the link** — auto-adds the session
-2. **Paste the string** in the Add Session dialog
-3. **Manual entry** — type host and ports
+1. **Click the link** in your terminal — auto-adds the session
+2. **Paste the code** in the Add Session dialog
+3. **Type the address** manually (host + ports)
 
 ## CLI
 
 ```bash
-npx compeek start          # Pull image, start container, print connection info
-npx compeek start --open   # Same + open dashboard in browser
-npx compeek stop           # Stop all compeek containers
-npx compeek stop 1         # Stop compeek-1
-npx compeek status         # List running containers
-npx compeek logs           # Follow container logs
-npx compeek open           # Open dashboard with auto-connect URL
+npx @rmbk/compeek start          # Pull image, start container, print connection info
+npx @rmbk/compeek start --open   # Same + open dashboard in browser
+npx @rmbk/compeek stop           # Stop all compeek containers
+npx @rmbk/compeek stop 1         # Stop compeek-1
+npx @rmbk/compeek status         # List running containers
+npx @rmbk/compeek logs           # Follow container logs
+npx @rmbk/compeek open           # Open dashboard with auto-connect URL
+```
+
+Flags for `start`: `--name`, `--api-port`, `--vnc-port`, `--mode`, `--persist`, `--password`, `--tunnel`, `--no-pull`, `--open`.
+
+| Flag | Description |
+|------|-------------|
+| `--open` | Open dashboard in browser after starting |
+| `--mode <m>` | Desktop mode: `full`, `browser`, `minimal`, `headless` |
+| `--persist` | Mount a named Docker volume so files survive container restarts |
+| `--password <pw>` | Set a custom VNC password (auto-generated if omitted) |
+| `--tunnel` | Create public URLs via localtunnel for remote access |
+
+## Security
+
+Each container auto-generates a **VNC password** on startup. The password is included in the connection link so the dashboard connects seamlessly — you don't need to type it.
+
+You can set your own password with `--password`:
+
+```bash
+npx @rmbk/compeek start --password mysecret
+```
+
+### Remote access
+
+If you're running compeek on the same machine as your browser, everything works locally — no tunneling needed.
+
+To access a container from another machine (e.g. a remote server), use `--tunnel` to create public URLs:
+
+```bash
+npx @rmbk/compeek start --tunnel
 ```
 
-Flags for `start`: `--name`, `--api-port`, `--vnc-port`, `--mode`, `--no-pull`, `--open`.
+This uses [localtunnel](https://theboroer.github.io/localtunnel-www/) to make the container reachable over the internet. The VNC desktop is password-protected, but the tool API currently has no authentication — use a VPN or firewall for sensitive environments.
 
 ## Development
 

package/bin/compeek.mjs

@@ -5,6 +5,7 @@
 
 import { execSync, spawn } from 'node:child_process';
 import http from 'node:http';
+import crypto from 'node:crypto';
 
 const IMAGE = 'ghcr.io/uburuntu/compeek:latest';
 const CONTAINER_PREFIX = 'compeek-';
@@ -12,6 +13,22 @@ const DASHBOARD_URL = 'https://compeek.rmbk.me';
 const HEALTH_TIMEOUT = 30_000;
 const HEALTH_INTERVAL = 1_000;
 
+// ── ANSI Colors ──────────────────────────────────────────
+
+const isColorSupported = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = isColorSupported ? {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  cyan:    '\x1b[36m',
+  green:   '\x1b[32m',
+  yellow:  '\x1b[33m',
+  red:     '\x1b[31m',
+  magenta: '\x1b[35m',
+  white:   '\x1b[97m',
+  gray:    '\x1b[90m',
+} : { reset: '', bold: '', dim: '', cyan: '', green: '', yellow: '', red: '', magenta: '', white: '', gray: '' };
+
 // ── Helpers ──────────────────────────────────────────────
 
 function run(cmd, opts = {}) {
@@ -70,6 +87,19 @@ function findNextName() {
 }
 
 function waitForHealth(host, port, timeout) {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let frame = 0;
+  let spinner;
+
+  if (isColorSupported) {
+    spinner = setInterval(() => {
+      process.stdout.write(`\r  ${c.cyan}${frames[frame]}${c.reset} Waiting for container...`);
+      frame = (frame + 1) % frames.length;
+    }, 80);
+  } else {
+    console.log('  Waiting for container...');
+  }
+
   return new Promise((resolve, reject) => {
     const start = Date.now();
     const check = () => {
@@ -79,7 +109,13 @@ function waitForHealth(host, port, timeout) {
         res.on('end', () => {
           try {
             const data = JSON.parse(body);
-            if (data.status === 'ok') return resolve(data);
+            if (data.status === 'ok') {
+              if (spinner) {
+                clearInterval(spinner);
+                process.stdout.write(`\r  ${c.green}✓${c.reset} Container ready            \n`);
+              }
+              return resolve(data);
+            }
           } catch { /* retry */ }
           retry();
         });
@@ -88,16 +124,23 @@ function waitForHealth(host, port, timeout) {
       req.on('timeout', () => { req.destroy(); retry(); });
     };
     const retry = () => {
-      if (Date.now() - start > timeout) return reject(new Error('Health check timed out'));
+      if (Date.now() - start > timeout) {
+        if (spinner) {
+          clearInterval(spinner);
+          process.stdout.write(`\r  ${c.red}✗${c.reset} Health check timed out      \n`);
+        }
+        return reject(new Error('Health check timed out'));
+      }
       setTimeout(check, HEALTH_INTERVAL);
     };
     check();
   });
 }
 
-function buildConnectionString(name, apiHost, apiPort, vncHost, vncPort) {
-  const config = JSON.stringify({ name, type: 'compeek', apiHost, apiPort, vncHost, vncPort });
-  return Buffer.from(config).toString('base64');
+function buildConnectionString(name, apiHost, apiPort, vncHost, vncPort, vncPassword) {
+  const config = { name, type: 'compeek', apiHost, apiPort, vncHost, vncPort };
+  if (vncPassword) config.vncPassword = vncPassword;
+  return Buffer.from(JSON.stringify(config)).toString('base64');
 }
 
 function openUrl(url) {
@@ -115,7 +158,7 @@ function openUrl(url) {
 
 async function cmdStart(args) {
   if (!hasDocker()) {
-    console.error('Docker is not available. Install Docker first: https://docs.docker.com/get-docker/');
+    console.error(`${c.red}Docker is not available.${c.reset} Install Docker first: https://docs.docker.com/get-docker/`);
     process.exit(1);
   }
 
@@ -125,18 +168,32 @@ async function cmdStart(args) {
   const apiPort = parseInt(flags['api-port']) || defaultApi;
   const vncPort = parseInt(flags['vnc-port']) || defaultVnc;
   const mode = flags.mode || 'full';
+  const vncPassword = flags.password || crypto.randomBytes(6).toString('base64url').slice(0, 8);
   const sessionName = name.replace(CONTAINER_PREFIX, '').replace(/^(\d+)$/, 'Desktop $1');
 
+  console.log('');
+  console.log(`  ${c.bold}${c.cyan}compeek${c.reset}`);
+  console.log('');
+
   if (!flags['no-pull']) {
-    console.log(`Pulling ${IMAGE}...`);
+    console.log(`  ${c.dim}Pulling image...${c.reset}`);
     try {
       run(`docker pull ${IMAGE}`, { stdio: 'inherit' });
     } catch {
-      console.log('Pull failed, using cached image if available.');
+      console.log(`  ${c.yellow}Pull failed, using cached image.${c.reset}`);
     }
+    console.log('');
   }
 
-  console.log(`Starting ${name} (api:${apiPort}, vnc:${vncPort}, mode:${mode})...`);
+  const info = [
+    `mode:${c.white}${mode}${c.reset}`,
+    `api:${c.white}${apiPort}${c.reset}`,
+    `vnc:${c.white}${vncPort}${c.reset}`,
+  ];
+  if (flags.persist) info.push(`${c.green}persist${c.reset}`);
+  if (flags.tunnel)  info.push(`${c.yellow}tunnel${c.reset}`);
+
+  console.log(`  ${c.cyan}▸${c.reset} Starting ${c.bold}${name}${c.reset}  ${c.dim}${info.join(' · ')}${c.reset}`);
 
   // Remove existing container with same name if stopped
   run(`docker rm -f ${name}`, { allowFail: true });
@@ -149,41 +206,40 @@ async function cmdStart(args) {
     `--shm-size=512m`,
     `-e DISPLAY=:1`,
     `-e DESKTOP_MODE=${mode}`,
-    `-e COMPEEK_SESSION_NAME=${sessionName}`,
+    `-e COMPEEK_SESSION_NAME="${sessionName}"`,
+    `-e VNC_PASSWORD="${vncPassword}"`,
+    flags.tunnel ? '-e ENABLE_TUNNEL=true' : '',
+    flags.persist ? `-v ${name}-data:/home/compeek/data` : '',
     `--security-opt seccomp=unconfined`,
     IMAGE,
-  ].join(' '));
-
-  console.log('Waiting for container to be ready...');
+  ].filter(Boolean).join(' '));
 
   try {
     await waitForHealth('localhost', apiPort, HEALTH_TIMEOUT);
-    console.log('Container is ready.');
   } catch {
-    console.error('Container did not become healthy. Check logs: npx compeek logs');
+    console.error(`\n  ${c.red}Container did not start.${c.reset} Check logs: npx compeek logs`);
     process.exit(1);
   }
 
-  const connStr = buildConnectionString(sessionName, 'localhost', apiPort, 'localhost', vncPort);
+  const connStr = buildConnectionString(sessionName, 'localhost', apiPort, 'localhost', vncPort, vncPassword);
+  const dashboardLink = `${DASHBOARD_URL}/#config=${connStr}`;
 
   console.log('');
-  console.log('=========================================');
-  console.log(`  ${name}`);
-  console.log('=========================================');
-  console.log(`  Tool API : http://localhost:${apiPort}`);
+  console.log(`  ${c.dim}──── Links ─────────────────────────────────────${c.reset}`);
+  console.log('');
+  console.log(`  ${c.bold}Dashboard${c.reset}   ${c.cyan}${dashboardLink}${c.reset}`);
+  console.log(`  ${c.dim}Tool API${c.reset}    http://localhost:${apiPort}`);
   if (mode !== 'headless') {
-    console.log(`  noVNC    : http://localhost:${vncPort}`);
+    console.log(`  ${c.dim}noVNC${c.reset}       http://localhost:${vncPort}`);
+    console.log(`  ${c.dim}Password${c.reset}    ${vncPassword}`);
   }
   console.log('');
-  console.log('  Connection string:');
-  console.log(`  ${connStr}`);
+  console.log(`  ${c.dim}──── Connection string ──────────────────────────${c.reset}`);
+  console.log(`  ${c.dim}${connStr}${c.reset}`);
   console.log('');
-  console.log('  Dashboard link:');
-  console.log(`  ${DASHBOARD_URL}/#config=${connStr}`);
-  console.log('=========================================');
 
   if (flags.open) {
-    openUrl(`${DASHBOARD_URL}/#config=${connStr}`);
+    openUrl(dashboardLink);
   }
 }
 
@@ -191,33 +247,41 @@ function cmdStop(args) {
   const target = args[0];
   if (target) {
     const name = target.startsWith(CONTAINER_PREFIX) ? target : `${CONTAINER_PREFIX}${target}`;
-    console.log(`Stopping ${name}...`);
+    console.log(`  ${c.cyan}▸${c.reset} Stopping ${c.bold}${name}${c.reset}...`);
     run(`docker rm -f ${name}`, { allowFail: true, stdio: 'inherit' });
+    console.log(`  ${c.green}✓${c.reset} Stopped`);
   } else {
     const containers = listContainers();
     if (containers.length === 0) {
-      console.log('No compeek containers running.');
+      console.log(`  ${c.dim}No compeek containers running.${c.reset}`);
       return;
     }
-    for (const c of containers) {
-      console.log(`Stopping ${c.name}...`);
-      run(`docker rm -f ${c.name}`, { allowFail: true });
+    for (const ctr of containers) {
+      console.log(`  ${c.cyan}▸${c.reset} Stopping ${c.bold}${ctr.name}${c.reset}...`);
+      run(`docker rm -f ${ctr.name}`, { allowFail: true });
     }
-    console.log(`Stopped ${containers.length} container(s).`);
+    console.log(`  ${c.green}✓${c.reset} Stopped ${containers.length} container(s)`);
   }
 }
 
 function cmdStatus() {
   const containers = listContainers();
   if (containers.length === 0) {
-    console.log('No compeek containers found.');
+    console.log(`  ${c.dim}No compeek containers found.${c.reset}`);
     return;
   }
-  console.log('NAME\t\t\tSTATUS\t\t\t\tPORTS');
-  console.log('─'.repeat(80));
-  for (const c of containers) {
-    console.log(`${c.name}\t\t${c.status}\t\t${c.ports}`);
+  console.log('');
+  for (const ctr of containers) {
+    const isUp = ctr.status.startsWith('Up');
+    const dot = isUp ? `${c.green}●${c.reset}` : `${c.red}●${c.reset}`;
+    const statusText = isUp ? `${c.green}${ctr.status}${c.reset}` : `${c.dim}${ctr.status}${c.reset}`;
+    console.log(`  ${dot} ${c.bold}${ctr.name}${c.reset}  ${statusText}`);
+    if (ctr.ports) {
+      const portList = ctr.ports.replace(/0\.0\.0\.0:/g, ':').replace(/:::(\d+)/g, ':$1');
+      console.log(`    ${c.dim}${portList}${c.reset}`);
+    }
   }
+  console.log('');
 }
 
 function cmdLogs(args) {
@@ -284,7 +348,7 @@ function parseFlags(args) {
     const arg = args[i];
     if (arg.startsWith('--')) {
       const key = arg.slice(2);
-      if (key === 'open' || key === 'no-pull') {
+      if (key === 'open' || key === 'no-pull' || key === 'persist' || key === 'tunnel') {
         flags[key] = true;
       } else if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
         flags[key] = args[++i];
@@ -318,24 +382,27 @@ switch (command) {
   case '-h':
   case 'help':
     console.log(`
-compeek — AI desktop agent
-
-Usage: npx compeek [command] [options]
-
-Commands:
-  start       Start a new container (default)
-  stop [name] Stop one or all compeek containers
-  status      List running containers
-  logs [name] Follow container logs
-  open [name] Open dashboard with auto-connect URL
-
-Start options:
-  --name <n>       Container name (default: compeek-N)
-  --api-port <p>   Host port for tool API (default: auto)
-  --vnc-port <p>   Host port for noVNC (default: auto)
-  --mode <m>       Desktop mode: full|browser|minimal|headless
-  --no-pull        Skip docker pull
-  --open           Open dashboard after start
+  ${c.bold}${c.cyan}compeek${c.reset} ${c.dim}— AI eyes & hands for any desktop${c.reset}
+
+  ${c.bold}Usage${c.reset}   npx @rmbk/compeek ${c.dim}[command] [options]${c.reset}
+
+  ${c.bold}Commands${c.reset}
+    start ${c.dim}............${c.reset} Start a new virtual desktop ${c.dim}(default)${c.reset}
+    stop  ${c.dim}[name]${c.reset} ${c.dim}....${c.reset} Stop one or all containers
+    status ${c.dim}...........${c.reset} List running containers
+    logs  ${c.dim}[name]${c.reset} ${c.dim}....${c.reset} Follow container logs
+    open  ${c.dim}[name]${c.reset} ${c.dim}....${c.reset} Open dashboard in browser
+
+  ${c.bold}Options${c.reset}
+    --open ${c.dim}..........${c.reset} Open dashboard after start
+    --mode ${c.dim}<m>${c.reset} ${c.dim}......${c.reset} full ${c.dim}|${c.reset} browser ${c.dim}|${c.reset} minimal ${c.dim}|${c.reset} headless
+    --persist ${c.dim}.......${c.reset} Mount volume for persistent data
+    --password ${c.dim}<pw>${c.reset} ${c.dim}.${c.reset} Custom VNC password ${c.dim}(auto-generated if omitted)${c.reset}
+    --tunnel ${c.dim}........${c.reset} Enable localtunnel for remote access
+    --no-pull ${c.dim}.......${c.reset} Skip pulling latest Docker image
+    --name ${c.dim}<n>${c.reset} ${c.dim}......${c.reset} Custom container name
+    --api-port ${c.dim}<p>${c.reset} ${c.dim}.${c.reset} Host port for tool API
+    --vnc-port ${c.dim}<p>${c.reset} ${c.dim}.${c.reset} Host port for noVNC
 `);
     break;
   default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmbk/compeek",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "AI eyes and hands for any desktop application — a general-purpose computer use agent framework powered by Claude Opus 4.6",
   "license": "MIT",
   "author": "rmbk",