SavePoint Bridge

Connect your local printers and hardware to SavePoint.

SavePoint Bridge is a small background service that runs on your local network. It receives print jobs from SavePoint (labels, receipts) and sends them directly to your physical printers — no cloud-to-printer connection required.

Requirements

• Node.js 18+ — nodejs.org
• macOS, Linux, or Windows
• A network printer on port 9100, or a printer exposed through CUPS
• A SavePoint account with the Bridge feature enabled

Install

npm install -g @savepoint/bridge

Or run without installing:

npx @savepoint/bridge setup

Setup

The setup wizard walks you through everything in about 5 minutes.

Step 1 — Get your agent token

1. In SavePoint, go to Settings > Bridge > Add Bridge
2. Copy the token shown

Step 2 — Run setup

savepoint-bridge setup

The wizard will:

• Verify your token
• Scan your network and local CUPS queues for printers
• Install the bridge as a background service (starts automatically on login/boot)

That's it. Print a test label from Settings > Printers to confirm everything works.

Commands

savepoint-bridge setup       Guided setup wizard (start here)
savepoint-bridge start       Start the daemon manually (without installing as a service)
savepoint-bridge status      Show running state, connected printers, and recent jobs
savepoint-bridge logs        View recent activity
savepoint-bridge discover    Re-scan for printers on your network and local CUPS queues
savepoint-bridge uninstall   Remove the background service and stored token

Background Service

The setup wizard installs the bridge as an OS-level service so it starts automatically.

| OS | Service type | |----|-------------| | macOS | LaunchAgent (~/Library/LaunchAgents/com.savepoint.bridge.plist) | | Linux | systemd user unit (~/.config/systemd/user/savepoint-bridge.service) | | Windows | Scheduled Task at logon ("SavePoint Bridge") |

To stop and remove the service:

savepoint-bridge uninstall

Automation / Silent Setup

For IT teams deploying to multiple machines:

savepoint-bridge setup \
  --token=<your-agent-token> \
  --non-interactive \
  --no-service

| Flag | Description | |------|-------------| | --token=<token> | Skip the token prompt | | --non-interactive | Suppress all prompts, use defaults | | --no-service | Do not install as an OS service | | --log-level=debug | Verbose output |

What It Stores on Your Computer

| Data | Location | |------|---------| | Agent token | OS keychain (macOS Keychain, Windows Credential Manager, or gnome-keyring) | | Token fallback | ~/.savepoint-bridge/.token (AES-256 encrypted file with machine-local derived key) | | Printer registry | ~/.savepoint-bridge/registry.db | | Log files | ~/.savepoint-bridge/logs/ (7-day rolling) |

The agent token and print job content are never written to log files.

Security

• Outbound only. The bridge polls api.savepointhq.com — no inbound ports are opened, no firewall changes required.
• Tenant-scoped. The agent token only has access to print jobs and printers for your store. It cannot read orders, customers, or any non-print data.
• Revocable. Go to Settings > Bridge > Revoke at any time. The bridge stops immediately on its next poll.
• TLS always on. Certificate validation is always enforced. If your network uses an SSL-intercepting proxy, set NODE_EXTRA_CA_CERTS=/path/to/proxy-ca.crt before running the bridge.

Supported Printers

Pre-configured models

| Printer | Format | Connection | |---------|--------|-----------| | Zebra ZT230 | ZPL | Network / CUPS | | Zebra ZT410 | ZPL | Network / CUPS | | Zebra GK420d | ZPL | Network / CUPS | | Epson TM-T88 | ESC/P | Network / CUPS | | Epson TM-T20 | ESC/P | Network / CUPS | | Brother QL-820NWB | RAW | Network / CUPS |

Any printer not in this list can be added manually in Settings > Printers with a custom host/port.

Connection types

• Network — TCP socket to port 9100 (raw ZPL / ESC/P / JetDirect). Most common.
• System (CUPS) — Uses the OS print queue. macOS and Linux.

USB transport is not public in 1.0.0; use network or CUPS-backed printers for the first public release.

Troubleshooting

Bridge doesn't connect after setup

• Check that the machine running the bridge can reach api.savepointhq.com on port 443
• Run savepoint-bridge logs to see error details
• Run savepoint-bridge status to confirm the service is running

Printer not found during setup

• Make sure the printer is powered on and connected to the same network
• For network printers: verify the printer's IP is reachable (ping <printer-ip>)
• For CUPS printers: confirm the queue exists locally with lpstat -p
• You can always add a printer manually in Settings > Printers after setup

"Token verification failed"

• The token is single-use display — copy it fresh from Settings > Bridge > Add Bridge
• Check that the token is complete (64 hex characters)

SSL / certificate error

Your network may use an SSL-intercepting proxy. Run:

NODE_EXTRA_CA_CERTS=/path/to/your-proxy-ca.crt savepoint-bridge setup

Or add the certificate to your system's trust store and restart the bridge.

Linux: bridge doesn't start at boot on a headless machine

The setup wizard runs loginctl enable-linger $USER automatically. If you skipped setup or it failed, run:

loginctl enable-linger $(whoami)
systemctl --user enable --now savepoint-bridge

Logs

Logs are structured JSON written to ~/.savepoint-bridge/logs/YYYY-MM-DD.log. The logs command renders them in a human-readable format:

savepoint-bridge logs

Logs rotate automatically — only the last 7 days are kept.

Uninstall

savepoint-bridge uninstall

This removes the OS service and the stored token. It does not remove the @savepoint/bridge npm package itself — run npm uninstall -g @savepoint/bridge to remove that too.