Sharnix Reference

Overview

The core flow is three objects working together:

• Agent — the @sharnix/agent process running on your machine. It keeps the tunnel connection alive.
• Tunnel — the persistent channel between your local port and the relay. Has a stable ID and optional permanent subdomain.
• Share link — a scoped URL you hand to a viewer. Each link has its own permission level, expiry, and access rules.

localhost:3000  →  @sharnix/agent  →  relay.sharnix.com  →  https://relay.sharnix.com/p/abc123?t=TOKEN

Quick start

The normal foreground CLI flow is:

1. Start your local app.
2. Run the Sharnix agent.
3. Copy the public URL or scan the compact QR code.
4. Share it with a client, tester, teammate, or phone.

# 1. Start your app
npm run dev

# 2. Share a single-port app
npx @sharnix/agent --port 3000 --share

# 3. Multi-port apps
# Add .sharnix.yaml, then run the agent from that project.

Use --port for single-port apps. Multi-port apps require a .sharnix.yaml manifest so the agent knows which local services belong to the preview.

Platform support

Share links depend on your local app and the Sharnix agent being online. If either stops, visitors see a paused/offline page and can notify the owner from that page.

Tunnels

A tunnel is a stable WebSocket connection between your local machine and the Sharnix relay. The tunnel ID is derived from a SHA-256 hash of your working directory, so restarting the agent in the same project can produce the same ID and URL.

Once connected, the relay forwards all HTTP requests that arrive at your tunnel URL through the WebSocket to your local server and proxies the response back. Viewers never see your IP address.

Permanent subdomains

By default a tunnel is accessed via its ID (relay.sharnix.com/p/abc123). You can claim a permanent subdomain — my-app.preview.sharnix.com — that stays stable forever, even if the tunnel disconnects and reconnects.

# Via CLI
npx @sharnix/agent --port 3000 --subdomain my-app

# Via MCP
claim_subdomain(tunnel_id, "my-app")

Each subdomain is globally unique across all of Sharnix. Once claimed it belongs to your org permanently.

Share links

A share link is a scoped URL that grants a specific level of access to one tunnel. You can create as many links as you want per tunnel — each with different permissions, expiry, and restrictions. Links are independent: revoking one doesn't affect others.

# URL format
https://relay.sharnix.com/p/<tunnelId>?t=<JWT>

# The JWT encodes: tunnelId, linkId, permission, label, expiry

Permissions

Every share link has one of three permission levels:

Expiry & one-time view

Links can be set to expire at a specific date and time. After expiry, the relay returns a 410 Gone response. Links can also be created as one-time view — the link burns after the first successful page load and cannot be visited again.

create_share_link(tunnel_id, "read-only",
  expires_in_hours=48,   // expires in 48 hours from now
  one_time_view=true     // burns after first visit
)

Email restrictions

You can restrict a share link to specific email addresses or entire domains without requiring viewers to log in. When a visitor tries to access a restricted link, they are prompted to enter their email address. If it matches the allowlist, they get a one-time access code via email.

This feature is available on all plans. Viewers do not need a Sharnix account.

Require viewer login Pro

When require_auth is enabled, visitors must log in with their Sharnix account before seeing the preview. Unlike email restrictions, this enforces full authentication — the visitor must have (or create) a Sharnix account.

Use this when you need a strong identity guarantee, not just an email gate. You can combine require_auth with allowed_emails to allow only specific accounts.

create_share_link(tunnel_id, "read-only",
  require_auth=true,
  allowed_emails=["@acme.com"]  // optional — restrict to company accounts
)

IP & geo allowlists Team

IP allowlists restrict access to specific IPv4/IPv6 addresses or CIDR ranges. Geo allowlists restrict access to visitors from specific countries (ISO 3166-1 alpha-2 codes). Visitors outside the allowlist receive a 403 response immediately — no explanation is shown.

Auto-suspension

When the @sharnix/agent process disconnects (Ctrl+C, crash, machine sleeps), all active share links for its tunnels are automatically paused within seconds. Visitors see a branded "Preview paused" or offline page — not a connection error — and can notify the owner from that page.

Timeline after reconnect:

• Agent reconnects → tunnel re-established immediately
• After 30 seconds of stability → reactivation email sent to org owner (Pro/Team)
• Owner or agent calls reactivate_link → link goes live again

Pro and Team plans track visits that occur while the link is paused (downtimeVisits in analytics), so you can see demand even when the preview was offline.

Analytics Pro

The get_link_stats MCP tool and GET /api/v1/orgs/:slug/links/:id/stats endpoint return visit analytics for any share link.

The period parameter accepts "1d", "7d", or "30d".

Custom domains Team

Map your own domain (e.g. previews.acme.com) to a tunnel so visitors see your domain instead of relay.sharnix.com. Add a CNAME record pointing to relay.sharnix.com and register the domain in Settings.

Custom domains work with all share link features — permissions, expiry, auth, and analytics apply normally. TLS is provisioned automatically via Let's Encrypt.

CLI reference

Install via npx — no global install required.

# Start a tunnel
npx @sharnix/agent --port 3000

# Tunnel + immediately print a share link and compact QR code
npx @sharnix/agent --port 3000 --share

# First-time setup (local machine)
npx @sharnix/agent setup

# First-time setup (remote/headless — prints URL and exits)
npx @sharnix/agent setup --print-url

MCP tools

Install the MCP server by running npx @sharnix/agent setup — it writes the config to Claude Desktop, Cursor, and Windsurf automatically. All tools accept an optional org parameter (org slug). If omitted, the first org is used.

REST API

All endpoints require Authorization: Bearer shx_... or a session cookie. Base URL: https://relay.sharnix.com