nstantpage-agent 0.4.2 → 0.5.0

package/dist/cli.d.ts

@@ -3,12 +3,13 @@
  * nstantpage-agent CLI
  *
  * Usage:
- *   nstantpage login              — Authenticate with nstantpage.com
- *   nstantpage start [dir]        — Start agent for a project directory
- *   nstantpage stop               — Stop running agent
- *   nstantpage status             — Show agent status
- *   nstantpage service            — Install as background service (auto-start on boot)
- *   nstantpage service --uninstall — Remove background service
+ *   nstantpage login                — Authenticate with nstantpage.com
+ *   nstantpage start [dir]          — Start agent for a project directory
+ *   nstantpage stop                 — Stop running agent
+ *   nstantpage status               — Show agent status
+ *   nstantpage service install      — Install as background service (auto-start on boot)
+ *   nstantpage service uninstall    — Remove background service
+ *   nstantpage service status       — Check if service is running
  *
  * The agent replaces Docker containers — your project runs natively on your
  * machine with full performance, and the cloud editor connects through a tunnel.

package/dist/cli.js

@@ -3,12 +3,13 @@
  * nstantpage-agent CLI
  *
  * Usage:
- *   nstantpage login              — Authenticate with nstantpage.com
- *   nstantpage start [dir]        — Start agent for a project directory
- *   nstantpage stop               — Stop running agent
- *   nstantpage status             — Show agent status
- *   nstantpage service            — Install as background service (auto-start on boot)
- *   nstantpage service --uninstall — Remove background service
+ *   nstantpage login                — Authenticate with nstantpage.com
+ *   nstantpage start [dir]          — Start agent for a project directory
+ *   nstantpage stop                 — Stop running agent
+ *   nstantpage status               — Show agent status
+ *   nstantpage service install      — Install as background service (auto-start on boot)
+ *   nstantpage service uninstall    — Remove background service
+ *   nstantpage service status       — Check if service is running
  *
  * The agent replaces Docker containers — your project runs natively on your
  * machine with full performance, and the cloud editor connects through a tunnel.
@@ -18,15 +19,17 @@ import chalk from 'chalk';
 import { loginCommand } from './commands/login.js';
 import { startCommand } from './commands/start.js';
 import { statusCommand } from './commands/status.js';
-import { serviceCommand } from './commands/service.js';
+import { serviceInstallCommand, serviceUninstallCommand, serviceStatusCommand } from './commands/service.js';
 const program = new Command();
 program
     .name('nstantpage')
     .description('Local development agent for nstantpage.com — run projects on your machine, preview in the cloud')
-    .version('0.3.0');
+    .version('0.5.0');
 program
     .command('login')
     .description('Authenticate with nstantpage.com')
+    .option('--gateway <url>', 'Gateway URL (auto-detects local vs production)')
+    .option('--force', 'Re-authenticate even if already logged in')
     .action(loginCommand);
 program
     .command('start')
@@ -69,12 +72,21 @@ program
     .command('status')
     .description('Show agent status')
     .action(statusCommand);
-program
+const service = program
     .command('service')
-    .description('Install/uninstall agent as a background service (starts on boot)')
-    .option('--project-id <id>', 'Project ID to serve')
+    .description('Manage the background service (keeps your machine connected to nstantpage.com)');
+service
+    .command('install')
+    .description('Install & start the agent as a background service (starts on boot)')
     .option('--gateway <url>', 'Gateway URL', 'wss://webprev.live')
-    .option('--uninstall', 'Remove the background service')
-    .action(serviceCommand);
+    .action(serviceInstallCommand);
+service
+    .command('uninstall')
+    .description('Remove the background service')
+    .action(serviceUninstallCommand);
+service
+    .command('status')
+    .description('Check if the background service is running')
+    .action(serviceStatusCommand);
 program.parse();
 //# sourceMappingURL=cli.js.map

package/dist/commands/login.d.ts

@@ -1,4 +1,9 @@
 /**
  * Login command — authenticate with nstantpage.com
  */
-export declare function loginCommand(): Promise<void>;
+interface LoginOptions {
+    gateway?: string;
+    force?: boolean;
+}
+export declare function loginCommand(options?: LoginOptions): Promise<void>;
+export {};

package/dist/commands/login.js

@@ -5,21 +5,34 @@ import chalk from 'chalk';
 import open from 'open';
 import http from 'http';
 import { getConfig } from '../config.js';
