Connect an Edge machine to an app

Pairing an Edge machine connects it to your organization. Granting controls which apps in that organization may use it.

Grant the machineCopy Anchor Link

You can grant the same Edge machine to multiple apps. Removing a grant stops only that app from using it; the machine remains paired to your organization.

Pair a printer aliasCopy Anchor Link

An alias is a stable role used by the app, such as front-counter, kitchen, or customer-receipt. The alias points to a physical printer.

This lets you replace a printer later without changing app code.

If hardware is removed or the machine grant is revoked, Stardeck keeps the alias and marks it as broken. Re-pair the alias to restore the app without rebuilding it.

Customize receipt brandingCopy Anchor Link

Under Receipt Branding in the same app settings:

• upload a PNG, JPEG, or WebP logo
• review the exact black-and-white print preview
• replace or remove the current logo
• turn the Powered by Stardeck footer mark on or off

Simple, high-contrast artwork prints best. Stardeck converts the image to a one-color thermal printer format before storing it.

Test without hardwareCopy Anchor Link

Turn on a virtual printer to try printing before a real printer is installed. In the app's Settings → Integrations, find Virtual printer and select Enable virtual printer. Then pair an alias to Virtual receipt printer in Printer Pairings.

Prints from the sandbox and preview deployments land on a paper tape in that section, laid out at the printer's width, with a badge when the cash drawer would have opened. The brand logo isn't drawn. Production never sees the virtual printer, so pair a real printer to the alias before you go live.

Build an Edge feature with your agentCopy Anchor Link

Once the grant exists, describe the behavior you want to your coding agent in the app's repository:

Print a receipt on the front-counter printer after a successful cash payment,
then open the attached cash drawer.

Every app includes the Edge SDK, @stardeck-customer-apps/edge-sdk. Its SKILL.md, in node_modules/@stardeck-customer-apps/edge-sdk/, is the API reference your agent works from. Tell it which alias to use if the app has more than one printer role.

Over your organization's MCP connection, the agent can also grant a machine, pair aliases, set displays and turn on the virtual printer. Each change shows you a preview to confirm first. See Tools & Permissions.

Building in the browser instead? Give the same request to Starcat Developer in the app's Build tab.

Print from server codeCopy Anchor Link

Server-side app code uses @stardeck-customer-apps/edge-sdk. Stardeck injects the required connection settings into sandboxes and deployments, so no device secret needs to be copied into the app.

import { createEdgeClient } from "@stardeck-customer-apps/edge-sdk/server";

const edge = createEdgeClient();

await edge.print({
  alias: "front-counter",
  receipt: {
    header: { lines: ["My Shop"] },
    items: [{ name: "Coffee", quantity: 1, unitPrice: 80, total: 80 }],
    total: 80,
    footer: { lines: ["Thank you"] },
  },
  openDrawer: true,
});

print() fails if the printer is briefly offline. For a receipt that must not be lost, use enqueueReceipt(): Stardeck keeps retrying delivery for up to 10 minutes. The SDK's SKILL.md covers its rules.

Use listPeripherals() and testPrint() to build an in-app pairing screen for location staff. Handle offline and broken-binding errors by showing a retry or re-pairing action instead of a generic failure.

Control the receipt layoutCopy Anchor Link

For alignment, bold, text size, rules, spacing, or a different section order, send an ordered list of blocks instead of the fixed fields:

await edge.print({
  alias: "front-counter",
  receipt: {
    blocks: [
      { type: "text", text: "MY SHOP", align: "center", bold: true, size: "large" },
      { type: "separator" },
      { type: "items", rows: [{ name: "Coffee", quantity: 1, unitPrice: 80, total: 80 }] },
      { type: "separator" },
      { type: "columns", left: "TOTAL", right: "80.00", bold: true, size: "large" },
      { type: "barcode", format: "qr", data: "https://example.com/r/1234", widthPercent: 50 },
    ],
  },
});

Available blocks: text, columns, separator, spacer, items, and barcode. Set paperWidth on the receipt to lay out for 58mm or 80mm regardless of the printer.

A QR prints at the printer's default size unless the block sets widthPercent (5–100), the share of the paper width it should take. The printed width is quantised to whole dots per cell and rounded down, so the code lands on the nearest size at or below the request. The preview draws that size, not the request. More data means a denser symbol at the same width, so shorten a long URL rather than shrinking the code further.

Show an accurate preview in the appCopy Anchor Link

getCapabilities() reports what the target printer can do: paper width and characters per line, whether text prints as characters or as an image, Thai and Unicode coverage, supported barcodes, cutter, and cash drawer. renderReceiptPreviewHtml() lays the receipt out with the same code the printer uses, so an on-screen preview matches the paper.

import { renderReceiptPreviewHtml } from "@stardeck-customer-apps/edge-sdk";

const capabilities = await edge.getCapabilities({ alias: "front-counter" });
const html = renderReceiptPreviewHtml(receipt, capabilities, { widthPx: 320 });

Capabilities are available even when the machine is offline, so previews keep working while the hardware is down.