@sharnix/agent 1.0.4 → 1.0.6

package/README.md

@@ -2,80 +2,122 @@
 
 Instantly share your local app with anyone — no config, no port forwarding, no deployment.
 
+## First-time setup (one command)
+
 ```bash
-SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000
+npx @sharnix/agent setup
 ```
 
-## What it does
+This is all a new user needs to run. It will:
 
-`@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.
+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
 
-- **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
+After that, your AI agent has full MCP access and you can start tunneling.
 
-## Requirements
+## Tunneling your app
 
-- Node.js 18 or later
-- A free Sharnix account at [relay.sharnix.com](https://relay.sharnix.com)
-- An API key from **Settings → API Keys**
+```bash
+npx @sharnix/agent --port 3000
+```
 
-## Usage
+The API key is read from `SHARNIX_API_KEY` in your environment, or saved automatically by `setup`.
 
 ```bash
 # Tunnel port 3000
 SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000
 
-# Tunnel a different port with a label
+# 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"
 ```
 
-Set the key in your shell profile so you don't repeat it:
+Save the key to your shell profile so you don't repeat it:
 
 ```bash
 # ~/.bashrc or ~/.zshrc
 export SHARNIX_API_KEY=shx_...
 ```
 
-Then just:
+## What it does
 
-```bash
-npx @sharnix/agent --port 3000
-```
+`@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
 
 | 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 |
 | `--help`, `-h` | — | Show help |
 
 ## Environment variables
 
 | Variable | Description |
 |----------|-------------|
-| `SHARNIX_API_KEY` | Your API key (required) |
+| `SHARNIX_API_KEY` | Your API key — set automatically by `setup`, or from Settings |
 | `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.
+
+The block it writes looks like this:
+
+```json
+{
+  "mcpServers": {
+    "sharnix": {
+      "command": "npx",
+      "args": ["-y", "@sharnix/mcp-server"],
+      "env": {
+        "SHARNIX_API_KEY": "shx_your_key_here"
+      }
+    }
+  }
+}
+```
+
 ## 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)
-- **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. `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
 
 ## License
 

package/index.js

