Foreground npx @sharnix/agent is great for quick shares. Background service mode is for when you want the tunnel agent to outlive your terminal session.
The command shape
cd my-app
sharnix service install
sharnix service start
sharnix service logs --followInstall captures your project directory, manifest (or port), and writes a service config under ~/.sharnix/services/. Start launches the tunnel as your current user — not LocalSystem — so it reads the same ~/.sharnix/key.json and tunnel cache as the foreground CLI.
Two things must be running
Sharnix service mode keeps the tunnel agent alive. It does not start your dev server.
| Layer | You start with… | |-------|-----------------| | Your app (npm run dev, etc.) | Your usual workflow — or your own systemd/PM2 setup | | Sharnix tunnel | sharnix service install once, then service start |
If the Sharnix service is up but nothing is listening on your port, visitors see a paused/offline preview — even though service status shows the OS service as running.
Platform backends
| Platform | Mechanism | Status | |----------|-----------|--------| | Windows | Task Scheduler (current user) + detached runner fallback | Beta | | Linux | systemd user service in ~/.config/systemd/user/ | Stable in @sharnix/agent 1.1.10+ | | macOS | LaunchAgent in ~/Library/LaunchAgents/ | Beta |
No NSSM knowledge required. No manual unit files unless you want to inspect them.
What survives logout (Linux)
On Ubuntu desktop we verified:
- The Sharnix systemd user service auto-starts when you log back in — no manual
service start. - Your dev server does not auto-start — run
npm run dev(or your equivalent) after login. - Once the app is listening again, the tunnel reconnects and your preview subdomain works.
For SSH-only or headless Linux, enable linger when Sharnix suggests it:
loginctl enable-linger $USERService mode guarantees
- No hidden device-flow auth — run
sharnix setuponce in a terminal first. - No new share link on every restart — service mode reconnects the tunnel; it does not spam
--share. - Same stable tunnel ID as the foreground CLI for the same project folder.
- Duplicate protection — foreground and service cannot own the same tunnel without
--force. - Predictable logs —
~/.sharnix/logs/<service-id>.log
Windows caveat
Some Windows accounts deny "run at logon" task creation. Sharnix falls back to an on-demand background runner. In that mode, sharnix service start still survives terminal close, but you may need to start it again after login.
Try it
npx @sharnix/agent@1.1.10 service install --cwd .
npx @sharnix/agent service start
npx @sharnix/agent service statusSee releases for version notes.