@sourapp/station

A long-running terminal app that turns any computer into a SourApp station — register the machine, receive print jobs, and keep your workspace connected to physical hardware in the room.

@sourapp/station is the official terminal client for SourApp. It pairs with your account via a browser approval flow and then runs as a background service handling print jobs sent from the SourApp dashboard.

 ● SOUR  ·  STATION                                          v0.1.0
─────────────────────────────────────────────────────────────────────

 Bench-Pi  ·  SOUR-0001

 connection: ● online   ·   printers: 2   ·   service: running

 recent jobs
   13:42:01  ✓ Customer receipt #4821
   13:38:55  ✓ Repair label — SOUR-7341-D1
   13:35:12  ✓ Estimate quote

 press q to quit

Install

npm install --global @sourapp/station

Requires Node.js 20 or newer.

Quick start

sourapp-station

The first time you run this, the TUI prints a short verification code and opens your browser to the approval page. A workspace admin signs in, confirms the machine's identity, and approves the pairing. The TUI then drops into its live status screen and starts handling print jobs.

Commands

sourapp-station                # Interactive TUI (default)
sourapp-station login          # Pair this machine without opening the TUI
sourapp-station logout         # Revoke this station and forget the pairing
sourapp-station status         # Print current state as JSON (good for scripts)
sourapp-station daemon         # Run the headless service loop with no UI

sourapp-station service install    # Register the station to launch at user logon / boot
sourapp-station service uninstall  # Remove the autostart registration
sourapp-station service status     # Show whether the background service is running

Running on boot

sourapp-station service install registers the station to start automatically the next time you log in (or boot, on Linux). Under the hood:

• macOS: writes a launch agent at ~/Library/LaunchAgents/com.sourapp.station.plist
• Linux: writes a systemd user unit at ~/.config/systemd/user/sourapp-station.service
• Windows: creates a scheduled task triggered at user logon

On Linux, the installer also reminds you to enable user lingering (sudo loginctl enable-linger $USER) so the service survives logout and reboot — needed only for headless machines without a graphical login session.

To uninstall: sourapp-station service uninstall.

Authentication & security

Pairing uses a one-time, device-code style flow: the TUI never asks for a password and never receives your user credentials. After approval, SourApp issues the machine a station-scoped token with a narrow set of capabilities:

• Send heartbeats and report online status
• Receive and execute print jobs
• Report the station's identity and attached printers
• Read its own configuration

It cannot read or modify tickets, customers, inventory, other stations, or act as a user — even if the machine is compromised. The full capability list is shown to the approver at pairing time.

The refresh token is stored in your operating system's keychain (Keychain on macOS, Credential Vault on Windows, Secret Service on Linux), falling back to a file with 0600 permissions if no keychain is available. Access tokens live only in memory and rotate hourly.

To revoke a station: run sourapp-station logout on the machine, or remove it from Settings → Stations in the SourApp dashboard.

Printers

The station discovers printers automatically from your operating system (lpstat -p on macOS/Linux, Get-Printer on Windows) and reports them to the dashboard. You assign roles (receipt, label, etc.) from the dashboard's Stations page.

When a user sends a print job in SourApp, it's routed to the correct station, executed locally via lp (macOS/Linux) or PowerShell (Windows), and reported back as done or failed.

The station refreshes its list of attached printers every 5 minutes, so plugging in a new printer is picked up automatically without restarting.

Files & logs

| What | Location (macOS / Linux / Windows) | | ------------------- | ----------------------------------------------------------------------------- | | Station record | ~/Library/Application Support/sourapp-station/station.json ~/.config/sourapp-station/station.json %APPDATA%\sourapp-station\station.json | | Refresh token | OS keychain entry sourapp-station / refresh-token(or tokens.json in the config dir if no keychain available) | | Logs | ~/Library/Logs/sourapp-station/station.log ~/.local/state/sourapp-station/station.log %LOCALAPPDATA%\sourapp-station\station.log |

Run sourapp-station status for a JSON dump of the current state, including the resolved log path.

Troubleshooting

The TUI shows the verification URL but the browser doesn't open. Common on headless boxes and SSH sessions. Copy the URL from the TUI and open it on any device — your phone works fine. The code is the same regardless of which browser approves.

Connection stays "offline". Check that the network can reach https://api.sour.systems. Then check the log file for the specific error.

Print job stays queued. Run sourapp-station status to confirm the station is online and registered with the printer assigned to that job. From the SourApp dashboard, the Stations page will also show the same status.

Station was revoked from the dashboard. The daemon will exit cleanly on the next refresh. Run sourapp-station again to pair fresh.

The service won't survive a reboot on a headless Linux server. Run sudo loginctl enable-linger $USER once.

Support

• Documentation: https://sour.systems/docs/stations
• Issues & feature requests: contact your SourApp account team

License

MIT