Skip to content

Headless Mode

Jump to bottom
siganberg edited this page Mar 18, 2026 · 7 revisions

Headless Mode

Run ncSender as a network server without the desktop UI — access it from any browser on your network.

Quick Start

1. Find the Server Binary

The server is bundled inside the installed application:

Platform Path
macOS /Applications/ncSender.app/Contents/Resources/server/NcSender.Server
Windows C:\Program Files\ncSender\resources\server\NcSender.Server.exe
Linux /opt/ncSender/resources/server/NcSender.Server

2. Run It

macOS:

/Applications/ncSender.app/Contents/Resources/server/NcSender.Server

Windows:

"C:\Program Files\ncSender\resources\server\NcSender.Server.exe"

Linux:

/opt/ncSender/resources/server/NcSender.Server

3. Open in Browser

Navigate to http://<host-ip>:8090 from any device on the same network.

To find your host IP:

  • Windows: ipconfig (look for IPv4 Address)
  • macOS: ifconfig | grep "inet "
  • Linux: hostname -I

Custom Port

# macOS / Linux
PORT=9000 /opt/ncSender/resources/server/NcSender.Server

# Windows
set PORT=9000
"C:\Program Files\ncSender\resources\server\NcSender.Server.exe"

Enable Remote Control

Remote control must be enabled in settings.json for the headless server to accept browser connections. Open (or create) the settings file and add:

{
  "remoteControl": {
    "enabled": true
  }
}

Settings file location:

Platform Path
macOS ~/Library/Application Support/ncSender/settings.json
Windows %APPDATA%/ncSender/settings.json
Linux ~/.config/ncSender/settings.json

Tip: If you've previously run ncSender with the desktop UI, settings.json already exists. Just ensure the remoteControl.enabled field is set to true.

Auto-Start on Boot

Linux (systemd)

Create /etc/systemd/system/ncsender.service:

[Unit]
Description=ncSender Server
After=network.target

[Service]
Type=simple
User=youruser
ExecStart=/opt/ncSender/resources/server/NcSender.Server
WorkingDirectory=/opt/ncSender/resources/server
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable ncsender
sudo systemctl start ncsender

macOS (Launch Agent)

Create ~/Library/LaunchAgents/com.ncsender.server.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.ncsender.server</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Applications/ncSender.app/Contents/Resources/server/NcSender.Server</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
launchctl load ~/Library/LaunchAgents/com.ncsender.server.plist

Windows (Task Scheduler)

schtasks /create /tn "ncSender Server" /tr "\"C:\Program Files\ncSender\resources\server\NcSender.Server.exe\"" /sc onstart /ru SYSTEM

Or use Task Scheduler GUI: Create Basic Task > trigger "When the computer starts" > action "Start a program" > point to the server exe.

Firewall

If you can't connect from another device, allow port 8090 through your firewall:

  • Windows: Windows Defender Firewall > Allow an app > add port 8090
  • macOS: System Preferences > Security & Privacy > Firewall > allow incoming connections
  • Linux: sudo ufw allow 8090/tcp

Stopping the Server

  • Press Ctrl+C in the terminal window
  • Or kill the process: pkill NcSender.Server (macOS/Linux) / taskkill /IM NcSender.Server.exe /F (Windows)

Related Topics

Clone this wiki locally