Executar Social Stream Ninja sem interface gráfica

Ir para configuração inicial, API HTTP, MCP, Owncast e Rocket.Chat, ou verificação da captura.

Sim — use o AppImage Linux normal

Baixe o aplicativo Linux normal e torne-o executável. Em um VPS sem ambiente gráfico, iniciar apenas o AppImage não basta: use uma tela virtual e a opção --ssapp-headless-control opção. As etapas abaixo mantêm a captura de chat após você desconectar do SSH e após reiniciar o servidor.

O modo sem interface gráfica mantém ocultas as janelas Electron do SSApp, mas as páginas das fontes continuam sendo janelas reais de navegador. Por isso, o Linux precisa de uma tela virtual como Xvfb. Não se trata de um pequeno serviço de chat executado apenas em segundo plano.

O modo sem interface gráfica não cria uma API de controle pública. Um controlador em outro computador usa a mesma sessão do Social Stream e o transporte normal WebRTC ou WebSocket hospedado dos outros fluxos de controle remoto.

Antes de começar

Use Ubuntu 22.04+, Debian 12+ ou distribuição Linux semelhante.
Reserve pelo menos 2 GB de memória para uma configuração pequena e mais para várias janelas de fontes.
Escolha uma pasta de perfil persistente para configurações, fontes, sessões e dados do navegador.
Planeje uma sessão inicial de desktop ou VNC para logins e outras configurações privadas.

URLs públicas de fontes que não exigem login são as mais fáceis de operar remotamente. OAuth, CAPTCHA, senhas, cookies e configuração de contas ainda exigem uma pessoa.

1. Instale Xvfb e o AppImage

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

Baixe o AppImage Linux atual na página de download do Social Stream Ninja. Escolha o download correspondente à arquitetura do servidor (uname -m) e depois substitua YOUR_DOWNLOADED_FILE.AppImage acima pelo nome exato do arquivo. Não é necessário um checkout do código-fonte nem instalação separada do Node.

2. Prepare o perfil e faça login uma vez

Use a mesma conta e pasta de dados para a configuração e o serviço em segundo plano. Crie uma conta dedicada:

id ssapp >/dev/null 2>&1 || sudo useradd --system --create-home --home-dir /var/lib/ssapp --shell /usr/sbin/nologin ssapp
sudo install -d -o ssapp -g ssapp -m 700 /var/lib/ssapp
sudo apt-get install -y x11vnc
sudo -u ssapp Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp -extension GLX

Deixe esse terminal em execução. Em um segundo terminal SSH, abra o SSApp de forma visível nessa tela virtual:

sudo -u ssapp env DISPLAY=:99 SSAPP_USER_DATA_DIR=/var/lib/ssapp SSAPP_HEADLESS_CONTROL=0 \
  /opt/socialstream/socialstreamninja.AppImage --ozone-platform=x11 --no-hwa

Em um terceiro terminal SSH, inicie acesso VNC temporário, restrito ao próprio servidor:

sudo -u ssapp x11vnc -display :99 -localhost -rfbport 5900 -nopw -forever

No seu computador, abra um túnel SSH:

ssh -N -L 5900:127.0.0.1:5900 you@your-server

Conecte seu visualizador VNC a localhost:5900. Defina o ID de sessão do Social Stream e a senha opcional, adicione fontes e conclua os logins necessários. Ative Ativar automaticamente nas fontes que deseja iniciar quando o SSApp iniciar. Copie os links de dock de chat e sobreposição de destaque para usar depois.

Encerre o SSApp após a configuração e pare VNC, túnel e Xvfb com Ctrl+C nos respectivos terminais. Não execute a configuração e o serviço no mesmo perfil ao mesmo tempo. VNC conectado a uma instância já sem interface gráfica normalmente mostrará uma tela vazia, pois as janelas estão ocultas.

Use SSAPP_USER_DATA_DIR, não a opção do Chromium --user-data-dir. Conclua os logins no VPS; cookies do navegador copiados de outro sistema operacional podem não ser descriptografados.

3. Inicie o aplicativo sem interface gráfica

sudo -u ssapp env SSAPP_USER_DATA_DIR=/var/lib/ssapp xvfb-run -a -s "-screen 0 1920x1080x24 -nolisten tcp -extension GLX" \
  /opt/socialstream/socialstreamninja.AppImage \
  --ozone-platform=x11 --ssapp-headless-control --no-hwa

O --ssapp-headless-control mantém as janelas do aplicativo ocultas. Este comando em primeiro plano para quando você o interrompe; use o serviço systemd abaixo para operação sem supervisão. O aplicativo principal ainda precisa de Xvfb; --ozone-platform=headless não substitui a tela virtual.

