Running as a Service

Windows Services

Register the Node as a Windows service using sc.exe:

# Run from elevated PowerShell
$exe = "$env:LOCALAPPDATA\SophonNode\sophon-node.exe"
sc.exe create SophonNode binPath= "`"$exe`" start --service" start= auto DisplayName= "Sophon Node"
sc.exe description SophonNode "Sophon desktop automation agent — connects to the Sophon Gateway to execute commands."
sc.exe start SophonNode

Managing the service

sc.exe query SophonNode     # running / stopped
sc.exe start SophonNode
sc.exe stop SophonNode
sc.exe delete SophonNode     # removes the service entry

Logs

When running as a service, logs still go to %USERPROFILE%\.sophon-node\logs\sophon-node-YYYYMMDD.log. The service runs under LocalSystem by default, which means %USERPROFILE% resolves to C:\Windows\System32\config\systemprofile.

For user-scoped automation, run the service under the logged-in user's account:

sc.exe config SophonNode obj= "<DOMAIN>\<user>" password= "<password>"

This lets the Node access the user's clipboard, screen, and profile — important for most automation.

Tray icon

Interactive mode (sophon-node start) shows a tray icon on Windows. Service mode runs headless. You can run both simultaneously — service handles reliability, interactive tray handles pause/resume UI — they share the same token.

systemd user service

Create ~/.config/systemd/user/sophon-node.service:

[Unit]
Description=Sophon Node
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/sophon-node start --service
Restart=on-failure
RestartSec=5s
Environment=DISPLAY=:0

[Install]
WantedBy=default.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable sophon-node
systemctl --user start sophon-node

Managing

systemctl --user status sophon-node
systemctl --user restart sophon-node
systemctl --user stop sophon-node
journalctl --user -u sophon-node -f     # follow logs

Lingering

By default, user services only run while the user is logged in. To keep the Node running across logouts:

sudo loginctl enable-linger $USER

Wayland vs X11

• X11 — set Environment=DISPLAY=:0 in the unit file (as above). Make sure xhost +SI:localuser:$USER is set if running under a different user.
• Wayland — ydotool needs its own service. Install and enable ydotool.service before starting Sophon Node. Some Wayland compositors restrict input automation entirely; if commands silently fail, check the compositor's input-method policy.

System-wide service

If you want the Node to run without a logged-in user (rare — most automation needs user session access), create /etc/systemd/system/sophon-node.service instead and run systemctl enable sophon-node. You'll need to manually configure DISPLAY / screen sessions for GUI commands to work.

launchd user agent

Create ~/Library/LaunchAgents/ai.sophon.node.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTD/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.sophon.node</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/sophon-node</string>
        <string>start</string>
        <string>--service</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/you/.sophon-node/logs/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/you/.sophon-node/logs/stderr.log</string>
</dict>
</plist>

Load and start:

launchctl load ~/Library/LaunchAgents/ai.sophon.node.plist
launchctl start ai.sophon.node

Managing

launchctl list | grep sophon
launchctl stop ai.sophon.node
launchctl unload ~/Library/LaunchAgents/ai.sophon.node.plist     # remove agent
tail -f ~/.sophon-node/logs/sophon-node-*.log

Accessibility permission

On first mouse/keyboard command, macOS prompts for Accessibility permission for sophon-node (via cliclick). Without this, automation commands fail silently.

Grant in System Settings → Privacy & Security → Accessibility. You may need to re-grant after updating the binary (macOS ties the permission to the exact binary signature).

Background app permissions

On macOS 13+, user agents need Login Items permission:

System Settings → General → Login Items → Allow in the Background. Toggle Sophon Node on.