-export async function loginCommand() {
+/**
+ * Resolve the frontend URL based on gateway.
+ * - If gateway points to localhost → frontend is http://localhost:5001
+ * - Otherwise → https://nstantpage.com
+ */
+function resolveFrontendUrl(gateway) {
+    if (gateway && /^wss?:\/\/(localhost|127\.0\.0\.1)/.test(gateway)) {
+        return 'http://localhost:5001';
+    }
+    return 'https://nstantpage.com';
+}
+export async function loginCommand(options = {}) {
     const conf = getConfig();
-    // Check if already logged in
+    // Check if already logged in (unless --force)
     const existingToken = conf.get('token');
-    if (existingToken) {
+    if (existingToken && !options.force) {
         console.log(chalk.green('✓ Already authenticated'));
         console.log(chalk.gray('  Run "nstantpage login --force" to re-authenticate'));
         return;
     }
-    console.log(chalk.blue('🔐 Authenticating with nstantpage.com...\n'));
+    const frontendUrl = resolveFrontendUrl(options.gateway);
+    const isLocal = frontendUrl.includes('localhost');
+    console.log(chalk.blue(`🔐 Authenticating with ${isLocal ? 'local server' : 'nstantpage.com'}...\n`));
     // Start local callback server
     const callbackPort = 18923;
     const token = await new Promise((resolve, reject) => {
         const server = http.createServer((req, res) => {
-            // Allow CORS from nstantpage.com (the auth page uses fetch())
+            // Allow CORS from frontend (the auth page uses fetch())
             res.setHeader('Access-Control-Allow-Origin', '*');
             res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
             res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
@@ -51,7 +64,7 @@ export async function loginCommand() {
             }
         });
         server.listen(callbackPort, () => {
-            const loginUrl = `https://nstantpage.com/auth/agent?callback=http://localhost:${callbackPort}/callback`;
+            const loginUrl = `${frontendUrl}/auth/agent?callback=http://localhost:${callbackPort}/callback`;
             console.log(chalk.gray(`  Opening browser to authenticate...`));
             console.log(chalk.gray(`  If browser doesn't open, visit: ${loginUrl}\n`));
             open(loginUrl).catch(() => {

package/dist/commands/service.d.ts

@@ -1,17 +1,24 @@
 /**
  * Service command — install/uninstall the nstantpage agent as a background service.
  *
+ * The service keeps the agent connected to your nstantpage.com account,
+ * ready to accept project connections from the web editor at any time.
+ * No project-id needed — projects are assigned from the web when you click "Connect".
+ *
  * macOS:   Uses launchd (~/Library/LaunchAgents/com.nstantpage.agent.plist)
  * Linux:   Uses systemd (--user mode: ~/.config/systemd/user/nstantpage-agent.service)
- * Windows: Uses node-windows / Task Scheduler (future)
+ * Windows: Uses Task Scheduler (future)
  *
- * This allows the agent to run on boot, always ready to accept connections
- * from the web editor without manually starting it each time.
+ * Usage:
+ *   nstantpage service install                — Install & start the background service
+ *   nstantpage service install --gateway URL  — Use a custom gateway
+ *   nstantpage service uninstall              — Remove the background service
+ *   nstantpage service status                 — Check if service is running
  */
-interface ServiceOptions {
-    projectId?: string;
+interface ServiceInstallOptions {
     gateway?: string;
-    uninstall?: boolean;
 }
-export declare function serviceCommand(options: ServiceOptions): Promise<void>;
+export declare function serviceInstallCommand(options?: ServiceInstallOptions): Promise<void>;
+export declare function serviceUninstallCommand(): Promise<void>;
+export declare function serviceStatusCommand(): Promise<void>;
 export {};

package/dist/commands/service.js

@@ -1,12 +1,19 @@
 /**
  * Service command — install/uninstall the nstantpage agent as a background service.
  *
+ * The service keeps the agent connected to your nstantpage.com account,
+ * ready to accept project connections from the web editor at any time.
+ * No project-id needed — projects are assigned from the web when you click "Connect".
+ *
  * macOS:   Uses launchd (~/Library/LaunchAgents/com.nstantpage.agent.plist)
  * Linux:   Uses systemd (--user mode: ~/.config/systemd/user/nstantpage-agent.service)
- * Windows: Uses node-windows / Task Scheduler (future)
+ * Windows: Uses Task Scheduler (future)
  *
- * This allows the agent to run on boot, always ready to accept connections
- * from the web editor without manually starting it each time.
+ * Usage:
+ *   nstantpage service install                — Install & start the background service
+ *   nstantpage service install --gateway URL  — Use a custom gateway
+ *   nstantpage service uninstall              — Remove the background service
+ *   nstantpage service status                 — Check if service is running
  */
 import chalk from 'chalk';
 import fs from 'fs';
@@ -16,21 +23,97 @@ import { execSync } from 'child_process';
 import { getConfig } from '../config.js';
 const PLIST_LABEL = 'com.nstantpage.agent';
 const SYSTEMD_SERVICE = 'nstantpage-agent';
-export async function serviceCommand(options) {
-    if (options.uninstall) {
-        return uninstallService();
+export async function serviceInstallCommand(options = {}) {
+    const conf = getConfig();
+    const token = conf.get('token');
+    if (!token) {
+        console.log(chalk.red('✗ Not authenticated. Run "nstantpage login" first.'));
+        process.exit(1);
+    }
+    const gateway = options.gateway || 'wss://webprev.live';
+    const platform = os.platform();
+    if (platform === 'darwin') {
+        await installLaunchd(gateway, token);
+    }
+    else if (platform === 'linux') {
+        await installSystemd(gateway, token);
+    }
+    else {
+        console.log(chalk.yellow('⚠ Background service not yet supported on this platform.'));
+        console.log(chalk.gray('  Use "nstantpage start --project-id X" to run manually.'));
+        console.log(chalk.gray('  Windows support coming soon.'));
+        process.exit(1);
     }
-    return installService(options);
 }
+export async function serviceUninstallCommand() {
+    const platform = os.platform();
+    if (platform === 'darwin') {
+        await uninstallLaunchd();
+    }
+    else if (platform === 'linux') {
+        await uninstallSystemd();
+    }
+    else {
+        console.log(chalk.yellow('  ⚠ Service uninstall not supported on this platform'));
+    }
+}
+export async function serviceStatusCommand() {
+    const platform = os.platform();
+    if (platform === 'darwin') {
+        try {
+            const result = execSync(`launchctl list | grep ${PLIST_LABEL}`, { encoding: 'utf-8' }).trim();
+            if (result) {
+                const parts = result.split('\t');
+                const pid = parts[0];
+                const lastExit = parts[1];
+                console.log(chalk.green('  ✓ Service is installed'));
+                console.log(chalk.gray(`  PID:        ${pid === '-' ? 'not running' : pid}`));
+                console.log(chalk.gray(`  Last exit:  ${lastExit}`));
+            }
+            else {
+                console.log(chalk.yellow('  ⚠ Service is not installed'));
+            }
+        }
+        catch {
+            console.log(chalk.yellow('  ⚠ Service is not installed'));
+        }
+    }
+    else if (platform === 'linux') {
+        try {
+            const result = execSync(`systemctl --user is-active ${SYSTEMD_SERVICE} 2>/dev/null`, { encoding: 'utf-8' }).trim();
+            console.log(chalk.green(`  ✓ Service is ${result}`));
+        }
+        catch {
+            console.log(chalk.yellow('  ⚠ Service is not running or not installed'));
+        }
+    }
+    else {
+        console.log(chalk.gray('  Service status not available on this platform'));
+    }
+    // Also check log file
+    const logPath = path.join(os.homedir(), '.nstantpage', 'agent.log');
+    if (fs.existsSync(logPath)) {
+        const stats = fs.statSync(logPath);
+        console.log(chalk.gray(`  Log file:   ${logPath} (${(stats.size / 1024).toFixed(1)}KB)`));
+        try {
+            const content = fs.readFileSync(logPath, 'utf-8');
+            const lines = content.trim().split('\n').slice(-5);
+            if (lines.length > 0) {
+                console.log(chalk.gray('  Last log lines:'));
+                lines.forEach(l => console.log(chalk.gray(`    ${l}`)));
+            }
+        }
+        catch { }
+    }
+}
+// ─── Helper Functions ─────────────────────────────────
 function getAgentBinPath() {
-    // Find the globally installed nstantpage binary
     try {
         const resolved = execSync('which nstantpage 2>/dev/null || which nstantpage-agent 2>/dev/null', { encoding: 'utf-8' }).trim();
         if (resolved)
             return resolved;
     }
     catch { }
-    // Fallback: try npm root -g
     try {
         const npmRoot = execSync('npm root -g', { encoding: 'utf-8' }).trim();
         const bin = path.join(npmRoot, '.bin', 'nstantpage');
@@ -48,44 +131,18 @@ function getNodePath() {
         return '/usr/local/bin/node';
     }
 }
-async function installService(options) {
-    const conf = getConfig();
-    const token = conf.get('token');
-    if (!token) {
-        console.log(chalk.red('✗ Not authenticated. Run "nstantpage login" first.'));
-        process.exit(1);
-    }
-    const projectId = options.projectId;
-    if (!projectId) {
-        console.log(chalk.red('✗ --project-id is required for service mode.'));
-        console.log(chalk.gray('  Example: nstantpage service --project-id 1234'));
-        process.exit(1);
-    }
-    const gateway = options.gateway || 'wss://webprev.live';
-    const platform = os.platform();
-    if (platform === 'darwin') {
-        await installLaunchd(projectId, gateway, token);
-    }
-    else if (platform === 'linux') {
-        await installSystemd(projectId, gateway, token);
-    }
-    else {
-        console.log(chalk.yellow('⚠ Background service not yet supported on this platform.'));
-        console.log(chalk.gray('  Use "nstantpage start" to run manually.'));
-        console.log(chalk.gray('  Windows support coming soon.'));
-        process.exit(1);
-    }
-}
-async function installLaunchd(projectId, gateway, token) {
+// ─── macOS (launchd) ──────────────────────────────────
+async function installLaunchd(gateway, token) {
     const binPath = getAgentBinPath();
     const nodePath = getNodePath();
     const plistDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
     const plistPath = path.join(plistDir, `${PLIST_LABEL}.plist`);
     const logPath = path.join(os.homedir(), '.nstantpage', 'agent.log');
     const errPath = path.join(os.homedir(), '.nstantpage', 'agent.err.log');
-    // Ensure dirs exist
     fs.mkdirSync(plistDir, { recursive: true });
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    // Service runs `nstantpage start --gateway <url> --token <token>`
+    // No --project-id: agent connects in standby, ready for web commands
     const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -97,8 +154,6 @@ async function installLaunchd(projectId, gateway, token) {
         <string>${nodePath}</string>
         <string>${binPath}</string>
         <string>start</string>
-        <string>--project-id</string>
-        <string>${projectId}</string>
         <string>--gateway</string>
         <string>${gateway}</string>
         <string>--token</string>
@@ -125,22 +180,35 @@ async function installLaunchd(projectId, gateway, token) {
 </dict>
 </plist>`;
     fs.writeFileSync(plistPath, plist, 'utf-8');
-    // Unload if already running
     try {
         execSync(`launchctl unload "${plistPath}" 2>/dev/null`, { encoding: 'utf-8' });
     }
     catch { }
-    // Load
     execSync(`launchctl load "${plistPath}"`, { encoding: 'utf-8' });
     console.log(chalk.green('\n  ✓ Agent installed as background service (launchd)\n'));
-    console.log(chalk.gray(`  Plist:    ${plistPath}`));
-    console.log(chalk.gray(`  Project:  ${projectId}`));
-    console.log(chalk.gray(`  Log:      ${logPath}`));
-    console.log(chalk.gray(`  Status:   launchctl list | grep nstantpage`));
-    console.log(chalk.gray(`  Stop:     nstantpage service --uninstall\n`));
-    console.log(chalk.blue('  The agent will now start automatically on login.'));
+    console.log(chalk.gray(`  Plist:   ${plistPath}`));
+    console.log(chalk.gray(`  Log:     ${logPath}`));
+    console.log(chalk.gray(`  Status:  nstantpage service status`));
+    console.log(chalk.gray(`  Remove:  nstantpage service uninstall\n`));
+    console.log(chalk.blue('  The agent will start on login and stay connected to your account.'));
+    console.log(chalk.blue('  Open any project on nstantpage.com and click "Connect" to use it.\n'));
+}
+async function uninstallLaunchd() {
+    const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${PLIST_LABEL}.plist`);
+    if (!fs.existsSync(plistPath)) {
+        console.log(chalk.yellow('  ⚠ Service is not installed'));
+        return;
+    }
+    try {
+        execSync(`launchctl unload "${plistPath}" 2>/dev/null`, { encoding: 'utf-8' });
+    }
+    catch { }
+    fs.unlinkSync(plistPath);
+    console.log(chalk.green('  ✓ Agent service uninstalled (launchd)'));
+    console.log(chalk.gray('  The agent will no longer start automatically.'));
 }
-async function installSystemd(projectId, gateway, token) {
+// ─── Linux (systemd) ─────────────────────────────────
+async function installSystemd(gateway, token) {
     const binPath = getAgentBinPath();
     const serviceDir = path.join(os.homedir(), '.config', 'systemd', 'user');
     const servicePath = path.join(serviceDir, `${SYSTEMD_SERVICE}.service`);
@@ -152,7 +220,7 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-ExecStart=${binPath} start --project-id ${projectId} --gateway ${gateway} --token ${token}
+ExecStart=${binPath} start --gateway ${gateway} --token ${token}
 Restart=on-failure
 RestartSec=10
 Environment=PATH=/usr/local/bin:/usr/bin:/bin
@@ -172,44 +240,30 @@ WantedBy=default.target
         console.log(chalk.gray('  You may need to reload manually: systemctl --user daemon-reload'));
     }
     console.log(chalk.green('\n  ✓ Agent installed as background service (systemd --user)\n'));
-    console.log(chalk.gray(`  Unit:     ${servicePath}`));
-    console.log(chalk.gray(`  Project:  ${projectId}`));
-    console.log(chalk.gray(`  Status:   systemctl --user status ${SYSTEMD_SERVICE}`));
-    console.log(chalk.gray(`  Logs:     journalctl --user -u ${SYSTEMD_SERVICE} -f`));
-    console.log(chalk.gray(`  Stop:     nstantpage service --uninstall\n`));
-    console.log(chalk.blue('  The agent will now start automatically on login.'));
+    console.log(chalk.gray(`  Unit:    ${servicePath}`));
+    console.log(chalk.gray(`  Status:  nstantpage service status`));
+    console.log(chalk.gray(`  Logs:    journalctl --user -u ${SYSTEMD_SERVICE} -f`));
+    console.log(chalk.gray(`  Remove:  nstantpage service uninstall\n`));
+    console.log(chalk.blue('  The agent will start on login and stay connected to your account.'));
+    console.log(chalk.blue('  Open any project on nstantpage.com and click "Connect" to use it.\n'));
 }
-async function uninstallService() {
-    const platform = os.platform();
-    if (platform === 'darwin') {
-        const plistPath = path.join(os.homedir(), 'Library', 'LaunchAgents', `${PLIST_LABEL}.plist`);
-        try {
-            execSync(`launchctl unload "${plistPath}" 2>/dev/null`, { encoding: 'utf-8' });
-        }
-        catch { }
-        if (fs.existsSync(plistPath)) {
-            fs.unlinkSync(plistPath);
-        }
-        console.log(chalk.green('  ✓ Agent service uninstalled (launchd)'));
+async function uninstallSystemd() {
+    const servicePath = path.join(os.homedir(), '.config', 'systemd', 'user', `${SYSTEMD_SERVICE}.service`);
+    if (!fs.existsSync(servicePath)) {
+        console.log(chalk.yellow('  ⚠ Service is not installed'));
+        return;
     }
-    else if (platform === 'linux') {
-        try {
-            execSync(`systemctl --user stop ${SYSTEMD_SERVICE} 2>/dev/null`, { encoding: 'utf-8' });
-            execSync(`systemctl --user disable ${SYSTEMD_SERVICE} 2>/dev/null`, { encoding: 'utf-8' });
-        }
-        catch { }
-        const servicePath = path.join(os.homedir(), '.config', 'systemd', 'user', `${SYSTEMD_SERVICE}.service`);
-        if (fs.existsSync(servicePath)) {
-            fs.unlinkSync(servicePath);
-            try {
-                execSync('systemctl --user daemon-reload', { encoding: 'utf-8' });
-            }
-            catch { }
-        }
-        console.log(chalk.green('  ✓ Agent service uninstalled (systemd)'));
+    try {
+        execSync(`systemctl --user stop ${SYSTEMD_SERVICE} 2>/dev/null`, { encoding: 'utf-8' });
+        execSync(`systemctl --user disable ${SYSTEMD_SERVICE} 2>/dev/null`, { encoding: 'utf-8' });
     }
-    else {
-        console.log(chalk.yellow('  ⚠ Service uninstall not supported on this platform'));
+    catch { }
+    fs.unlinkSync(servicePath);
+    try {
+        execSync('systemctl --user daemon-reload', { encoding: 'utf-8' });
     }
+    catch { }
+    console.log(chalk.green('  ✓ Agent service uninstalled (systemd)'));
+    console.log(chalk.gray('  The agent will no longer start automatically.'));
 }
 //# sourceMappingURL=service.js.map

package/dist/commands/start.js

@@ -24,7 +24,7 @@ import { getConfig, getProjectConfig, setProjectConfig, clearProjectConfig, getD
 import { TunnelClient } from '../tunnel.js';
 import { LocalServer } from '../localServer.js';
 import { PackageInstaller } from '../packageInstaller.js';
-const VERSION = '0.4.1';
+const VERSION = '0.5.0';
 /**
  * Resolve the backend API base URL.
  * - If --backend is passed, use it
@@ -175,13 +175,14 @@ export async function startCommand(directory, options) {
     if (!token && isLocalGateway) {
         token = 'local-dev';
     }
-    // Determine project ID
+    // Determine project ID (optional — without it, agent enters standby mode)
     let projectId = options.projectId || conf.get('projectId');
+    const backendUrl = resolveBackendUrl(options);
+    const deviceId = getDeviceId();
     if (!projectId) {
-        console.log(chalk.yellow('⚠ No project ID specified.'));
-        console.log(chalk.gray('  Use --project-id <id>'));
-        console.log(chalk.gray('  Example: npx nstantpage-agent start --project-id 1234'));
-        process.exit(1);
+        // No project specified — enter standby mode
+        await startStandbyMode(token, options, backendUrl, deviceId);
+        return;
     }
     // Auto-assign ports per project (unless user explicitly specified them)
     const userSpecifiedPort = options.port !== '3000';
@@ -207,8 +208,6 @@ export async function startCommand(directory, options) {
     }
     // Save project ID
     conf.set('projectId', projectId);
-    const backendUrl = resolveBackendUrl(options);
-    const deviceId = getDeviceId();
     // Kill any leftover agent for THIS PROJECT only (not other projects)
     cleanupPreviousAgent(projectId, apiPort, devPort);
     // Small delay to let ports release
@@ -271,6 +270,11 @@ export async function startCommand(directory, options) {
         projectId,
         apiPort,
         devPort,
+        onStartProject: async (pid) => {
+            await startAdditionalProject(pid, {
+                token, backendUrl, gatewayUrl: options.gateway, deviceId, noDev: options.noDev,
+            });
+        },
     });
     // 5. Register device with backend
     let heartbeatInterval = null;
@@ -424,4 +428,191 @@ export async function startCommand(directory, options) {
         process.exit(1);
     }
 }
+// ─── Standby Mode ────────────────────────────────────────────────────────
+/**
+ * Run the agent in standby mode — no initial project.
+ * Connects to gateway and waits for start-project commands from the web UI.
+ * This is used by `nstantpage service install` (background service).
+ */
+async function startStandbyMode(token, options, backendUrl, deviceId) {
+    console.log(chalk.blue(`\n🚀 nstantpage agent v${VERSION} (standby mode)\n`));
+    console.log(chalk.gray(`  Device ID:    ${deviceId.slice(0, 12)}...`));
+    console.log(chalk.gray(`  Device:       ${os.hostname()} (${os.platform()} ${os.arch()})`));
+    console.log(chalk.gray(`  Gateway:      ${options.gateway}`));
+    console.log(chalk.gray(`  Backend:      ${backendUrl}\n`));
+    const activeProjects = new Map();
+    // Create standby tunnel (for receiving start-project commands)
+    const standbyTunnel = new TunnelClient({
+        gatewayUrl: options.gateway,
+        token,
+        projectId: '_standby_',
+        apiPort: 0,
+        devPort: 0,
+        onStartProject: async (pid) => {
+            if (activeProjects.has(pid)) {
+                console.log(chalk.yellow(`  Project ${pid} is already running`));
+                return;
+            }
+            const result = await startAdditionalProject(pid, {
+                token, backendUrl, gatewayUrl: options.gateway, deviceId, noDev: options.noDev,
+            });
+            if (result)
+                activeProjects.set(pid, result);
+        },
+    });
+    // Register device with backend (no project)
+    try {
+        const res = await fetch(`${backendUrl}/api/agent/register`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                deviceId, name: os.hostname(), hostname: os.hostname(),
+                platform: `${os.platform()} ${os.arch()}`, agentVersion: VERSION,
+                capabilities: ['file-sync', 'type-check', 'install', 'terminal', 'dev-server'],
+            }),
+        });
+        if (res.ok)
+            console.log(chalk.green(`  ✓ Device registered`));
+        else
+            console.log(chalk.gray(`  ⚠ Device registration: ${res.status}`));
+    }
+    catch (err) {
+        console.log(chalk.gray(`  ⚠ Device registration: ${err.message}`));
+    }
+    // Connect standby tunnel
+    try {
+        await standbyTunnel.connect();
+        console.log(chalk.green(`  ✓ Connected to gateway\n`));
+    }
+    catch (err) {
+        console.log(chalk.yellow(`  ⚠ Gateway connection failed: ${err.message}`));
+        standbyTunnel.startBackgroundReconnect();
+    }
+    // Heartbeat
+    setInterval(async () => {
+        try {
+            await fetch(`${backendUrl}/api/agent/heartbeat`, {
+                method: 'POST',
+                headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    deviceId, activeProjectIds: Array.from(activeProjects.keys()), agentVersion: VERSION,
+                }),
+            });
+        }
+        catch { }
+    }, 60_000);
+    // Shutdown handler
+    const shutdown = async () => {
+        console.log(chalk.yellow('\n  Shutting down...'));
+        standbyTunnel.disconnect();
+        for (const [, proj] of activeProjects) {
+            proj.tunnel.disconnect();
+            await proj.localServer.stop();
+        }
+        try {
+            await fetch(`${backendUrl}/api/agent/disconnect`, {
+                method: 'POST',
+                headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify({ deviceId }),
+            });
+        }
+        catch { }
+        process.exit(0);
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    console.log(chalk.blue.bold(`  ┌──────────────────────────────────────────────┐`));
+    console.log(chalk.blue.bold(`  │  Agent ready (standby mode)                  │`));
+    console.log(chalk.blue.bold(`  ├──────────────────────────────────────────────┤`));
+    console.log(chalk.white(`  │  Device: ${os.hostname()}`));
+    console.log(chalk.white(`  │  Waiting for project assignments...`));
+    console.log(chalk.blue.bold(`  └──────────────────────────────────────────────┘\n`));
+    console.log(chalk.gray(`  Open any project on nstantpage.com and click "Connect"`));
+    console.log(chalk.gray(`  to start it on this machine.`));
+    console.log(chalk.gray(`  Press Ctrl+C to stop\n`));
+    await new Promise(() => { });
+}
+// ─── Multi-Project Helper ────────────────────────────────────────────────
+/**
+ * Start an additional project on this agent.
+ * Called via the tunnel's onStartProject callback when the web UI
+ * sends a start-project command.
+ */
+async function startAdditionalProject(projectId, opts) {
+    console.log(chalk.blue(`\n  📦 Starting project ${projectId}...`));
+    try {
+        const allocated = allocatePortsForProject(projectId);
+        const projectDir = resolveProjectDir('.', projectId);
+        if (!fs.existsSync(projectDir))
+            fs.mkdirSync(projectDir, { recursive: true });
+        // Fetch project files
+        try {
+            await fetchProjectFiles(opts.backendUrl, projectId, projectDir, opts.token);
+        }
+        catch (err) {
+            console.log(chalk.yellow(`  ⚠ Could not fetch files: ${err.message}`));
+        }
+        // Install dependencies
+        const hasNodeModules = fs.existsSync(path.join(projectDir, 'node_modules'));
+        if (!hasNodeModules && fs.existsSync(path.join(projectDir, 'package.json'))) {
+            console.log(chalk.gray(`  Installing dependencies...`));
+            const installer = new PackageInstaller({ projectDir });
+            const result = await installer.install([], false);
+            if (result.success)
+                console.log(chalk.green(`  ✓ Dependencies installed`));
+        }
+        // Start local server
+        const localServer = new LocalServer({
+            projectDir, projectId,
+            apiPort: allocated.apiPort, devPort: allocated.devPort,
+        });
+        await localServer.start();
+        console.log(chalk.green(`  ✓ API server on port ${allocated.apiPort}`));
+        // Start dev server
+        if (!opts.noDev) {
+            try {
+                await localServer.getDevServer().start();
+                console.log(chalk.green(`  ✓ Dev server on port ${allocated.devPort}`));
+            }
+            catch (err) {
+                console.log(chalk.yellow(`  ⚠ Dev server: ${err.message}`));
+            }
+        }
+        // Connect project tunnel
+        const tunnel = new TunnelClient({
+            gatewayUrl: opts.gatewayUrl,
+            token: opts.token,
+            projectId,
+            apiPort: allocated.apiPort,
+            devPort: allocated.devPort,
+        });
+        try {
+            await tunnel.connect();
+            console.log(chalk.green(`  ✓ Tunnel connected for project ${projectId}`));
+        }
+        catch (err) {
+            console.log(chalk.yellow(`  ⚠ Tunnel: ${err.message}`));
+            tunnel.startBackgroundReconnect();
+        }
+        // Register project with backend
+        try {
+            await fetch(`${opts.backendUrl}/api/agent/register`, {
+                method: 'POST',
+                headers: { 'Authorization': `Bearer ${opts.token}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    deviceId: opts.deviceId, name: os.hostname(), hostname: os.hostname(),
+                    platform: `${os.platform()} ${os.arch()}`, agentVersion: VERSION,
+                    projectId, capabilities: ['file-sync', 'type-check', 'install', 'terminal', 'dev-server'],
+                }),
+            });
+        }
+        catch { }
+        console.log(chalk.green(`  ✓ Project ${projectId} is live!\n`));
+        return { localServer, tunnel };
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ Failed to start project ${projectId}: ${err.message}`));
+        return null;
+    }
+}
 //# sourceMappingURL=start.js.map

package/dist/localServer.d.ts

@@ -12,7 +12,37 @@
  *
  * Requests arrive through the tunnel from the gateway.
  */
+import { ChildProcess } from 'child_process';
 import { DevServer } from './devServer.js';
+interface TerminalSession {
+    id: string;
+    projectId: string;
+    shell: ChildProcess;
+    outputBuffer: string[];
+    createdAt: number;
+    lastActivity: number;
+    cols: number;
+    rows: number;
+    isAiSession: boolean;
+    label: string;
+    exited: boolean;
+    exitCode: number | null;
+    /** Real-time output listeners for WebSocket relay */
+    dataListeners: Set<(data: string) => void>;
+    exitListeners: Set<(code: number | null) => void>;
+}
+/**
+ * Get a terminal session by ID (used by WS relay in tunnel).
+ */
+export declare function getTerminalSession(sessionId: string): TerminalSession | undefined;
+/**
+ * Attach a real-time listener to a terminal session (for WebSocket relay).
+ * Returns a cleanup function to detach.
+ */
+export declare function attachTerminalClient(sessionId: string, callbacks: {
+    onData: (data: string) => void;
+    onExit: (code: number | null) => void;
+}): (() => void) | null;
 export interface LocalServerOptions {
     projectDir: string;
     projectId: string;
@@ -72,3 +102,4 @@ export declare class LocalServer {
     private json;
     private collectBody;
 }
+export {};

package/dist/localServer.js

@@ -21,9 +21,41 @@ import { Checker } from './checker.js';
 import { ErrorStore, structuredErrorToString } from './errorStore.js';
 import { PackageInstaller } from './packageInstaller.js';
 const terminalSessions = new Map();
+let sessionCounter = 0;
 function generateSessionId() {
     return Math.random().toString(16).slice(2, 10);
 }
+/**
+ * Get a terminal session by ID (used by WS relay in tunnel).
+ */
+export function getTerminalSession(sessionId) {
+    return terminalSessions.get(sessionId);
+}
+/**
+ * Attach a real-time listener to a terminal session (for WebSocket relay).
+ * Returns a cleanup function to detach.
+ */
+export function attachTerminalClient(sessionId, callbacks) {
+    const session = terminalSessions.get(sessionId);
+    if (!session)
+        return null;
+    session.dataListeners.add(callbacks.onData);
+    session.exitListeners.add(callbacks.onExit);
+    // Send scrollback immediately
+    if (session.outputBuffer.length > 0) {
+        const scrollback = session.outputBuffer.join('');
+        callbacks.onData(scrollback);
+    }
+    // If session already exited, notify immediately
+    if (session.exited) {
+        callbacks.onExit(session.exitCode);
+    }
+    // Return cleanup function
+    return () => {
+        session.dataListeners.delete(callbacks.onData);
+        session.exitListeners.delete(callbacks.onExit);
+    };
+}
 export class LocalServer {
     server = null;
     options;
@@ -303,13 +335,16 @@ export class LocalServer {
             const sessions = Array.from(terminalSessions.values())
                 .filter(s => s.projectId === this.options.projectId)
                 .map(s => ({
-                sessionId: s.id,
+                id: s.id,
                 projectId: s.projectId,
+                isAiSession: s.isAiSession,
+                label: s.label,
                 createdAt: s.createdAt,
                 lastActivity: s.lastActivity,
+                exited: s.exited,
+                exitCode: s.exitCode,
                 cols: s.cols,
                 rows: s.rows,
-                isAiSession: s.isAiSession,
             }));
             this.json(res, { success: true, sessions });
             return;
@@ -336,6 +371,8 @@ export class LocalServer {
             env: { ...process.env, TERM: 'xterm-256color', COLUMNS: String(cols), LINES: String(rows) },
             stdio: ['pipe', 'pipe', 'pipe'],
         });
+        sessionCounter++;
+        const label = parsed.label || `Terminal ${sessionCounter}`;
         const session = {
             id: sessionId,
             projectId: this.options.projectId,
@@ -346,31 +383,69 @@ export class LocalServer {
             cols,
             rows,
             isAiSession,
+            label,
+            exited: false,
+            exitCode: null,
+            dataListeners: new Set(),
+            exitListeners: new Set(),
         };
         shell.stdout?.on('data', (data) => {
-            session.outputBuffer.push(data.toString('utf-8'));
+            const str = data.toString('utf-8');
+            session.outputBuffer.push(str);
             session.lastActivity = Date.now();
             // Keep buffer capped at ~100KB
             while (session.outputBuffer.length > 500)
                 session.outputBuffer.shift();
+            // Notify real-time listeners (WebSocket relay)
+            for (const listener of session.dataListeners) {
+                try {
+                    listener(str);
+                }
+                catch { }
+            }
         });
         shell.stderr?.on('data', (data) => {
-            session.outputBuffer.push(data.toString('utf-8'));
+            const str = data.toString('utf-8');
+            session.outputBuffer.push(str);
             session.lastActivity = Date.now();
             while (session.outputBuffer.length > 500)
                 session.outputBuffer.shift();
+            // Notify real-time listeners
+            for (const listener of session.dataListeners) {
+                try {
+                    listener(str);
+                }
+                catch { }
+            }
         });
-        shell.on('exit', () => {
+        shell.on('exit', (code) => {
+            session.exited = true;
+            session.exitCode = code;
+            // Notify exit listeners
+            for (const listener of session.exitListeners) {
+                try {
+                    listener(code);
+                }
+                catch { }
+            }
             terminalSessions.delete(sessionId);
         });
         terminalSessions.set(sessionId, session);
+        // Return format matching frontend TerminalSessionInfo
         this.json(res, {
             success: true,
-            sessionId,
-            projectId: this.options.projectId,
-            cols,
-            rows,
-            isAiSession,
+            session: {
+                id: sessionId,
+                projectId: this.options.projectId,
+                isAiSession,
+                label,
+                createdAt: session.createdAt,
+                lastActivity: session.lastActivity,
+                exited: false,
+                exitCode: null,
+                cols,
+                rows,
+            },
         });
     }
     // ─── /live/terminal/write ────────────────────────────────────
@@ -427,7 +502,7 @@ export class LocalServer {
             connected: true,
             projectId: this.options.projectId,
             agent: {
-                version: '0.4.1',
+                version: '0.5.0',
                 hostname: os.hostname(),
                 platform: `${os.platform()} ${os.arch()}`,
             },

package/dist/tunnel.d.ts

@@ -23,6 +23,8 @@ interface TunnelClientOptions {
     apiPort: number;
     /** Port where the dev server (Vite/Next.js) runs */
     devPort: number;
+    /** Callback when gateway requests starting a new project on this device */
+    onStartProject?: (projectId: string) => Promise<void>;
 }
 export declare class TunnelClient {
     private ws;
@@ -34,6 +36,8 @@ export declare class TunnelClient {
     private pingInterval;
     private requestsForwarded;
     private connectedAt;
+    /** Active WebSocket channels (terminal WS relay through tunnel) */
+    private wsChannels;
     constructor(options: TunnelClientOptions);
     get isConnected(): boolean;
     get stats(): {
@@ -59,6 +63,25 @@ export declare class TunnelClient {
         lintErrors: string[];
         runtimeErrors: string[];
     }): void;
+    /**
+     * Handle ws-open: gateway wants to open a virtual WebSocket channel
+     * for a terminal session. Attach to the session's I/O.
+     */
+    private handleWsOpen;
+    /**
+     * Handle ws-data: frontend sent a message through the terminal WebSocket.
+     * Parse it and route to the terminal session.
+     */
+    private handleWsData;
+    /**
+     * Handle ws-close: frontend disconnected the terminal WebSocket.
+     */
+    private handleWsClose;
+    /**
+     * Handle start-project: gateway wants this agent to start serving a new project.
+     * Called when user clicks "Connect" in the web editor's Cloud panel.
+     */
+    private handleStartProject;
     private send;
     private handleMessage;
     /**

package/dist/tunnel.js

@@ -19,6 +19,7 @@ import WebSocket from 'ws';
 import http from 'http';
 import os from 'os';
 import { getDeviceId } from './config.js';
+import { getTerminalSession, attachTerminalClient } from './localServer.js';
 export class TunnelClient {
     ws = null;
     options;
@@ -29,6 +30,8 @@ export class TunnelClient {
     pingInterval = null;
     requestsForwarded = 0;
     connectedAt = 0;
+    /** Active WebSocket channels (terminal WS relay through tunnel) */
+    wsChannels = new Map();
     constructor(options) {
         this.options = options;
     }
@@ -59,7 +62,7 @@ export class TunnelClient {
                 // Send enhanced agent info with capabilities and deviceId
                 this.send({
                     type: 'agent-info',
-                    version: '0.4.0',
+                    version: '0.5.0',
                     hostname: os.hostname(),
                     platform: `${os.platform()} ${os.arch()}`,
                     deviceId: getDeviceId(),
@@ -138,6 +141,119 @@ export class TunnelClient {
             errors,
         });
     }
+    // ─── WebSocket Relay (terminal WS through tunnel) ──────────
+    /**
+     * Handle ws-open: gateway wants to open a virtual WebSocket channel
+     * for a terminal session. Attach to the session's I/O.
+     */
+    handleWsOpen(wsId, sessionId, _projectId) {
+        const session = getTerminalSession(sessionId);
+        if (!session) {
+            // Session not found — send error and close
+            this.send({
+                type: 'ws-data',
+                wsId,
+                data: JSON.stringify({ type: 'error', message: `Session ${sessionId} not found` }),
+            });
+            this.send({ type: 'ws-close', wsId });
+            return;
+        }
+        const cleanup = attachTerminalClient(sessionId, {
+            onData: (data) => {
+                // Send terminal output as WS protocol message
+                this.send({
+                    type: 'ws-data',
+                    wsId,
+                    data: JSON.stringify({ type: 'output', data }),
+                });
+            },
+            onExit: (exitCode) => {
+                this.send({
+                    type: 'ws-data',
+                    wsId,
+                    data: JSON.stringify({ type: 'exit', exitCode }),
+                });
+                this.send({ type: 'ws-close', wsId });
+                this.wsChannels.delete(wsId);
+            },
+        });
+        this.wsChannels.set(wsId, { sessionId, cleanup });
+        // Send connection confirmation
+        this.send({
+            type: 'ws-data',
+            wsId,
+            data: JSON.stringify({ type: 'connected', sessionId, projectId: session.projectId }),
+        });
+    }
+    /**
+     * Handle ws-data: frontend sent a message through the terminal WebSocket.
+     * Parse it and route to the terminal session.
+     */
+    handleWsData(wsId, data) {
+        const channel = this.wsChannels.get(wsId);
+        if (!channel)
+            return;
+        try {
+            const msg = JSON.parse(data);
+            const session = getTerminalSession(channel.sessionId);
+            if (!session)
+                return;
+            switch (msg.type) {
+                case 'input':
+                    if (typeof msg.data === 'string') {
+                        session.shell.stdin?.write(msg.data);
+                        session.lastActivity = Date.now();
+                    }
+                    break;
+                case 'resize':
+                    if (typeof msg.cols === 'number' && typeof msg.rows === 'number') {
+                        session.cols = msg.cols;
+                        session.rows = msg.rows;
+                        // Note: child_process.spawn doesn't support resize natively
+                        // (only node-pty does). We update the stored size for future use.
+                    }
+                    break;
+            }
+        }
+        catch {
+            // Invalid JSON — ignore
+        }
+    }
+    /**
+     * Handle ws-close: frontend disconnected the terminal WebSocket.
+     */
+    handleWsClose(wsId) {
+        const channel = this.wsChannels.get(wsId);
+        if (channel) {
+            if (channel.cleanup)
+                channel.cleanup();
+            this.wsChannels.delete(wsId);
+        }
+    }
+    /**
+     * Handle start-project: gateway wants this agent to start serving a new project.
+     * Called when user clicks "Connect" in the web editor's Cloud panel.
+     */
+    async handleStartProject(projectId) {
+        console.log(`  [Tunnel] Received start-project command for ${projectId}`);
+        if (!projectId) {
+            this.send({ type: 'start-project-result', success: false, error: 'Missing projectId' });
+            return;
+        }
+        if (this.options.onStartProject) {
+            try {
+                await this.options.onStartProject(projectId);
+                this.send({ type: 'start-project-result', projectId, success: true });
+            }
+            catch (err) {
+                console.error(`  [Tunnel] Failed to start project ${projectId}:`, err.message);
+                this.send({ type: 'start-project-result', projectId, success: false, error: err.message });
+            }
+        }
+        else {
+            this.send({ type: 'start-project-result', success: false, error: 'Agent does not support remote project start' });
+        }
+    }
     send(msg) {
         if (this.ws?.readyState === WebSocket.OPEN) {
             this.ws.send(JSON.stringify(msg));
@@ -151,6 +267,18 @@ export class TunnelClient {
             case 'http-request':
                 this.handleHttpRequest(msg);
                 break;
+            case 'ws-open':
+                this.handleWsOpen(msg.wsId, msg.sessionId, msg.projectId);
+                break;
+            case 'ws-data':
+                this.handleWsData(msg.wsId, msg.data);
+                break;
+            case 'ws-close':
+                this.handleWsClose(msg.wsId);
+                break;
+            case 'start-project':
+                this.handleStartProject(msg.projectId);
+                break;
             default:
                 console.warn(`  [Tunnel] Unknown message type: ${msg.type}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nstantpage-agent",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Local development agent for nstantpage.com — run your projects locally, preview in the cloud. Replaces cloud containers for faster builds.",
   "type": "module",
   "bin": {