Install & setup.

From bare Start9 to your first issued license, in roughly the order you’ll do it. Allow about an afternoon.

Prerequisites

• A Start9 server running StartOS 0.4.x (Server Pro, Server One, or DIY install).
• Administrative access to the StartOS dashboard.
• About 2 GB of free disk for Keysat itself; BTCPay’s requirements are larger and depend on your Bitcoin node mode.

Step 1: Install Keysat

Two ways. Either gets you to the same place.

Option A: from the Keysat marketplace (recommended)

1. In your StartOS dashboard, go to Marketplace → Add.
2. Paste https://registry.keysat.xyz as the URL.
3. Find Keysat in the marketplace listing and click Install.

Option B: sideload

1. Download keysat_x86_64.s9pk from the GitHub releases page.
2. In your StartOS dashboard, go to Sideload and drag the file in.
3. Click Install.

BTCPay Server is declared as a required dependency. If you don’t have it installed yet, StartOS will prompt you to install it as part of the same flow.

Step 2: Set your operator name

Open the Keysat service page in StartOS. Go to Actions → Set operator name. Pick a short label that identifies you as the seller, e.g. "aurora-software", "northpath", "my-name". This shows up on the public purchase pages and in the audit log.

This change is live-reloaded; you don’t need to restart the service.

Step 3: Connect BTCPay

Make sure BTCPay Server is running and has at least one store with a configured payment method (on-chain wallet or Lightning node). Without a payment method, BTCPay will reject Keysat’s invoice creation.

In Keysat’s service page, click Actions → Connect BTCPay. You’ll be redirected to BTCPay’s authorize page, where you grant Keysat the permissions it needs:

• btcpay.store.canviewstoresettings
• btcpay.store.canmodifystoresettings (to register the settle webhook)
• btcpay.store.canviewinvoices
• btcpay.store.cancreateinvoice
• btcpay.store.canmodifyinvoices

Once you confirm, BTCPay redirects back to Keysat with an API key and store id. Keysat:

1. Stores the API key and store id in its local SQLite (encrypted at rest by StartOS).
2. Registers an outbound webhook subscription on the store, pointed at Keysat’s /btcpay webhook endpoint.
3. Verifies the connection by fetching the store’s payment-method list.

Automating setup? On a sandbox daemon you can connect a non-mainnet BTCPay over the API instead of clicking, using a scoped key carrying the payment_providers:write scope. See Agent integration: Connect BTCPay programmatically.

Click Actions → Check BTCPay connection to verify the wiring. It should report:

# Expected output:
status: connected
store: YOUR_STORE_ID
webhook: registered
payment_methods: [BTC-OnChain, BTC-LightningNetwork]

If payment_methods is empty, head back to BTCPay and configure at least one before continuing.

Step 4: Get your admin API key

Go to Actions → Show admin API key. This reveals the 64-hex-character key that gates all /v1/admin/* endpoints, including the admin UI.

Step 5: Open the admin UI

Click the Launch UI button on Keysat’s service page. (StartOS surfaces this for any service that defines a type: 'ui' interface.) Paste the admin key from the previous step into the sign-in form.

From here on, you mostly work in the admin UI. The StartOS Actions tab is reserved for setup-only operations (operator name, BTCPay connect/disconnect/check, show admin key).

Step 6: Define your first product

In the admin UI, go to Products → Create a new product and fill in:

• Slug: lowercase, hyphens, will appear in the public URL. e.g. bitcoin-ticker-pro.
• Display name: shown on the buyer’s purchase page and on receipts.
• Description: one or two sentences; rendered as plain text.
• Price: the currency picker accepts sats, USD, or EUR. For sats, enter an integer (e.g. 50000). For USD/EUR, enter the amount in dollars/euros. Keysat converts to BTC at invoice creation and the buyer pays the locked-in BTC amount.

The product is created with no policies attached. Next:

Step 7: Define one or more policies

Go to Policies → Create a new policy. Pick the product, then fill in:

• Slug: lowercase id (e.g. basic, pro, annual). Not "special" in any way; the buy page renders a tier picker when a product has two or more public policies, with the initial tier chosen by ?policy=<slug> in the URL, then by the policy you mark "most popular", then by cheapest.
• Duration. Common choices: perpetual, 30 days (trial), 1 year. Recurring subscriptions are a separate toggle on the same form. Flip "Recurring subscription" + set a renewal cadence and Keysat handles the cycle (invoice → settle → re-sign) automatically.
• Max devices. 1 for single-seat, 0 for unlimited.
• Entitlements: pick from the product's catalog (you set up the catalog when you created the product on the previous step). The picked entitlements are baked into the signed license and your app reads them at verify time. Optionally toggle the "hide on buy page" eye icon on any entitlement to drop it from the tier card without un-granting it. Useful for higher tiers that use "Everything in Basic, plus:" marketing copy.
• Marketing bullets (optional): operator-authored ✓ items rendered on the tier card alongside the entitlements. Pure marketing copy, not enforced.

If you're selling a multi-tier product (e.g. Basic / Pro / Max), repeat this step for each tier. Drag the cards in the Policies grid to set the order shown to buyers.

Step 8: Share your purchase URL

Your public purchase URL is now live at:

https://<your-keysat-host>/buy/<product-slug>

Buyers hit it, see your product, click "Pay", and BTCPay’s checkout takes over. On payment confirmation, Keysat receives a webhook from BTCPay, signs a license, and emails it to the buyer (if they entered an email) and shows it on the receipt page.

Test it end-to-end by creating a free-license discount code and redeeming it: the same code path runs, just without the payment leg.

What’s next