@sharnix/agent 1.0.5 → 1.0.7

package/README.md

@@ -2,47 +2,57 @@
 
 Instantly share your local app with anyone — no config, no port forwarding, no deployment.
 
+## Usage
+
 ```bash
-SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000
+npx @sharnix/agent --port 3000
 ```
 
-## What it does
+That's it. If this is your first time on this machine, the CLI will handle setup automatically — no separate setup step needed.
 
-`@sharnix/agent` opens a secure tunnel from [relay.sharnix.com](https://relay.sharnix.com) to your local machine. Visitors access your app through a shareable link — you never expose a port publicly.
+## First-time setup (automatic)
 
-- **Stable tunnel ID** per project directory — the same tunnel URL survives restarts
-- **Auto-provisioned** — creates an agent credential on first run, stored in `~/.sharnix/`
-- **Auto-suspends** share links when you disconnect, reactivates when you reconnect
-- **Works with any framework** — Next.js, Vite, Django, Rails, anything on localhost
+When no key is found, the CLI starts a one-time device flow:
 
-## Requirements
+1. Generates a short-lived auth URL and prints it in the terminal
+2. You (or your AI agent) open the URL in any browser — phone, laptop, doesn't matter
+3. Sign in and click **"Authorize"** — one click
+4. The CLI receives your key automatically via polling — nothing to copy or paste
+5. Key saved to `~/.sharnix/key.json` for all future runs
+6. Tunnel connects immediately
 
-- Node.js 18 or later
-- A free Sharnix account at [relay.sharnix.com](https://relay.sharnix.com)
-- An API key from **Settings → API Keys**
+**Every run after that is silent** — the CLI reads the saved key and connects with no prompts.
 
-## Usage
+## Tunneling your app
 
 ```bash
-# Tunnel port 3000
+# Tunnel port 3000 (key read from ~/.sharnix/key.json or env)
+npx @sharnix/agent --port 3000
+
+# Pass key explicitly
 SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000
 
-# Tunnel a different port with a label
-SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 8080 --label "staging"
+# With a label
+npx @sharnix/agent --port 8080 --label "staging"
 ```
 
-Set the key in your shell profile so you don't repeat it:
+## Key resolution order
 
-```bash
-# ~/.bashrc or ~/.zshrc
-export SHARNIX_API_KEY=shx_...
-```
+The CLI checks for a key in this order:
 
-Then just:
+1. `SHARNIX_API_KEY` environment variable
+2. `SHARNIX_KEY` environment variable
+3. `~/.sharnix/key.json` (saved automatically after first setup)
+4. Device flow (auto-started if none of the above exist)
 
-```bash
-npx @sharnix/agent --port 3000
-```
+## What it does
+
+`@sharnix/agent` opens a secure tunnel from [relay.sharnix.com](https://relay.sharnix.com) to your local machine. Visitors access your app through a shareable link — you never expose a port publicly.
+
+- **Stable tunnel ID** per project directory — same URL survives restarts
+- **Auto-provisioned** — creates agent credentials on first run, stored in `~/.sharnix/`
+- **Auto-suspends** share links when you disconnect, reactivates when you reconnect
+- **Works with any framework** — Next.js, Vite, Django, Rails, anything on localhost
 
 ## Options
 
@@ -50,32 +60,60 @@ npx @sharnix/agent --port 3000
 |------|---------|-------------|
 | `--port`, `-p` | `3000` | Local port to forward |
 | `--label`, `-l` | — | Human-readable label for this tunnel |
-| `--name` | `local-dev` | Agent name used on first-time setup |
+| `--name` | `local-dev` | Agent name registered on first setup |
 | `--help`, `-h` | — | Show help |
 
 ## Environment variables
 
 | Variable | Description |
 |----------|-------------|
-| `SHARNIX_API_KEY` | Your API key (required) |
+| `SHARNIX_API_KEY` | API key — overrides saved key file |
+| `SHARNIX_KEY` | Alias for `SHARNIX_API_KEY` |
 | `SHARNIX_URL` | Override relay URL (default: `https://relay.sharnix.com`) |
 
+## MCP config for AI editors
+
+To give your AI agent (Claude Desktop, Cursor, Windsurf) MCP access to Sharnix, add this to your editor's config file and restart:
+
+```json
+{
+  "mcpServers": {
+    "sharnix": {
+      "command": "npx",
+      "args": ["-y", "@sharnix/mcp-server"],
+      "env": {
+        "SHARNIX_API_KEY": "shx_your_key_here"
+      }
+    }
+  }
+}
+```
+
+| Editor | Config file |
+|--------|-------------|
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+
 ## Creating share links
 
 Once the agent is running, create share links from:
 
+- **AI agent** — ask Claude/Cursor: *"share my app with the client"* via [`@sharnix/mcp-server`](https://www.npmjs.com/package/@sharnix/mcp-server)
 - **Dashboard** — [relay.sharnix.com/app](https://relay.sharnix.com/app)
-- **AI agent** — via the [`@sharnix/mcp-server`](https://www.npmjs.com/package/@sharnix/mcp-server) MCP integration
-- **API** — `POST /api/v1/orgs/:slug/tunnels/:id/links`
 
 Share links support permissions (`read-only`, `full`), expiry dates, email restrictions, and one-time view mode.
 
 ## How it works
 
-1. On first run, the agent calls the Sharnix API to create a credential pair (`agentId` + `secret`), saved to `~/.sharnix/agent.json`
-2. A stable tunnel ID is generated for the current working directory and saved to `~/.sharnix/tunnel-<hash>.json`
-3. The agent opens a WebSocket to the relay and registers the tunnel
-4. When a visitor opens a share link, the relay forwards their HTTP request over the WebSocket to your local app and streams the response back
+1. On first run with no key, the CLI starts a device flow: prints a one-time auth URL and polls for completion
+2. You open the URL in any browser, sign in, click Authorize — key is saved to `~/.sharnix/key.json` automatically
+3. Agent credentials (`agentId` + `secret`) are provisioned via the API and saved to `~/.sharnix/agent.json`
+4. A stable tunnel ID is generated per working directory and saved to `~/.sharnix/tunnel-<hash>.json`
+5. The agent opens a WebSocket to the relay and registers the tunnel
+6. When a visitor opens a share link, the relay forwards their HTTP request over the WebSocket to your local app and streams the response back
 
 ## License
 

package/index.js

@@ -12,6 +12,10 @@ const RELAY_BASE = (process.env.SHARNIX_URL || 'https://relay.sharnix.com').repl
 const WS_BASE = RELAY_BASE.replace(/^http/, 'ws');
 const API_KEY = process.env.SHARNIX_API_KEY || '';
 
+// ── Config persistence (declared early so dispatch below can rely on it) ──────
+const CONFIG_DIR = path.join(os.homedir(), '.sharnix');
+if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
+
 // ── CLI args ──────────────────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 const get = (flag) => {
@@ -30,7 +34,8 @@ if (has('--help') || has('-h')) {
   sharnix — tunnel your local app through Sharnix
 
   Usage:
-    npx @sharnix/agent setup               First-time setup (no API key needed)
+    npx @sharnix/agent setup               First-time setup on your local machine
+    npx @sharnix/agent setup --print-url   Print auth URL and exit (for remote/agent use)
     npx @sharnix/agent --port <port>       Tunnel a local port
     SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000
 
@@ -50,11 +55,13 @@ if (has('--help') || has('-h')) {
 
 // ── Setup command (device-flow bootstrap, no API key required) ────────────────
 if (args[0] === 'setup') {
-  runSetup().catch((err) => { console.error(`\n  Error: ${err.message}\n`); process.exit(1); });
+  runSetup(has('--print-url')).catch((err) => { console.error(`\n  Error: ${err.message}\n`); process.exit(1); });
 } else {
   if (!API_KEY) {
-    console.error('\n  Error: SHARNIX_API_KEY is not set.');
-    console.error('  Run:  npx @sharnix/agent setup\n');
+    console.error('\n  Error: SHARNIX_API_KEY is not set.\n');
+    console.error('  On your local machine:  npx @sharnix/agent setup');
+    console.error('  On a remote machine:    SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000');
+    console.error('\n  Get your key from relay.sharnix.com/app/settings → API Keys\n');
     process.exit(1);
   }
   if (isNaN(port) || port < 1 || port > 65535) {
@@ -65,10 +72,7 @@ if (args[0] === 'setup') {
 }
 
 
-// ── Config persistence ────────────────────────────────────────────────────────
-const CONFIG_DIR = path.join(os.homedir(), '.sharnix');
-if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
-
+// ── Config persistence helpers ────────────────────────────────────────────────
 function loadJson(file) {
   try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
 }
@@ -271,8 +275,8 @@ function main() {
 }
 
 // ── Setup: device-flow bootstrap ─────────────────────────────────────────────
-async function runSetup() {
-  const { execSync, spawn } = require('child_process');
+async function runSetup(printUrlOnly = false) {
+  const { spawn } = require('child_process');
 
   console.log('\n  Sharnix Setup\n');
 
@@ -283,16 +287,25 @@ async function runSetup() {
   const { code, authUrl } = await r.json();
   process.stdout.write(' done\n\n');
 
+  if (printUrlOnly) {
+    // Non-blocking mode for agents running on remote machines
+    console.log('  Authorization URL (open this in your browser):\n');
+    console.log(`  ${authUrl}\n`);
+    console.log('  After authorizing, run the tunnel with:');
+    console.log(`  SHARNIX_API_KEY=<your-key> npx @sharnix/agent --port 3000\n`);
+    console.log('  Your key will be shown on the authorization page after you click "Authorize".\n');
+    process.exit(0);
+  }
+
   console.log('  Opening your browser to authorize…');
   console.log(`  URL: ${authUrl}\n`);
 
   // Open browser cross-platform
   try {
-    const cmd = process.platform === 'win32' ? 'start' :
-                process.platform === 'darwin' ? 'open' : 'xdg-open';
     if (process.platform === 'win32') {
       spawn('cmd', ['/c', 'start', '', authUrl], { detached: true, stdio: 'ignore' });
     } else {
+      const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
       spawn(cmd, [authUrl], { detached: true, stdio: 'ignore' });
     }
   } catch {}

package/package.json

@@ -1,27 +1,17 @@
 {
   "name": "@sharnix/agent",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Tunnel your local app through Sharnix — share previews with one command",
-  "keywords": [
-    "tunnel",
-    "preview",
-    "sharing",
-    "localhost",
-    "sharnix"
-  ],
+  "keywords": ["tunnel", "preview", "sharing", "localhost", "sharnix"],
   "homepage": "https://relay.sharnix.com",
   "license": "MIT",
-  "engines": {
-    "node": ">=18"
-  },
+  "engines": { "node": ">=18" },
   "main": "./index.js",
   "bin": {
-    "sharnix-agent": "./index.js",
-    "sharnix": "./index.js"
+    "sharnix-agent": "index.js",
+    "sharnix": "index.js"
   },
-  "files": [
-    "index.js"
-  ],
+  "files": ["index.js"],
   "dependencies": {
     "ws": "^8.18.0"
   }