nsyte — Decentralized Static Site Deployment

nsyte is a Deno-based CLI that publishes static websites to the Nostr network using Blossom servers for file storage. Sites are content-addressed (SHA-256), censorship-resistant, and discoverable via Nostr relays.

Key concepts: For Nostr/Blossom domain knowledge (relays, pubkeys, nsec, NIP-46, events), see references/nostr-concepts.md.

Installation

Check if installed

nsyte --version

If this prints a version string, skip to Project Setup.

Linux / macOS (recommended — no Deno required)

curl -fsSL https://nsyte.run/get/install.sh | bash

Installs to /usr/local/bin/nsyte. Use sudo if that directory is not writable.

Linux / macOS (alternative — requires Deno 2.x)

deno install -A -f -g -n nsyte jsr:@nsyte/cli

Windows

Download the latest binary from https://github.com/sandwichfarm/nsyte/releases, place in %USERPROFILE%\bin\, and add that directory to PATH.

Troubleshooting installation

• Command not found: Add /usr/local/bin to PATH in ~/.bashrc or ~/.zshrc and reload.
• Permission denied: Use sudo for the curl install, or install to a user-writable location.
• Deno version too old: Run deno upgrade or use the binary install instead.

Project Setup

cd /path/to/your/project
nsyte init

Interactive prompts ask for:

1. Auth method — generate new key, enter existing nsec/hex key, or connect NIP-46 bunker
2. Relay URLs — one or more wss:// relay WebSocket URLs
3. Blossom server URLs — one or more https:// Blossom server URLs

On success, creates .nsite/config.json. See Configuration for the schema.

Configuration

Config file: .nsite/config.json

For the full JSON Schema, see assets/config.schema.json.

Required fields

Authentication

Site identity

Publishing flags (root sites only — id must be null/empty)

Optional objects

Example configs

Minimal (root site):

{
  "relays": ["wss://relay.damus.io", "wss://nos.lol"],
  "servers": ["https://cdn.hzrd149.com"]
}

Named site (blog):

{
  "relays": ["wss://relay.damus.io"],
  "servers": ["https://cdn.hzrd149.com"],
  "id": "blog",
  "title": "My Blog",
  "description": "A blog about decentralized applications"
}

With profile publishing:

{
  "relays": ["wss://relay.damus.io", "wss://nos.lol"],
  "servers": ["https://cdn.hzrd149.com"],
  "publishProfile": true,
  "publishRelayList": true,
  "publishServerList": true,
  "profile": {
    "name": "Alice",
    "display_name": "Alice",
    "about": "Decentralization enthusiast",
    "picture": "https://example.com/avatar.jpg",
    "nip05": "alice@example.com",
    "lud16": "alice@getalby.com"
  }
}

With NIP-89 app handler:

{
  "relays": ["wss://relay.damus.io"],
  "servers": ["https://cdn.hzrd149.com"],
  "publishAppHandler": true,
  "appHandler": {
    "kinds": [1, 30023],
    "name": "My Nostr Viewer",
    "description": "A viewer for notes and articles",
    "icon": "https://example.com/logo.png"
  }
}

Interactive config editor

nsyte config

Requires an interactive terminal. Keys: ↑/↓ navigate, Enter edit, s save, r reset, q quit.

For non-interactive contexts, edit .nsite/config.json directly and validate:

nsyte validate

Authentication

NIP-46 Bunker (recommended)

Connect via QR code

nsyte bunker connect

Choose “Scan QR Code”, enter a relay URL, scan with signer app (Amber, nsec.app), approve.

Connect via bunker URL

nsyte bunker connect 'bunker://pubkey?relay=wss://relay.example.com&secret=xxx'

CRITICAL: Always single-quote the URL — ? and & are shell metacharacters.

Link bunker to project

nsyte bunker use [pubkey]

Sets bunkerPubkey in config and stores nbunksec in OS keychain. Never manually edit bunkerPubkey.

Bunker management commands

Secrets storage

nsyte auto-selects the best backend:

1. macOS: Keychain
2. Linux: Secret Service (fallback: encrypted file)
3. Windows: Credential Manager (fallback: encrypted file)

Override with NSYTE_FORCE_ENCRYPTED_STORAGE=true.

Deployment

Basic deploy

nsyte deploy ./dist

Auth resolution order

1. --sec flag (highest priority):

   nsyte deploy ./dist --sec "nsec1..."
   nsyte deploy ./dist --sec "${NBUNK_SECRET}"
   

   Auto-detects format: nsec1..., nbunksec1..., bunker://..., or 64-char hex.

2. Stored bunker from .nsite/config.json bunkerPubkey + OS keychain.

3. If neither available, nsyte exits with an error.

Common flags

Interpreting output

• Full success: {N} files uploaded successfully ({size}) — all files to all servers
• Partial success: {uploaded}/{total} files uploaded — some servers failed
• Total failure: Failed to upload any files — check relay/server/auth errors

Gateway URL printed after deploy: https://{npub}.nsite.lol/

CI/CD

Step 1: Generate CI credential (one-time, on dev machine)

nsyte ci
# or with bunker URL:
nsyte ci 'bunker://pubkey?relay=wss://relay.example.com&secret=xxx'

The nbunksec1... string is printed once and never stored. Copy it immediately and save as a CI secret.

Step 2: Deploy in pipeline

nsyte deploy ./dist --non-interactive --sec "${NBUNK_SECRET}"

CRITICAL: Use --sec (not --nbunksec).

GitHub Actions example

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: denoland/setup-deno@v1
      - run: nsyte deploy ./dist --non-interactive --sec "${{ secrets.NBUNK_SECRET }}"

CI checklist

• .nsite/config.json committed or provided as artifact
• NBUNK_SECRET secret set to nbunksec1... string
• --non-interactive flag present
• Optionally run nsyte validate before deploy

Other Commands

Troubleshooting

Auth errors

• “No valid signing method”: Provide --sec or configure bunker via nsyte bunker use.
• “No stored credential”: bunkerPubkey set in config but keychain entry missing. Fix: nsyte bunker use [pubkey].
• Bunker URL rejected: Shell ate metacharacters. Use single quotes: 'bunker://...'.

Deploy errors

• Relay issues: Check relays array in config has valid wss:// URLs. Try --use-fallback-relays.
• Blossom server rejection: Check servers array. Try adding a different server via nsyte config.
• Config missing: Run nsyte init first.

Config errors

• “Config editor requires interactive terminal”: Edit JSON directly + nsyte validate.
• Validation fails: Common causes: malformed URLs, publishAppHandler: true without appHandler.kinds, publish* on named site.
• bunkerPubkey format: Must be 64 hex chars, not npub. Always use nsyte bunker use.