devsync-runner

DevSync Local Runner Agent — Execute, hot-sync, and preview DevSync cloud workspaces directly on your local computer with zero configuration.

⚡ Overview

DevSync is a real-time collaborative development platform. devsync-runner is the companion CLI agent that connects your local machine (Windows, macOS, or Linux) directly to the DevSync web editor.

With devsync-runner, you don't need cloud sandboxes with restricted CPU or memory. Your workspace code streams live to your machine, installs dependencies with local caching, and boots your dev server locally while streaming the terminal output and preview back into DevSync!

✨ Features

• 🚀 Zero-Setup Execution: Launch immediately using npx devsync-runner. No git clones or manual configuration required.
• 🔗 Persistent Account Pairing: Connect once via [email protected]. Switch between projects in your browser and your local agent will seamlessly follow without needing a terminal restart.
• 🔄 Real-Time Hot-Sync: Any code change typed in the DevSync web editor (Monaco) updates the file on your local disk in milliseconds.
• ⚡ Instant Cold-Starts: Smart caching preserves node_modules across sessions. If package.json hasn't changed, npm install is skipped for 1-second restarts.
• 🌐 Automatic Project Detection:
  • Node.js / React / Vite / Next.js: Auto-detects dev or start scripts and captures dev server ports.
  • Python (Flask, FastAPI, Django, Scripts): Detects entrypoints and runs unbuffered with live output.
  • Static Web (HTML/CSS/JS): Spawns an internal HTTP server with Server-Sent Events (SSE) live-reload.
• 🛡️ Flexible Storage Modes:
  • Persistent (Default): Keeps project files organized in ~/devsync-workspaces/<workspaceId> for fast caching and offline inspection.
  • Ephemeral (--ephemeral): Clean, sandboxed run that automatically purges all files from your machine upon exit.
• 📡 Bi-Directional Terminal Stream: Dev server stdout, stderr, and readiness signals are piped live back to the DevSync web UI.

📦 Quick Start

Option 1: NPX (Recommended — No Installation Required)

Pair your computer to your DevSync account:

npx devsync-runner [email protected]

Tip: You only need to run this once! The runner saves your email in ~/.devsync/config.json. After pairing, you can launch runs directly from the DevSync web UI.

Or run a specific workspace directly by its ID:

npx devsync-runner <workspaceId>

Option 2: Global Installation

If you prefer having the CLI globally available:

# Install globally via npm
npm install -g devsync-runner

# Or with yarn
yarn global add devsync-runner

# Or with pnpm
pnpm add -g devsync-runner

Run with either devsync-runner or the shorthand devsync:

devsync [email protected]

🖥️ Command-Line Usage & Flags

devsync-runner [workspaceId] [options]

Options

| Flag | Shorthand | Description | Default | | :--- | :--- | :--- | :--- | | --user=<email> | -u | Link runner to your DevSync account email | Stored in config | | --workspace=<id> | -w, -i | Specific workspace ID to execute | Positional arg | | --server=<url> | -s | DevSync backend server URL | http://localhost:5000 | | --dir=<path> | -d | Custom local workspace storage folder | ~/devsync-workspaces | | --ephemeral | -e | Wipe files from disk when stopped | false |

🔧 Environment Variables

You can also configure devsync-runner using environment variables or a .env file:

# DevSync backend URL
SERVER_URL=https://api.devsync.example.com

# Linked user account email
[email protected]

# Target workspace ID (optional)
WORKSPACE_ID=my-project-id

# Custom storage directory
DEVSYNC_DIR=C:\projects\devsync

# Ephemeral mode (true/false)
DEVSYNC_EPHEMERAL=false

# Override default dev server port (default: 5174)
DEV_PORT=5174

🏗️ How It Works

┌─────────────────────────────────┐
│        DevSync Web Editor       │
│  (Monaco Editor + Live Preview) │
└───────────────┬─────────────────┘
                │ WebSockets (Socket.IO)
                ▼
┌─────────────────────────────────┐
│         DevSync Server          │
│   (Real-time Relay & Storage)   │
└───────────────┬─────────────────┘
                │ Secure Socket Stream
                ▼
┌─────────────────────────────────┐
│     devsync-runner (Local)      │
│  ~/devsync-workspaces/<id>      │
├────────────────┬────────────────┤
│ 1. Disk Sync   │ 2. Dev Process │
│ (Diff & Write) │ (Vite / Node)  │
└────────────────┴────────────────┘

1. Agent Registration: devsync-runner establishes a persistent WebSocket connection to the DevSync server, announcing your computer's readiness.
2. Differential File Sync: When you click Run in DevSync, project files are streamed to your local disk. Only modified files are rewritten.
3. Smart Dependency Resolution: If node_modules already exists and package.json hasn't changed, dependencies are reused instantly.
4. Dev Server Orchestration: The runner launches your project's dev server (npm run dev, python app.py, or built-in static server) and detects the listening port.
5. Live Hot-Sync & Reload: Code edits in DevSync are instantly written to your local file tree. For static websites, the runner automatically reloads the browser via Server-Sent Events.

📁 Local File Location

By default, files are synced to your user home directory:

• Windows: C:\Users\<Username>\devsync-workspaces\<workspaceId>\
• macOS / Linux: ~/.devsync-workspaces/<workspaceId>/

Configuration settings (such as saved email and default backend) are stored in:

• ~/.devsync/config.json

🔍 Troubleshooting

npx devsync-runner [email protected] --server=https://your-backend.com

DEV_PORT=3000 npx devsync-runner

📄 License

ISC © DevSync Team