Run Social Stream Ninja Headlessly

What Headless Means

Headless mode keeps SSApp's Electron windows hidden, but the source pages are still real browser windows. Linux therefore needs a virtual display such as Xvfb. This is not a small background-only chat daemon.

Headless mode does not create a public control API. A controller on another computer uses the same Social Stream session and normal WebRTC or hosted WebSocket transport as other remote-control workflows.

Before You Start

Use Ubuntu 22.04+, Debian 12+, or a similar Linux distribution.
Allow at least 2 GB of memory for a small setup and more for several source windows.
Choose a persistent profile directory for settings, sources, sessions, and browser data.
Plan a one-time desktop or VNC session for sign-ins and other private setup.

Public source URLs that do not require sign-in are the easiest to operate remotely. OAuth, CAPTCHA, passwords, cookies, and account setup still require a person.

1. Install Xvfb and the AppImage

sudo apt-get update
sudo apt-get install -y xvfb x11-utils
sudo mkdir -p /opt/socialstream
sudo mv socialstreamninja_linux_*.AppImage /opt/socialstream/socialstreamninja.AppImage
sudo chmod 755 /opt/socialstream/socialstreamninja.AppImage

Download the current Linux AppImage from the Social Stream Ninja download page. A source checkout and separate Node installation are not required.

2. Prepare the Profile and Session

Choose a persistent directory such as /var/lib/ssapp or $HOME/.local/share/ssapp-headless.
Open SSApp once through a desktop or temporary VNC connection.
Set the Social Stream session ID and optional password used by the remote controller.
Add sources and complete any platform sign-ins that need a visible human workflow.
Keep the same SSAPP_USER_DATA_DIR for every later launch.

Use SSAPP_USER_DATA_DIR, not Chromium's --user-data-dir flag.

3. Start the App Headlessly

export SSAPP_USER_DATA_DIR="$HOME/.local/share/ssapp-headless"
xvfb-run -a -s "-screen 0 1920x1080x24 -nolisten tcp -extension GLX" \
  /opt/socialstream/socialstreamninja.AppImage \
  --ssapp-headless-control --no-hwa

The --ssapp-headless-control flag hides the app windows and enables the normal remote-control bridge. The main application still needs Xvfb; --ozone-platform=headless is not a replacement for the virtual display.

4. Control It from Another Computer

Use the same Social Stream session ID and optional password on the headless app and the remote controller. WebRTC is the normal transport. If it is unsuitable for the environment, use Social Stream's hosted WebSocket server mode.

Supported remote controls can add, start, stop, restart, mute, and hide public sources. They do not remotely complete sign-in, OAuth, CAPTCHA, cookies, credentials, or other private account setup.

See Sessions, Passwords, Relay, and Server Modes when the remote controller connects but messages or commands do not arrive.

Optional Local AI on the Server

If an AI tool or automation script runs on the same Linux server as SSApp, explicitly add --ssapp-control-api:

xvfb-run -a -s "-screen 0 1920x1080x24 -nolisten tcp -extension GLX" \
  /opt/socialstream/socialstreamninja.AppImage \
  --ssapp-headless-control --ssapp-control-api --no-hwa

The API remains on 127.0.0.1:17777. Do not forward or publish it for remote users. Follow the Local Control API and MCP guide to register the downloaded AppImage with a compatible AI client.

Keep It Running with systemd

[Unit]
Description=Social Stream Ninja (headless)
After=network-online.target

[Service]
Type=simple
User=ssapp
WorkingDirectory=/opt/socialstream
Environment=SSAPP_USER_DATA_DIR=/var/lib/ssapp
ExecStart=/usr/bin/xvfb-run -a -s "-screen 0 1920x1080x24 -nolisten tcp -extension GLX" /opt/socialstream/socialstreamninja.AppImage --ssapp-headless-control --no-hwa
Restart=on-failure
RestartSec=10
KillSignal=SIGTERM
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now ssapp
journalctl -u ssapp -f

Save the unit as /etc/systemd/system/ssapp.service. Create the ssapp user and profile directory with permissions appropriate for that account before starting it.

Troubleshooting

Problem	What To Check
`Missing X server or $DISPLAY`	Launch through `xvfb-run` or start Xvfb and set `DISPLAY`.
Xvfb exits immediately	Keep `-extension GLX` in the Xvfb arguments; some installed GPU drivers break its GLX startup.
The AppImage will not mount	Install `libfuse2` or extract the AppImage and run its extracted executable.
Remote commands do not arrive	Confirm both sides use the same session and password and that WebRTC or the hosted WebSocket mode is connected.
Sources or settings mix between instances	Give every instance a different `SSAPP_USER_DATA_DIR` and virtual display.