nsyte run

Alias: rn — nsyte rn is equivalent to nsyte run.

Run a resolver server that serves nsites via npub subdomains. This command starts a local server that can resolve and serve nsites using the format npub1234.localhost or similar subdomain patterns.

Usage

nsyte run [npub] [options]

Arguments

• [npub] (optional): Site identifier in one of these formats:
  • npub1... or hex pubkey — root site (kind 15128)
  • naddr1... — NIP-19 naddr pointing at a root (kind 15128) or named (kind 35128) site
  • If not provided, uses the site from .nsite/config.json (its bunkerPubkey) when present, otherwise falls back to a built-in demo site

Options

• -r, --relays <relays> — Nostr relays to query (comma-separated)
• -p, --port <port> — Port number to run the resolver on (default: 6798)
• --sec <secret> — Secret for signing (auto-detects: nsec, nbunksec, bunker://, hex)
• --prompt-sec — Prompt for the signing secret at runtime instead of --sec (keeps it out of shell history)
• -c, --cache-dir <dir> — Directory to cache files (default: /tmp/nsyte or %TEMP%\nsyte)
• --no-cache — Disable file caching entirely
• --use-fallback-relays — Include default nsyte relays for file discovery
• --use-fallback-servers — Include default blossom servers for file downloads
• --use-fallbacks — Enable both fallback relays and servers
• --no-open — Don't automatically open browser

Examples

Basic Resolver

nsyte run

Starts the resolver on http://localhost:6798. Accessing localhost redirects to a demo npub. You can access any nsite at:

• http://npub1abc123.localhost:6798
• http://npub1def456.localhost:6798

Launch Specific npub

nsyte run npub1abc123def456ghi789

Launch with naddr

nsyte run naddr1...

Launch Named Site

Named sites are addressed with their naddr1... pointer (which encodes the kind 35128 identifier):

nsyte run naddr1...

Custom Port and Cache

nsyte run -p 8080 -c /custom/cache

Disable Cache

nsyte run --no-cache

Don't Auto-Open Browser

nsyte run --no-open

Starts the resolver and when you access localhost, it will redirect to the specified npub instead of the default demo.

Custom Port

nsyte run --port 3000

Serves on port 3000 instead of the default 6798.

Custom Relays

nsyte run --relays wss://relay1.com,wss://relay2.com

Uses specific relays for discovering nsite events.

How It Works

The resolver server:

1. Subdomain Parsing: Extracts npub from subdomain (e.g., npub1abc123.local.dev)
2. Event Discovery: Fetches site manifest events (kinds 15128, 35128) from configured relays
3. File Resolution: Maps requested paths to file hashes from events
4. Blob Serving: Retrieves and serves files from blossom servers
5. Fallback Handling: Serves fallback content for client-side routing

Subdomain Format

The resolver expects npub subdomains in the format:

npub1[bech32-encoded-pubkey].[base-domain]

Examples:

• npub1abc123def456.localhost:3000
• npub1xyz789uvw012.local.dev:6798

DNS Setup for Production

For production use, you'll need to configure DNS:

Wildcard DNS

Set up a wildcard DNS record pointing to your server:

*.nsites.example.com → 1.2.3.4

Local Development

For local testing, add entries to /etc/hosts:

127.0.0.1 npub1abc123.localhost
127.0.0.1 npub1def456.localhost

Or use a service like lvh.me which resolves all subdomains to localhost.

Configuration

Relay Configuration

The resolver uses relays to discover nsite events:

# Use default relays
nsyte run

# Use specific relays
nsyte run --relays wss://relay.nsite.lol,wss://relay.damus.io

Blossom Server Configuration

Configure blossom servers via .nsite/config.json or enable defaults with --use-fallback-servers. The run command does not accept a --servers flag — the resolver reads the configured server list from your project config (or from the manifest itself when serving an arbitrary site).

# Use servers from the project config
nsyte run

# Add the default nsyte blossom servers as a fallback
nsyte run --use-fallback-servers

# Enable both relay and server fallbacks
nsyte run --use-fallbacks

Features

Automatic Discovery

• Discovers nsite events from relays automatically
• Caches event data for better performance
• Updates when new events are published

File Serving

• Serves files directly from blossom servers
• Handles content types appropriately
• Supports range requests for large files

SPA Support

• Respects fallback configuration from nsite events
• Enables client-side routing for React, Vue, etc.
• Serves index.html for unmatched routes (when configured)

Error Handling

• Returns 404 for non-existent nsites
• Handles blossom server failures gracefully
• Provides helpful error messages

Performance Considerations

Caching

The resolver caches:

• Event data from relays
• File mappings
• Blossom server responses (where appropriate)

Scaling

For production deployment:

• Use a reverse proxy (nginx, Cloudflare)
• Implement additional caching layers
• Monitor relay and blossom server performance

Reliability

• Configure multiple relays for redundancy
• Use multiple blossom servers for failover
• Implement health checks

Production Deployment

nsyte run always binds to localhost. There is no --host flag. To expose the resolver beyond localhost in production, run it behind a reverse proxy (nginx, Caddy, Cloudflare, etc.) that listens on a public interface and forwards to localhost:<port>.

Nginx Reverse Proxy

server {
    server_name *.nsites.example.com;

    location / {
        proxy_pass http://localhost:6798;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

systemd Service

[Unit]
Description=nsyte resolver
After=network.target

[Service]
Type=simple
User=nsyte
WorkingDirectory=/opt/nsyte
ExecStart=/usr/local/bin/nsyte run --port 6798
Restart=always

[Install]
WantedBy=multi-user.target

Monitoring

Health Check Endpoint

The resolver typically provides a health check endpoint:

GET /_health

Metrics

Monitor these metrics:

• Request latency
• Cache hit rates
• Relay response times
• Blossom server availability

Troubleshooting

Subdomain Not Resolving

1. Check DNS configuration
2. Verify npub format is correct
3. Ensure the nsite has published events

Files Not Loading

1. Check blossom server availability
2. Verify file hashes in events
3. Test blossom servers directly

Performance Issues

1. Check relay response times
2. Monitor blossom server latency
3. Review caching configuration

Related Commands

• nsyte serve - Serve local files for development
• nsyte deploy - Deploy files to create nsites
• nsyte debug - Debug nsite configuration and connectivity
• nsyte ls - List published nsite files

Inherits global options. See global options.