4. Controle a partir de outro computador

Use o mesmo ID de sessão do Social Stream e senha opcional no aplicativo sem interface gráfica e no controlador remoto. WebRTC é o transporte normal. Se não for adequado ao ambiente, use o modo de servidor WebSocket hospedado do Social Stream.

Os controles remotos compatíveis podem adicionar, iniciar, parar, reiniciar, silenciar e ocultar fontes públicas. Eles não concluem remotamente login, OAuth, CAPTCHA, cookies, credenciais nem outras configurações privadas de conta.

Veja Sessões, senhas, relay e modos de servidor quando o controlador remoto conecta, mas mensagens ou comandos não chegam.

Mantenha em execução com systemd

Primeiro, pare o aplicativo em primeiro plano com Ctrl+C. Crie /etc/systemd/system/ssapp.service com sudo nano /etc/systemd/system/ssapp.service e cole esta unidade:

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

[Service]
Type=simple
User=ssapp
StateDirectory=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 --ozone-platform=x11 --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

O serviço usa a conta e o perfil criados na etapa 2. Inicia na inicialização do sistema e reinicia após falhas do aplicativo. Se você alterou o caminho de instalação, atualize ExecStart para corresponder.

API HTTP opcional para scripts no VPS

O modo sem interface gráfica não ativa a API de controle. Para ativá-la no serviço, execute sudo systemctl edit ssapp e salve esta substituição:

[Service]
Environment=SSAPP_CONTROL_API=1

sudo systemctl daemon-reload
sudo systemctl restart ssapp
curl -sS http://127.0.0.1:17777/api/v1/capabilities
curl -sS http://127.0.0.1:17777/api/v1/status

Para iniciar manualmente, adicione --ssapp-control-api ao comando do aplicativo. Execute os comandos a seguir em um shell SSH no VPS. A API intencionalmente não tem token e escuta apenas em 127.0.0.1; é separado do seu servidor web Owncast ou Rocket.Chat. Mantenha-o local.

Leia ssappVersion, apiVersion, e as plataformas compatíveis em capabilities primeiro. Por exemplo, se houver suporte à Twitch, adicione uma fonte (substitua CHANNEL_NAME):

curl -sS http://127.0.0.1:17777/api/v1/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"addSource","value":{"target":"twitch","username":"CHANNEL_NAME","autoActivate":true}}'

curl -sS http://127.0.0.1:17777/api/v1/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"getSources","value":{}}'

Copie o identificador estável da fonte id na lista de fontes retornada e substitua SOURCE_ID abaixo. Adicionar uma fonte a deixa inativa; autoActivate controla futuras inicializações do aplicativo.

curl -sS http://127.0.0.1:17777/api/v1/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"startSource","value":{"sourceId":"SOURCE_ID"}}'

curl -sS http://127.0.0.1:17777/api/v1/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"getSourceDiagnostics","value":{"sourceId":"SOURCE_ID"}}'

curl -sS http://127.0.0.1:17777/api/v1/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"stopSource","value":{"sourceId":"SOURCE_ID"}}'

Verifique ok e payload em cada resposta; falhas retornam error. Leia o estado após uma alteração. Se uma solicitação exceder o tempo limite, verifique o estado antes de tentar novamente. Pare uma fonte antes de alterar seus campos de conexão. Comandos de recarregamento, remoção e desligamento exigem confirm: true.

curl -N http://127.0.0.1:17777/api/v1/events acompanha o feed de Server-Sent Events até Ctrl+C. Consulte o Guia da API e MCP para a referência completa. Estes são controles do aplicativo/fontes; ações de sobreposição, como destacar uma mensagem do chat, usam o dock do Social Stream e comandos do Social Stream.

MCP opcional para um cliente de IA no VPS

O MCP permite que um cliente de IA compatível chame os controles do SSApp como ferramentas. Ative a API acima e mantenha o serviço principal do aplicativo em execução. Registre esta configuração em um cliente executado no VPS:

{
  "mcpServers": {
    "social-stream": {
      "command": "/opt/socialstream/socialstreamninja.AppImage",
      "args": ["--ssapp-mcp", "--ozone-platform=headless"],
      "env": {
        "SSAPP_CONTROL_URL": "http://127.0.0.1:17777"
      }
    }
  }
}

O local da configuração depende do cliente. Isso inicia um adaptador separado pela entrada/saída padrão; não inicia o aplicativo principal de captura. Um cliente no seu computador doméstico apontaria para o próprio localhost, e não para o VPS. Use os controles remotos normais do Social Stream a partir de outro computador.