@@ -30,7 +30,8 @@ if (has('--help') || has('-h')) {
   sharnix — tunnel your local app through Sharnix
 
   Usage:
-    npx @sharnix/agent --port <port> [options]
+    npx @sharnix/agent setup               First-time setup (no API key needed)
+    npx @sharnix/agent --port <port>       Tunnel a local port
     SHARNIX_API_KEY=shx_... npx @sharnix/agent --port 3000
 
   Options:
@@ -41,22 +42,28 @@ if (has('--help') || has('-h')) {
     --help, -h        Show this message
 
   Environment:
-    SHARNIX_API_KEY   API key from relay.sharnix.com/app/settings (required)
+    SHARNIX_API_KEY   API key from relay.sharnix.com/app/settings
     SHARNIX_URL       Override relay base URL
 `);
   process.exit(0);
 }
 
-if (!API_KEY) {
-  console.error('\n  Error: SHARNIX_API_KEY is not set.\n');
-  console.error('  Get your key at: https://relay.sharnix.com/app/settings\n');
-  process.exit(1);
+// ── 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); });
+} else {
+  if (!API_KEY) {
+    console.error('\n  Error: SHARNIX_API_KEY is not set.');
+    console.error('  Run:  npx @sharnix/agent setup\n');
+    process.exit(1);
+  }
+  if (isNaN(port) || port < 1 || port > 65535) {
+    console.error(`\n  Error: invalid port "${get('--port') || get('-p')}"\n`);
+    process.exit(1);
+  }
+  main();
 }
 
-if (isNaN(port) || port < 1 || port > 65535) {
-  console.error(`\n  Error: invalid port "${get('--port') || get('-p')}"\n`);
-  process.exit(1);
-}
 
 // ── Config persistence ────────────────────────────────────────────────────────
 const CONFIG_DIR = path.join(os.homedir(), '.sharnix');
@@ -135,7 +142,7 @@ function connect() {
   const wsUrl = `${WS_BASE}?agentId=${encodeURIComponent(creds.agentId)}&secret=${encodeURIComponent(creds.secret)}`;
   ws = new WebSocket(wsUrl);
 
-  ws.on('open', () => {
+  ws.on('open', async () => {
     clearTimeout(reconnectTimer);
     ws.send(JSON.stringify({ type: MSG.REGISTER, tunnelId, label: label || agentName }));
     startHeartbeat();
@@ -255,9 +262,124 @@ process.on('SIGINT', () => {
   process.exit(0);
 });
 
-// ── Main ──────────────────────────────────────────────────────────────────────
-console.log(`\n  Sharnix Agent  →  localhost:${port}\n`);
+// ── Tunnel main ───────────────────────────────────────────────────────────────
+function main() {
+  console.log(`\n  Sharnix Agent  →  localhost:${port}\n`);
+  bootstrap()
+    .then((c) => { creds = c; connect(); })
+    .catch((err) => { console.error(`\n  Error: ${err.message}\n`); process.exit(1); });
+}
+
+// ── Setup: device-flow bootstrap ─────────────────────────────────────────────
+async function runSetup() {
+  const { execSync, spawn } = require('child_process');
+
+  console.log('\n  Sharnix Setup\n');
 
-bootstrap()
-  .then((c) => { creds = c; connect(); })
-  .catch((err) => { console.error(`\n  Error: ${err.message}\n`); process.exit(1); });
+  // Start device flow
+  process.stdout.write('  Starting setup…');
+  const r = await fetch(`${RELAY_BASE}/api/v1/setup-cli`, { method: 'POST' });
+  if (!r.ok) throw new Error('Could not reach relay.sharnix.com. Check your internet connection.');
+  const { code, authUrl } = await r.json();
+  process.stdout.write(' done\n\n');
+
+  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 {
+      spawn(cmd, [authUrl], { detached: true, stdio: 'ignore' });
+    }
+  } catch {}
+
+  // Poll until authorized
+  process.stdout.write('  Waiting for browser authorization');
+  let apiKey = null;
+  const deadline = Date.now() + 10 * 60 * 1000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 2000));
+    process.stdout.write('.');
+    const poll = await fetch(`${RELAY_BASE}/api/v1/setup-cli/${code}`);
+    if (!poll.ok) { process.stdout.write('\n'); throw new Error('Setup session expired.'); }
+    const data = await poll.json();
+    if (data.done) { apiKey = data.key; break; }
+  }
+  process.stdout.write('\n');
+  if (!apiKey) throw new Error('Setup timed out. Run npx @sharnix/agent setup again.');
+
+  console.log('\n  API key received!\n');
+
+  // Save key to ~/.sharnix/config.json
+  if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  saveJson(path.join(CONFIG_DIR, 'sharnix-key.json'), { apiKey, createdAt: new Date().toISOString() });
+
+  // Detect and write MCP configs
+  const mcpBlock = {
+    sharnix: {
+      command: 'npx',
+      args: ['-y', '@sharnix/mcp-server'],
+      env: { SHARNIX_API_KEY: apiKey },
+    },
+  };
+
+  const configTargets = getMcpConfigTargets();
+  const written = [];
+
+  for (const { label: editorLabel, file, wrapper } of configTargets) {
+    if (!fs.existsSync(path.dirname(file))) continue;
+    try {
+      let config = loadJson(file) || {};
+      if (wrapper === 'mcpServers') {
+        config.mcpServers = { ...(config.mcpServers || {}), ...mcpBlock };
+      } else {
+        config = { ...config, ...mcpBlock };
+      }
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(config, null, 2));
+      written.push(editorLabel);
+    } catch {}
+  }
+
+  if (written.length) {
+    console.log(`  MCP config written for: ${written.join(', ')}`);
+    console.log('  Restart your editor to pick up the changes.\n');
+  } else {
+    console.log('  Could not auto-detect an editor config. Add manually:\n');
+    console.log('  File: ~/Library/Application Support/Claude/claude_desktop_config.json');
+    console.log('       (or %APPDATA%\\Claude\\claude_desktop_config.json on Windows)\n');
+    console.log('  Content:');
+    console.log(JSON.stringify({ mcpServers: mcpBlock }, null, 2) + '\n');
+  }
+
+  console.log('  To start tunneling:');
+  console.log(`  SHARNIX_API_KEY=${apiKey} npx @sharnix/agent --port 3000\n`);
+  console.log('  Or save the key to your shell profile:');
+  console.log(`  export SHARNIX_API_KEY=${apiKey}\n`);
+  process.exit(0);
+}
+
+function getMcpConfigTargets() {
+  const home = os.homedir();
+  const appData = process.env.APPDATA || '';
+  const targets = [];
+
+  if (process.platform === 'win32') {
+    targets.push({ label: 'Claude Desktop', file: path.join(appData, 'Claude', 'claude_desktop_config.json'), wrapper: 'mcpServers' });
+    targets.push({ label: 'Cursor', file: path.join(appData, 'Cursor', 'User', 'globalStorage', 'cursor.mcp', 'mcp.json'), wrapper: 'mcpServers' });
+  } else if (process.platform === 'darwin') {
+    targets.push({ label: 'Claude Desktop', file: path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'), wrapper: 'mcpServers' });
+    targets.push({ label: 'Cursor', file: path.join(home, '.cursor', 'mcp.json'), wrapper: 'mcpServers' });
+    targets.push({ label: 'Windsurf', file: path.join(home, '.codeium', 'windsurf', 'mcp_config.json'), wrapper: 'mcpServers' });
+  } else {
+    targets.push({ label: 'Claude Desktop', file: path.join(home, '.config', 'Claude', 'claude_desktop_config.json'), wrapper: 'mcpServers' });
+    targets.push({ label: 'Cursor', file: path.join(home, '.cursor', 'mcp.json'), wrapper: 'mcpServers' });
+    targets.push({ label: 'Windsurf', file: path.join(home, '.codeium', 'windsurf', 'mcp_config.json'), wrapper: 'mcpServers' });
+  }
+
+  return targets;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sharnix/agent",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Tunnel your local app through Sharnix — share previews with one command",
   "keywords": [
     "tunnel",