@sharnix/agent 1.0.6 → 1.0.7

package/README.md

@@ -2,47 +2,48 @@
 
 Instantly share your local app with anyone — no config, no port forwarding, no deployment.
 
-## First-time setup (one command)
+## Usage
 
 ```bash
-npx @sharnix/agent setup
+npx @sharnix/agent --port 3000
 ```
 
-This is all a new user needs to run. It will:
+That's it. If this is your first time on this machine, the CLI will handle setup automatically — no separate setup step needed.
+
+## First-time setup (automatic)
 
-1. Open your browser to relay.sharnix.com — sign in if you haven't already
-2. Click **"Authorize & create key"** — one click
-3. The CLI captures your API key automatically
-4. Writes the MCP config to Claude Desktop, Cursor, and Windsurf automatically (whichever are installed)
-5. Prints your key and tells you to restart your editor
+When no key is found, the CLI starts a one-time device flow:
 
-After that, your AI agent has full MCP access and you can start tunneling.
+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
+
+**Every run after that is silent** — the CLI reads the saved key and connects with no prompts.
 
 ## Tunneling your app
 
 ```bash
+# Tunnel port 3000 (key read from ~/.sharnix/key.json or env)
 npx @sharnix/agent --port 3000
-```
 
-The API key is read from `SHARNIX_API_KEY` in your environment, or saved automatically by `setup`.
-
-```bash
-# Tunnel port 3000
+# Pass key explicitly
 SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000
 
-# Tunnel and immediately print a share link (no dashboard needed)
-SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000 --share
-
 # With a label
-SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 8080 --label "staging"
+npx @sharnix/agent --port 8080 --label "staging"
 ```
 
-Save the key to 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:
+
+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)
 
 ## What it does
 
@@ -57,35 +58,22 @@ export SHARNIX_API_KEY=shx_...
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `setup` | — | First-time setup: creates API key and writes MCP config automatically |
 | `--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 |
-| `--share` | — | Create a read-only share link on connect and print the URL |
+| `--name` | `local-dev` | Agent name registered on first setup |
 | `--help`, `-h` | — | Show help |
 
 ## Environment variables
 
 | Variable | Description |
 |----------|-------------|
-| `SHARNIX_API_KEY` | Your API key — set automatically by `setup`, or from Settings |
+| `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`) |
 
-## What setup writes automatically
-
-`npx @sharnix/agent setup` detects which editors are installed and writes the MCP config to:
-
-| 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` |
-
-It merges into the existing config — it will never overwrite other MCP servers you have configured.
+## MCP config for AI editors
 
-The block it writes looks like this:
+To give your AI agent (Claude Desktop, Cursor, Windsurf) MCP access to Sharnix, add this to your editor's config file and restart:
 
 ```json
 {
@@ -101,11 +89,18 @@ The block it writes looks like this:
 }
 ```
 
+| 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:
 
-- **Terminal** — `npx @sharnix/agent --port 3000 --share` prints a URL immediately
 - **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)
 
@@ -113,11 +108,12 @@ Share links support permissions (`read-only`, `full`), expiry dates, email restr
 
 ## How it works
 
-1. `setup` creates an API key via browser auth and writes MCP config to your editors
-2. On first tunnel run, agent credentials (`agentId` + `secret`) are auto-provisioned via the API and saved to `~/.sharnix/agent.json`
-3. A stable tunnel ID is generated per working directory and saved to `~/.sharnix/tunnel-<hash>.json`
-4. The agent opens a WebSocket to the relay and registers the tunnel
-5. 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.6",
+  "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"
   }