@sharnix/agent 1.0.5 → 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/package.json

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