@sharnix/agent

Instantly share your local app with anyone — no config, no port forwarding, no deployment.

Usage

npx @sharnix/agent --port 3000

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)

When no key is found, the CLI starts a one-time device flow:

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

# 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

# With a label
npx @sharnix/agent --port 8080 --label "staging"

# Create a full-access share link on connect
npx @sharnix/agent --port 3000 --share --permission full

When --share creates a link in an interactive terminal, the CLI opens a small local browser page with a QR code and a clickable preview URL. Use --no-qr to print only the URL without opening that page. --qr-large is kept for old scripts but no longer changes the QR display.

Background service

Sharnix can install a current-user background service that keeps the tunnel agent running after the terminal closes. It does not start your dev server — run both for a live preview.

cd my-app
sharnix service install
sharnix service start
sharnix service logs --follow

Windows uses Task Scheduler, Linux uses a systemd user service (stable in 1.1.10+), and macOS uses a LaunchAgent. All three run as your current user so they can read your existing ~/.sharnix/key.json and per-project tunnel cache.

The service uses the same ~/.sharnix/key.json and stable per-project tunnel cache as the foreground CLI. It will not start device-flow setup in the background; run sharnix setup first if the key is missing.

On Linux desktop, the systemd user service auto-starts when you log back in. Your app (npm run dev, etc.) must be started separately. In SSH or headless sessions, Sharnix warns when loginctl enable-linger <user> may be needed to survive logout.

If Windows denies creation of an at-logon Task Scheduler task, Sharnix registers a current-user Run-at-login entry instead (@sharnix/agent 1.1.11+). The tunnel agent then auto-starts after reboot. On older versions or rare setups without either trigger, run sharnix service start after login.

On Linux, Sharnix writes ~/.config/systemd/user/sharnix-<project>.service, runs systemctl --user daemon-reload, and enables the unit.

On macOS, Sharnix writes ~/Library/LaunchAgents/com.sharnix.<project>.plist and manages it with launchctl.

Useful commands:

sharnix service status
sharnix service status --json
sharnix service stop
sharnix service restart
sharnix service uninstall

Run service status from the project directory (or pass --cwd).

Troubleshooting:

• Missing key: run sharnix setup in a terminal, then sharnix service restart.
• Preview 503 but service running: start your dev server on the configured port first.
• Duplicate tunnel owner: stop either the foreground agent or the background service before starting the other. Use --force only when intentionally replacing the active owner.
• Offline or stale tunnel: run sharnix service status, then inspect sharnix service logs --follow.
• Linux systemd logs: run sharnix service logs --journal --follow.
• Moved package files: reinstall with sharnix service install --force.
• WebSocket failures: ensure .sharnix.yaml marks the matching path with upgrade: websocket.

Key resolution order

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

@sharnix/agent opens a secure tunnel from 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 | |------|---------|-------------| | --port, -p | 3000 | Local port to forward | | --label, -l | — | Human-readable label for this tunnel | | --share | — | Create a share link on connect and print the URL | | --permission | read-only | Permission for --share: read-only, full, or blocked | | --no-qr | — | Do not open the browser QR page for --share links | | --qr-large | — | Deprecated; QR now opens in a browser page | | --name | local-dev | Agent name registered on first setup | | --help, -h | — | Show help |

Environment variables

| Variable | Description | |----------|-------------| | 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:

{
  "mcpServers": {
    "sharnix": {
      "command": "npx",
      "args": ["-y", "@sharnix/mcp-server@latest"],
      "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
• Dashboard — relay.sharnix.com/app

Share links support permissions (read-only, full), expiry dates, email restrictions, and one-time view mode.

For a quick link directly from the CLI, run npx @sharnix/agent --port 3000 --share. Add --permission full when the visitor should be able to mutate the preview.

How it works

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

MIT