@papercraneai/sandbox-agent 0.1.16 → 0.1.17-beta.1

package/dist/index.js

@@ -46,7 +46,9 @@ function parseArgs() {
         devPort: parseInt(process.env.DEV_PORT || "3000"),
         workdir: join(homedir(), ".papercrane", "sandbox"),
         agentOnly: false,
-        hostMode: (process.env.HOST_MODE || "localhost")
+        hostMode: (process.env.HOST_MODE || "localhost"),
+        agentEndpoint: null,
+        dashboardsEndpoint: null,
     };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -79,6 +81,17 @@ function parseArgs() {
             }
             result.hostMode = mode;
         }
+        else if (arg === "--agent-endpoint" && args[i + 1]) {
+            // URL papercrane should use to reach this agent. Required for BYOC
+            // deployments where localhost / LAN auto-detection isn't reachable
+            // by papercrane (e.g., a Tailscale MagicDNS URL).
+            result.agentEndpoint = args[++i];
+        }
+        else if (arg === "--dashboards-endpoint" && args[i + 1]) {
+            // URL papercrane (and ultimately the browser iframe) should use to
+            // reach this sandbox's dev server. Same rationale as --agent-endpoint.
+            result.dashboardsEndpoint = args[++i];
+        }
         else if (arg === "--version" || arg === "-v") {
             console.log(pkg.version);
             process.exit(0);
@@ -95,15 +108,18 @@ Modes:
   Agent-only:             Just runs the agent API (use with --agent-only)
 
 Options:
-  --workdir <path>        Project directory (default: ~/.papercrane/sandbox)
-  --agent-only            Only run agent API (no template setup, no dev server)
-  --port <port>           Agent API port (default: 3001)
-  --dev-port <port>       Dev server port, standalone only (default: 3000)
-  --host-mode <mode>      Host for advertised URLs: localhost or lan (default: localhost)
-  --register              Register with Papercrane server (requires --token)
-  --token <token>         Connection token from Papercrane UI
-  --papercrane-url <url>  Papercrane server URL (default: https://fly.papercrane.ai)
-  --help, -h              Show this help message
+  --workdir <path>             Project directory (default: ~/.papercrane/sandbox)
+  --agent-only                 Only run agent API (no template setup, no dev server)
+  --port <port>                Agent API port (default: 3001)
+  --dev-port <port>            Dev server port, standalone only (default: 3000)
+  --host-mode <mode>           Host for advertised URLs: localhost or lan (default: localhost)
+  --register                   Register with Papercrane server (requires --token)
+  --token <token>              Connection token from Papercrane UI
+  --papercrane-url <url>       Papercrane server URL (default: https://fly.papercrane.ai)
+  --agent-endpoint <url>       URL Papercrane uses to reach this agent (overrides default
+                               localhost/LAN auto-detection; required for BYOC deployments)
+  --dashboards-endpoint <url>  URL Papercrane / iframe uses for the dev server (same purpose)
+  --help, -h                   Show this help message
 
 Environment Variables:
   PORT                    Agent API port (same as --port)
@@ -115,6 +131,9 @@ Examples:
   sandbox-agent                                    # Standalone: full setup
   sandbox-agent --workdir ~/my-project            # Standalone: custom directory
   sandbox-agent --agent-only --workdir /tmp/app   # Agent-only: just the API
+  sandbox-agent --register --token tok_abc \\
+    --agent-endpoint http://sandbox-abc.tail-x.ts.net:3001 \\
+    --dashboards-endpoint http://sandbox-abc.tail-x.ts.net:3000  # BYOC self-register
       `);
             process.exit(0);
         }
@@ -380,6 +399,7 @@ const sessionContext = {};
 // Registration state
 let environmentId = null;
 let connectionToken = null;
+let registeredPapercraneUrl = null;
 let heartbeatInterval = null;
 // Client-side tool: ShowPreview
 const showPreviewTool = tool("ShowPreview", "Shows the preview iframe for a specific route. Call this after creating or modifying a visualization so the user can see the result immediately. The preview will appear in the user's browser.", {
@@ -524,20 +544,7 @@ app.post("/cli/refresh", async (_req, res) => {
     if (!gitRoot)
         return;
     const { workspaceRefresh } = await import("@papercraneai/cli/lib/workspace-ops.js");
-    const result = await workspaceRefresh(gitRoot);
-    // If we start seeing publishes that change npm deps frequently, enable this
-    // block so refresh re-installs node_modules and bounces the dev-server PM2
-    // process (sandbox-agent stays up). Today most refreshes are dashboard source
-    // only, so paying the install + restart cost (and brief 502s on any open
-    // preview URL) on every push isn't worth it.
-    //
-    // const packageJsonChanged = result.filesChanged?.some((f: string) => f === "package.json" || f === "package-lock.json")
-    // if (packageJsonChanged) {
-    //   await runNpmInstall(gitRoot)
-    //   execSync("pm2 restart dev-server")
-    // }
-    // await ensureAppScaffold(gitRoot)
-    res.json(result);
+    res.json(await workspaceRefresh(gitRoot));
 });
 app.post("/cli/publish", async (req, res) => {
     const gitRoot = await resolveGitRoot(res);
@@ -1484,21 +1491,22 @@ app.post("/chat", async (req, res) => {
 // =============================================================================
 // Registration & Heartbeat
 // =============================================================================
-async function registerWithPapercrane() {
-    if (!cliArgs.token) {
+async function registerWithPapercrane(overrides) {
+    const token = overrides?.token ?? cliArgs.token;
+    const papercraneUrl = overrides?.papercraneUrl ?? cliArgs.papercraneUrl;
+    if (!token) {
         console.error("Error: --token is required when using --register");
         return false;
     }
-    console.log(`Registering with Papercrane server at ${cliArgs.papercraneUrl}...`);
+    console.log(`Registering with Papercrane server at ${papercraneUrl}...`);
     try {
-        const host = cliArgs.hostMode === "lan" ? getLocalNetworkIP() : "localhost";
-        const agentEndpoint = `http://${host}:${cliArgs.agentPort}`;
-        const previewEndpoint = `http://${host}:${cliArgs.devPort}`;
-        const res = await fetch(`${cliArgs.papercraneUrl}/api/environments/register`, {
+        const agentEndpoint = overrides?.agentEndpoint ?? `http://${cliArgs.hostMode === "lan" ? getLocalNetworkIP() : "localhost"}:${cliArgs.agentPort}`;
+        const previewEndpoint = overrides?.previewEndpoint ?? `http://${cliArgs.hostMode === "lan" ? getLocalNetworkIP() : "localhost"}:${cliArgs.devPort}`;
+        const res = await fetch(`${papercraneUrl}/api/environments/register`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
-                connectionToken: cliArgs.token,
+                connectionToken: token,
                 agentEndpoint,
                 previewEndpoint
             })
@@ -1510,7 +1518,8 @@ async function registerWithPapercrane() {
         }
         const data = await res.json();
         environmentId = data.environmentId;
-        connectionToken = cliArgs.token;
+        connectionToken = token;
+        registeredPapercraneUrl = papercraneUrl;
         console.log(`✓ Successfully registered as environment #${environmentId}`);
         console.log(`  Agent endpoint: ${agentEndpoint}`);
         console.log(`  Preview endpoint: ${previewEndpoint}`);
@@ -1526,7 +1535,7 @@ async function sendHeartbeat() {
     if (!environmentId || !connectionToken)
         return;
     try {
-        const res = await fetch(`${cliArgs.papercraneUrl}/api/environments/${environmentId}/heartbeat`, {
+        const res = await fetch(`${registeredPapercraneUrl ?? cliArgs.papercraneUrl}/api/environments/${environmentId}/heartbeat`, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
@@ -1575,7 +1584,7 @@ function handleShutdown(exitCode = 0) {
     // Notify Papercrane of disconnect
     if (environmentId && connectionToken) {
         console.log("Disconnecting from Papercrane...");
-        fetch(`${cliArgs.papercraneUrl}/api/environments/${environmentId}/disconnect`, {
+        fetch(`${registeredPapercraneUrl ?? cliArgs.papercraneUrl}/api/environments/${environmentId}/disconnect`, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
@@ -1626,9 +1635,18 @@ async function start() {
             log.info({ mode }, "Standalone mode: setting up template and dev server");
             PROJECT_DIR = await setupTemplate();
         }
-        // Register with Papercrane if requested
+        // Register with Papercrane if requested. CLI overrides for the agent /
+        // dashboards URLs are required for BYOC deployments where the default
+        // localhost/LAN fallback isn't reachable from papercrane (e.g., the
+        // agent's only ingress is a Tailscale MagicDNS hostname).
         if (cliArgs.register) {
-            const success = await registerWithPapercrane();
+            const overrides = cliArgs.agentEndpoint && cliArgs.dashboardsEndpoint
+                ? {
+                    agentEndpoint: cliArgs.agentEndpoint,
+                    previewEndpoint: cliArgs.dashboardsEndpoint,
+                }
+                : undefined;
+            const success = await registerWithPapercrane(overrides);
             if (!success) {
                 process.exit(1);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papercraneai/sandbox-agent",
-  "version": "0.1.16",
+  "version": "0.1.17-beta.1",
   "description": "Claude Agent SDK server for sandbox environments",
   "license": "MIT",
   "type": "module",