@sharnix/agent 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,82 @@
+# @sharnix/agent
+
+Instantly share your local app with anyone — no config, no port forwarding, no deployment.
+
+```bash
+SHARNIX_API_KEY=shx_... 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 — 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
+
+## Requirements
+
+- Node.js 18 or later
+- A free Sharnix account at [relay.sharnix.com](https://relay.sharnix.com)
+- An API key from **Settings → API Keys**
+
+## Usage
+
+```bash
+# Tunnel port 3000
+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"
+```
+
+Set the key in your shell profile so you don't repeat it:
+
+```bash
+# ~/.bashrc or ~/.zshrc
+export SHARNIX_API_KEY=shx_...
+```
+
+Then just:
+
+```bash
+npx @sharnix/agent --port 3000
+```
+
+## Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--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 |
+| `--help`, `-h` | — | Show help |
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `SHARNIX_API_KEY` | Your API key (required) |
+| `SHARNIX_URL` | Override relay URL (default: `https://relay.sharnix.com`) |
+
+## Creating share links
+
+Once the agent is running, create share links from:
+
+- **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
+
+## License
+
+MIT

package/index.js

@@ -23,6 +23,7 @@ const has = (flag) => args.includes(flag);
 const port = parseInt(get('--port') || get('-p') || '3000', 10);
 const label = get('--label') || get('-l') || null;
 const agentName = get('--name') || 'local-dev';
+const shareOnStart = has('--share');
 
 if (has('--help') || has('-h')) {
   console.log(`
@@ -36,6 +37,7 @@ if (has('--help') || has('-h')) {
     --port, -p <n>    Local port to forward (default: 3000)
     --label, -l <s>   Human-readable label for this tunnel
     --name <s>        Agent name used on first setup (default: local-dev)
+    --share           Create a read-only share link on connect and print the URL
     --help, -h        Show this message
 
   Environment:
@@ -145,6 +147,7 @@ function connect() {
     console.log(`    Dashboard  → relay.sharnix.com/app/tunnels/${tunnelId}`);
     console.log(`    MCP agent  → "create a share link for my tunnel"\n`);
     console.log(`  Press Ctrl+C to disconnect.\n`);
+    if (shareOnStart) await createShareLink();
   });
 
   ws.on('message', async (data) => {
@@ -166,6 +169,22 @@ function connect() {
   });
 }
 
+async function createShareLink() {
+  try {
+    const orgs = await api('GET', '/api/v1/orgs');
+    if (!orgs.length) return;
+    const orgSlug = creds.orgSlug || orgs[0].slug;
+    const result = await api('POST', `/api/v1/orgs/${orgSlug}/tunnels/${tunnelId}/links`, {
+      permission: 'read-only',
+      label: label || 'Shared via agent',
+    });
+    console.log(`  Share link  : ${result.url}`);
+    console.log(`  Permission  : read-only\n`);
+  } catch (err) {
+    console.error(`  Could not create share link: ${err.message}`);
+  }
+}
+
 function startHeartbeat() {
   clearInterval(heartbeatTimer);
   heartbeatTimer = setInterval(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sharnix/agent",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Tunnel your local app through Sharnix — share previews with one command",
   "keywords": ["tunnel", "preview", "sharing", "localhost", "sharnix"],
   "homepage": "https://relay.sharnix.com",