O adaptador empacotado está disponível desde o SSApp 0.4.7; versões 0.4.14 e posteriores anunciam o conjunto completo de ferramentas mesmo antes de o aplicativo estar disponível. As capacidades em tempo real ainda determinam quais chamadas funcionam. Não é necessário instalar Node separadamente. A opção Ozone headless aqui se aplica somente ao adaptador MCP; mantenha Xvfb para o aplicativo principal.

Experimente: “Chame ssapp_get_capabilities, depois ssapp_get_status e ssapp_list_sources. Diga quais fontes estão capturando e se alguma informa erros.” As ferramentas também abrangem início/parada de fontes, diagnósticos, eventos capturados, capturas de tela e interações aprovadas com janelas do aplicativo. Logins privados e CAPTCHA ainda precisam de uma pessoa.

Veja: Guia da API de controle local e MCP para a skill opcional de agente, compatibilidade de versões e mais controles.

Owncast, Rocket.Chat e mensagens em destaque

Você pode executar o SSApp no mesmo VPS do Owncast e Rocket.Chat se houver recursos suficientes. Instalar o SSApp, por si só, não conecta o Rocket.Chat nem coloca sobreposições no vídeo.

Supported chat source → SSApp → Social Stream dock / featured overlay
                                           ↓
Video input → server broadcaster renders overlays → Owncast → viewers

Não há conector integrado de Rocket.Chat nas árvores de código-fonte verificadas para este guia. É necessária uma integração separada para trazer essas mensagens ao Social Stream. Comprove que as mensagens chegam ao dock antes de configurar a sobreposição de vídeo.

Use as URLs de dock e sobreposição de destaque copiadas durante a configuração, com a mesma sessão/senha e transporte. Selecione uma mensagem capturada no dock para destacá-la. O transmissor no servidor precisa renderizar fontes de navegador para colocar essas páginas sobre o vídeo antes de enviar a transmissão combinada ao Owncast. Consulte instruções de transmissão do Owncast. O SSApp não é esse transmissor de vídeo.

Uma sobreposição posicionada sobre um player incorporado ao seu site é outra opção: aparece naquela página, em vez de fazer parte do vídeo recebido por outros players ou gravações. O Owncast documenta incorporação de vídeo e chat.

Para desligar o computador doméstico, a fonte de vídeo, o transmissor, a captura de chat e qualquer integração com Rocket.Chat precisam continuar funcionando independentemente dele. Reserve recursos para renderização e codificação de vídeo separadamente da memória de captura de chat do SSApp.

Verifique o fluxo completo antes de deixá-lo sem supervisão

Envie uma mensagem real em um chat conectado e confirme que ela chega ao dock do Social Stream.
Destaque essa mensagem e confirme que a sobreposição de destaque muda. Para Owncast, verifique também no vídeo real visto pelo espectador.
Desconecte VNC e SSH e envie mais mensagens durante vários minutos. A captura deve continuar.
Execute sudo systemctl restart ssapp, depois confirme que a mesma sessão e as fontes retornam e que fontes ativadas automaticamente recebem mensagens novas.
Durante uma janela de manutenção, reinicie o VPS e repita a verificação de mensagens. Um processo em execução ou uma resposta bem-sucedida da API, por si só, não prova que a captura de chat funciona.

Use sudo systemctl status ssapp e sudo journalctl -u ssapp -n 100 --no-pager para o status do serviço e logs recentes. Para parar deliberadamente, use sudo systemctl stop ssapp.

Para atualizações, pare o serviço, faça backup de /var/lib/ssapp, substitua o AppImage no mesmo caminho e inicie o serviço novamente. Mantenha o executável anterior até que a nova versão passe nas verificações de mensagens.

Solução de problemas

Problema	O que verificar
`Missing X server or $DISPLAY`	Inicie por `xvfb-run` ou inicie Xvfb e defina `DISPLAY`.
Xvfb encerra imediatamente	Mantenha `-extension GLX` nos argumentos de Xvfb; alguns drivers de GPU instalados impedem sua inicialização GLX.
O AppImage não monta	Extraia com `./socialstreamninja.AppImage --appimage-extract` em uma pasta com permissão de gravação e depois coloque a pasta extraída em `/opt/socialstream/squashfs-root`. Substitua o caminho do AppImage nos comandos de configuração, serviço e MCP por `/opt/socialstream/squashfs-root/socialstreamninja`.
Comandos remotos não chegam	Confirme que os dois lados usam a mesma sessão e senha e que o WebRTC ou o modo de WebSocket hospedado está conectado.
Fontes ou configurações se misturam entre instâncias	Dê a cada instância um `SSAPP_USER_DATA_DIR` e tela virtual.