Monky CLI

Ferramenta de linha de comando para criar e administrar servidores Monky.

Este é o CLI do servidor, não o CLI gerado para um bot. Para empacotar e operar seu próprio bot, consulte Distribuição de bots.

monky <comando> [subcomando] [opções]

O CLI é instalado globalmente e não depende do diretório em que você está: ele mantém um registro dos servidores desta máquina em ~/.monky/servers.json e usa esse registro para saber a qual servidor cada comando se aplica.

Instalação

Requer Node.js 22 ou superior (exigência do mediasoup, usado no modo SFU).

bash

curl -fsSL https://monkyorg.github.io/install.sh | bash

Para instalar uma versão beta:

bash

curl -fsSL https://monkyorg.github.io/install.sh | bash -s -- --beta

Instalação manual (sem o script)

Baixe o .tgz da versão desejada em Releases e instale com:

bash

npm install -g --allow-scripts=mediasoup https://github.com/MonkyOrg/Monky/releases/download/vX.Y.Z/monky-cli-X.Y.Z.tgz

O --allow-scripts=mediasoup libera o postinstall do mediasoup, que compila o worker do SFU. A partir do npm 12 os scripts de instalação são bloqueados por padrão, e sem esse binário o servidor sobe mas o modo SFU não funciona: as chamadas ficam sem mídia e o cliente fica tentando reconectar até o worker subir. Em versões de npm anteriores à 11.16 o parâmetro é desnecessário e pode ser omitido.

Para rodar o servidor como daemon (monky start), o CLI usa o PM2. Se ele não estiver instalado, monky start instala automaticamente. Os demais comandos apenas avisam:

bash

npm install -g pm2

O CLI procura o PM2 como o terminal procuraria, pelo PATH, então também acha o que foi instalado pelo pnpm, pelo Yarn ou pelo Volta. Um PM2 encontrado em que pm2 --version falha não é instalado de novo por cima: o CLI avisa, e ele deve ser corrigido pela ferramenta que o instalou.

Início rápido

bash

monky create     # cria o servidor e oferece iniciá-lo
monky status     # confere se está no ar
monky logs       # acompanha os logs

Múltiplos servidores

Uma mesma máquina pode hospedar quantos servidores quiser — cada um com sua pasta de dados, sua porta e seu processo PM2 próprio.

Quando existe um único servidor, os comandos agem sobre ele diretamente. Quando existe mais de um, o CLI pergunta qual você quer usar:

Há 2 servidores Monky nesta máquina.
Qual servidor deseja reiniciar?
❯ Amigos — porta 3000 — /srv/monky-amigos
  Trabalho — porta 3100 — /srv/monky-trabalho

Em scripts e cron (terminal não interativo) a pergunta não é possível, então informe --data explicitamente:

bash

monky --data /srv/monky-amigos restart

Idioma do CLI

O primeiro comando executado em um terminal interativo pergunta English (US) ou Português (Brasil) e salva a escolha em ~/.monky/cli-config.json. monky, --help e --version não fazem essa pergunta nem salvam preferências. Comandos em scripts ou com entrada/saída redirecionada também não perguntam nem alteram o idioma salvo.

Para trocar depois, abra monky config e escolha Idioma / Language, ou use:

bash

monky config language pt-BR
monky config language en-US

Essa configuração funciona sem criar ou escolher um servidor. O menu seguinte já usa o novo idioma; identidade, banco e configuração do servidor não mudam. monky config language sem código abre a escolha em um terminal; em scripts, apenas consulta. O atalho monky --lang pt-BR|en-US continua disponível.

en-US é normalizado para en; variantes de inglês e português, incluindo pt_BR.UTF-8, usam os catálogos en e pt-BR. Um código não suportado, --lang sem valor ou uma configuração inválida gera erro, sem substituir a preferência por um padrão silencioso.

A prioridade é: --lang → MONKY_LANG → preferência salva → locale do terminal → inglês. Para detectar o locale, o CLI consulta LC_ALL, LC_MESSAGES, LANG e LANGUAGE, nessa ordem. MONKY_LANG permite que um app ou script passe o idioma escolhido sem ler nem alterar a preferência do CLI; o CLI não lê perfis do Electron.

--lang junto de um comando interativo salva a escolha. Junto de ajuda, versão ou comandos não interativos, vale somente para aquela execução. O uso isolado monky --lang <código> é uma edição explícita e salva mesmo em scripts.

Isolamento para QA: MONKY_HOME troca tanto o diretório do registro de servidores quanto o da preferência de idioma. No PowerShell, por exemplo:

powershell

$env:MONKY_HOME = Join-Path $PWD '.monky-qa'
monky --lang pt-BR
monky --help

Nesse caso, a preferência fica em .monky-qa\cli-config.json; --data continua escolhendo os dados de um servidor, não o idioma. Nomes de comandos, chaves como maxUsers e voiceMode, permissões como MANAGE_ROLES e valores como true, false, p2p e sfu não são traduzidos.

Opções globais

Opção	Descrição
`--data <pasta>`	Pasta de dados do servidor alvo. Obrigatório quando há vários servidores e o terminal não é interativo.
`--help`, `-h`	Exibe a ajuda.
`--version`, `-v`	Exibe a versão instalada.
`--lang <código>`	Seleciona `en`/`en-US` ou `pt-BR`; usado sozinho, salva a preferência.

Estrutura da pasta de dados

Caminho	Conteúdo
`server.db`	Banco SQLite: membros, cargos, canais e mensagens.
`monky.json`	Porta do servidor e proxies confiáveis.
`ecosystem.config.cjs`	Configuração do PM2, regravada a cada `start`/`restart`.
`attachments/`, `avatars/`, `icons/`	Arquivos enviados.
`server.lock`	Existe enquanto o servidor está em execução. Veja Alterações com o servidor no ar.
`backups/`	Cópias do `server.db` feitas pelo `monky update` antes de reiniciar na nova versão. Ficam as 3 mais recentes.

Códigos de saída

Código	Significado
`0`	Sucesso.
`1`	Erro. A mensagem é impressa em `stderr`.

Alterações com o servidor no ar

O servidor mantém o banco inteiro em memória e regrava o server.db a partir dessa cópia. Uma alteração gravada por fora com ele no ar some em segundos, inclusive depois de um monky restart. Por isso, os comandos que alteram dados exigem o servidor parado:

monky admin add e monky admin remove;
monky roles create, assign, unassign e delete;
monky config set, exceto as chaves port, autoUpdate e trustedProxies, que ficam fora do banco.

Com o servidor no ar, seja pelo PM2, hospedado no app ou iniciado à mão, o comando é recusado sem gravar nada e explica como seguir:

bash

monky stop
monky admin add Fulano
monky start

Com o servidor no ar, a alteração também pode ser feita pelo app. Se o servidor for iniciado enquanto um comando interativo espera uma resposta, o comando termina com erro sem salvar. Um comando que falha também não salva nada pela metade.

As consultas (monky members, monky roles e monky config show) leem uma cópia do banco e funcionam com o servidor no ar, sem regravá-lo. Depois de atualizar o CLI, elas pedem um monky restart enquanto o servidor em execução ainda não tiver carregado a versão nova.

Enquanto roda, o servidor marca a pasta de dados com o arquivo server.lock. Se ele for encerrado à força, o arquivo fica para trás e é ignorado: o CLI confere se o processo indicado ainda existe nesta máquina.

Referência de comandos

`monky create`

Cria um novo servidor: prepara o banco, define o dono e salva a porta. Substitui o antigo monky bootstrap, que continua funcionando como apelido.

bash

monky create [opções]

Após a escolha inicial de idioma, quando necessária, o comando pergunta:

Onde guardar os dados — sugere ./data, mas você pode informar qualquer caminho. Se já houver um servidor na pasta escolhida, ele pede outra.
Código de identidade do dono (MONKY-ID2:...) — exporte pelo app Monky em Configurações → Meu Perfil → Identidade. Trate o backup e a senha como credenciais: use-os somente em uma máquina de administração confiável. Códigos que começam com MONKY-ID2: precisam de um CLI atualizado; um CLI anterior a eles responde "Código de identidade inválido". Se o CLI já estava instalado, rode monky update antes do monky create (ou monky update --beta, se o app estiver no canal beta). Códigos MONKY-ID:, exportados por versões anteriores do app, continuam aceitos.
Senha da identidade — a que você definiu ao exportar. O código e a senha são conferidos antes de qualquer dado ser gravado: uma senha errada não deixa um servidor pela metade. Se o comando avisar que o código veio de uma versão mais nova do Monky, atualize o CLI com monky update e rode de novo.
Nome do servidor
Porta do servidor (padrão: 3000)
Senha do servidor — deixe vazio para um servidor aberto.
Limite de membros — pergunta se você quer um teto de cadastros. O padrão é não ter limite.
Modo de voz/vídeo — p2p ou sfu. No modo SFU, verifica portas e dependências e pergunta o upload disponível para estimar a capacidade.

Ao final, exibe um resumo, pede confirmação e oferece iniciar o servidor.

Opções

Opção	Descrição	Padrão
`--identity <código>`	Código de identidade do dono	perguntado
`--name <nome>`	Nome do servidor	`Servidor dos Amigos`
`--port <n>`	Porta do servidor, de 1024 a 65535	`3000`
`--password <senha>`	Senha do servidor (vazio = sem senha)	perguntado
`--max-users <n>`	Limite de membros cadastrados (`0` = sem limite)	perguntado
`--voice-mode <p2p\|sfu>`	Modo de voz e mídia (`p2p` ou `sfu`)	`p2p`

A senha da identidade nunca é aceita por opção: ela é sempre digitada de forma oculta no terminal.

Exemplos

bash

# Totalmente interativo
monky create

# Pasta definida por opção, o resto perguntado
monky create --data /srv/monky-amigos

# Não interativo, exceto a senha da identidade
monky create --data /srv/monky-amigos \
  --identity "MONKY-ID2:..." \
  --name "Servidor dos Amigos" --port 3000 --password "senhaDoServidor"

`monky list`

Lista os servidores desta máquina e o estado de cada um. Também aceito como monky ls.

bash

monky list

NOME       STATUS   PORTA  PASTA DE DADOS
Amigos     online   3000   /srv/monky-amigos
Trabalho   parado   3100   /srv/monky-trabalho

`monky start`

Inicia um servidor já criado, como daemon do PM2.

bash

monky start [--port <n>] [--fresh]

Se não houver nenhum servidor na máquina, o comando falha e aponta o monky create — ele nunca cria um servidor por conta própria.

Antes de subir, o arquivo ecosystem.config.cjs é regravado, então a porta e o nome atuais valem a partir daí. Ele fixa também o caminho absoluto do Node que executou o comando (veja Trocar a versão do Node).

Opções

Opção	Descrição	Padrão
`--port <n>`	Porta só para esta execução	valor de `monky.json`, ou `3000`
`--fresh`	Remove o registro do processo no PM2 e o recria do zero	desligado

Para mudar a porta de forma permanente use monky config set port.

--fresh raramente é necessário: o CLI detecta sozinho um registro desatualizado e recria o processo. Ele existe para forçar isso à mão. Os logs em ~/.pm2/logs não são apagados.

Opções removidas

--password, --max-users, --name, --voice-channel e --text-channel não são mais aceitos aqui. Eles só tinham efeito na criação do banco e eram silenciosamente ignorados em servidores já existentes. Hoje o comando falha indicando a alternativa: monky create ou monky config set.

`monky stop`

Para o servidor, mantendo-o registrado no PM2.

bash

monky stop

O processo continua listado no PM2 de propósito: removê-lo descartaria os logs justamente quando eles mais importam, logo depois de uma queda ou parada. monky logs continua funcionando com o servidor parado.

Os contadores de pessoas online (inclusive na página inicial e no monitor) excluem bots e contam uma identidade apenas uma vez, mesmo conectada em vários dispositivos. Pessoas invisíveis ainda contam para o aviso de desligamento: elas continuam conectadas e também serão desconectadas.

Se houver gente conectada no momento, o CLI avisa quantas pessoas serão desconectadas e pede confirmação antes de parar. Em terminal não interativo (scripts, cron) o aviso é exibido e a parada segue normalmente.

`monky restart`

Reinicia o servidor aplicando a configuração atual.

bash

monky restart [--port <n>] [--fresh]

O ecosystem.config.cjs é regravado antes do reinício, então uma porta ou nome alterados desde o último start passam a valer.

Assim como no stop, se houver gente conectada o CLI avisa e pede confirmação antes de reiniciar.

--fresh funciona igual ao do monky start: descarta o registro do processo no PM2 antes de subir de novo.

Se o PM2 ainda executar um arquivo de outra instalação do CLI, start e restart recriam automaticamente apenas o registro daquele servidor. Regravar o ecosystem.config.cjs não basta nesse caso: o PM2 pode conservar o caminho executado anterior. O diretório de dados e os logs são preservados; uma mudança apenas no interpretador Node continua usando o reinício normal.

As leituras do banco feitas por start, restart e status (incluindo --watch) não gravam dados nem aplicam migrações. As migrações ficam a cargo do servidor ao iniciar, depois que a instância anterior encerra, para que seu snapshot em memória não sobrescreva um schema atualizado pelo CLI.

`monky status`

Exibe o estado do servidor.

bash

monky status [--data <pasta>]

Com um único servidor (ou com --data), mostra o detalhe:

Estado do servidor: Amigos
Estado: online
Pasta de dados: /srv/monky-amigos
porta 3000
Processo PM2: monky-server-a1b2c3d4
PID: 21877
Iniciado em: 2026-08-27T18:02:11.000Z
Reinícios: 0
Memória: 88 MB
CPU: 0%
Node.js: 24.20.0

O status não repete apenas o que o PM2 diz: a porta é sondada de verdade. O PM2 informa o estado que ele pretende manter, e não um que ele verificou — um processo que falhou ao iniciar continua listado como online. Quando o que o PM2 afirma não corresponde à realidade, aparece um bloco de diagnóstico:

Diagnóstico
⚠ O PM2 está executando o servidor no Node 20.20.2, mas o Monky exige Node 22+.
  Atualize o Node, rode "monky update" para recompilar os módulos nativos e "monky restart" para aplicar.
⚠ O PM2 marca o processo como "online", mas ele não tem PID — ou seja, nunca chegou a iniciar.
  Normalmente o PM2 está tentando usar um Node que não existe mais. Rode "monky restart --fresh" para registrar o processo de novo.

Com vários servidores e sem --data, imprime a mesma tabela do monky list — uma consulta não tem efeito colateral, então não faz sentido perguntar.

O status detalhado de um servidor em execução também informa se há bots com protocolo incompatível ou ainda não verificado. Esses avisos aparecem após monky start e monky restart e orientam a atualizar ou conferir o SDK dos bots. Após iniciar ou reiniciar (inclusive depois de monky update), o CLI repete a consulta por até 10 segundos enquanto /preview não responde, encerrando a espera assim que recebe os dados. Se o prazo esgotar ou a resposta não incluir dados válidos de compatibilidade, informa que não conseguiu consultá-la; consulte novamente com monky status --data <pasta>.

O monky list e a tabela de vários servidores mantêm esses avisos junto ao servidor correspondente. No monky status --watch, o aviso é atualizado a cada ciclo e desaparece quando os bots voltam a conectar com um SDK compatível. Servidores parados não são consultados nem aparecem como incompatíveis.

Trocar a versão do Node

O PM2 roda como um daemon de vida longa e guarda o Node com que foi iniciado. Atualizar o Node não o atualiza junto, e é daí que vem a maior parte dos problemas depois de um upgrade.

O que quebra não é atualizar o Node, e sim o caminho do binário mudar ou desaparecer:

Situação	O que acontece
Upgrade no lugar (apt/NodeSource, segue em `/usr/bin/node`)	Continua funcionando: o caminho existe e passa a apontar para o Node novo
Trocar de gerenciador (apt → nvm) e remover o antigo	Quebra: o PM2 aponta para um binário que não existe mais e não consegue iniciar o processo
`nvm use` outra versão, sem remover a antiga	Silencioso: o servidor continua rodando no Node antigo

No segundo caso o PM2 mostra status: online com pid: N/A, e nada escuta na porta — o cliente reclama que "o computador está online, mas nenhum servidor Monky está ativo na porta". O monky status aponta isso no diagnóstico.

Desde a versão 8.1, o ecosystem.config.cjs fixa o caminho absoluto do Node que executou monky start, em vez de deixar o PM2 resolver node pelo ambiente do daemon. Como o arquivo é regravado a cada start e restart, ele se reajusta sozinho.

Procedimento recomendado

Depois de mudar a versão do Node:

bash

monky update     # recompila os módulos nativos para o novo ABI
monky restart    # refixa o interpretador no ecosystem
pm2 save         # grava o estado bom no dump do PM2

Use monky restart, não pm2 restart

Só o monky regrava o ecosystem.config.cjs. O pm2 restart reaproveita o registro anterior, com o interpretador antigo.

pm2 update sozinho não resolve

O pm2 update restaura os processos a partir de ~/.pm2/dump.pm2, e o dump carrega o interpretador antigo. Se o servidor não voltar, recrie o registro:

bash

monky restart --fresh

Isso descarta o processo no PM2 e o registra de novo. Os arquivos em ~/.pm2/logs são preservados.

Se o CLI atualizado mostrar a versão nova, mas as conexões ainda indicarem um protocolo antigo, confira monky status --data <pasta>. O diagnóstico compara o arquivo realmente executado pelo PM2 com o arquivo da instalação atual do CLI e mostra ambos quando diferem. Em versões sem essa recuperação automática, monky restart --fresh --data <pasta> recria somente o registro selecionado, sem apagar o banco. Execute com o mesmo usuário que gerencia aquela instância; se a divergência persistir, confira qual processo atende à porta do servidor.

Módulos nativos são um problema à parte: better-sqlite3 e o worker do mediasoup são compilados contra o ABI do Node (20 = 115, 22 = 127, 24 = 137). Qualquer troca de versão maior exige reinstalar o CLI, e é isso que o monky update faz.

`monky logs`

Exibe os logs do servidor iniciado com monky start.

bash

monky logs [--lines <n>] [--level <nível>] [--no-follow]

Opções

Opção	Descrição	Padrão
`--lines <n>`	Quantidade de linhas anteriores a exibir	`100`
`--level <nível>`	Nível mínimo: `INFO`, `WARN` ou `ERROR`	sem filtro
`--no-follow`	Imprime e sai, em vez de seguir em tempo real	segue

--level filtra por nível mínimo: INFO mostra tudo, WARN mostra avisos e erros, ERROR mostra só erros. Linhas de continuação (como stack traces) acompanham o nível da linha acima delas.

Exemplos

bash

monky logs                              # segue em tempo real (Ctrl+C para sair)
monky logs --lines 500                  # começa com as últimas 500 linhas
monky logs --level WARN                 # só avisos e erros
monky logs --level ERROR --no-follow    # imprime os erros recentes e sai

TIP

monky logs lê os logs do PM2. Se o servidor estiver rodando dentro do app Monky, use o Monitor do Servidor no próprio app (menu do servidor → Monitor do Servidor).

`monky members`

Lista os membros do servidor e seus cargos.

bash

monky members
monky members info <nickname|clientId>

members info exibe id, clientId, chave pública, datas de criação e último acesso, se é o dono e a lista de cargos.

`monky admin`

Concede ou remove o cargo Admin.

bash

monky admin add [nickname|clientId]
monky admin remove [nickname|clientId]

Sem argumento, o comando lista os membros para você escolher. Exige o servidor parado; veja Alterações com o servidor no ar.

`monky roles`

Administra os cargos do servidor.

bash

monky roles                       # lista
monky roles create [nome] [cor] [permissões]
monky roles assign [membro] [cargo]
monky roles unassign [membro] [cargo]
monky roles delete [cargo]

Sem argumentos, cada subcomando é interativo. As permissões podem ser passadas por nome, separadas por vírgula. A cor usa o formato #RRGGBB. O cargo padrão do servidor não pode ser removido de um membro. Criar, atribuir, remover e apagar cargos exige o servidor parado; listar, não.

Um cargo novo segue as mesmas regras do app: o nome tem de 1 a 32 caracteres e não pode ser Admin, reservado ao cargo de administrador. Cargo não concede a permissão de administrador; para isso, use monky admin add.

`monky config`

Em um terminal, abre as configurações do CLI, incluindo idioma e acesso à configuração do servidor. Sem TTY ou em CI, mantém a consulta direta do servidor.

bash

monky config                        # menu de configurações em um terminal
monky config show                   # exibe diretamente os dados do servidor
monky config language en-US         # idioma do CLI, mesmo sem servidor
monky config set                    # escolhe a chave interativamente
monky config set <chave> [valor]    # altera direto

Chaves

Chave	Descrição	Padrão
`name`	Nome do servidor (mínimo 2 caracteres)	`Servidor dos Amigos`
`password`	Senha de entrada. Vazio, `none` ou `clear` remove a senha	sem senha
`port`	Porta TCP, de 1024 a 65535	`3000`
`icon`	Caminho de uma imagem, copiada para a pasta de dados. Vazio ou `clear` remove	sem ícone
`maxUsers`	Máximo de membros cadastrados. `0` remove o limite	`20`
`maxMessageLength`	Caracteres por mensagem. `0` remove o limite de caracteres; o teto técnico de 8 MiB por pacote permanece	`16000`
`allowSoundboard`	Permite o soundboard (`true`/`false`). Desligar também desliga o cache de áudios recentes	`true`
`allowEveryoneMention`	Permite `@todos`/`@everyone` no chat (`true`/`false`)	`true`
`maxAttachmentFileBytes`	Tamanho máximo por anexo, em bytes. Não pode passar do espaço total	sem limite
`maxAttachmentStorageBytes`	Espaço total para anexos, em bytes	sem limite
`voiceMode`	Modo de voz: `p2p` (mesh direto) ou `sfu` (Selective Forwarding Unit)	`p2p`
`autoUpdate`	Liga a atualização automática da máquina (`true`/`false`). Veja Atualização automática	`false`
`turn`	Liga o relay de mídia TURN (`true`/`false`). Só em Linux, exige o coturn instalado	`false`
`trustedProxies`	IPs ou redes (CIDR) dos seus proxies reversos, separados por vírgula. `none` desliga. Veja Atrás de um proxy reverso	desligado

port, autoUpdate e trustedProxies podem mudar com o servidor no ar. Alterar port ou trustedProxies com o servidor no ar oferece reiniciar na hora, pelo mesmo caminho do monky restart: avisa quem está em chamada, regrava o registro do PM2 e roda pm2 save, para que a porta nova sobreviva a um reboot. As demais chaves ficam no banco e exigem o servidor parado (veja Alterações com o servidor no ar); elas passam a valer no próximo monky start.

Exemplos

bash

monky config show
monky config set name "Servidor dos Amigos"
monky config set voiceMode sfu      # ativa modo SFU com estimativa de capacidade
monky config set password           # digitada de forma oculta
monky config set password clear     # remove a senha
monky config set maxUsers 50
monky config set autoUpdate true
monky config set turn true          # ver "Relay de mídia (TURN)" abaixo
monky config set trustedProxies 127.0.0.1   # servidor atrás de proxy reverso

Relay de mídia (TURN)

Por padrão, a voz e o vídeo do Monky trafegam direto entre os participantes (P2P). Quando dois membros estão atrás de CGNAT, eles não conseguem se enxergar e a chamada não conecta. O TURN resolve fazendo o servidor repassar a mídia desse par.

Guia completo

Veja a página dedicada do Relay TURN com instruções detalhadas de portas, firewall (Oracle Cloud, AWS, iptables, ufw), verificação e troubleshooting.

Ativando

bash

monky stop
monky config set turn true
monky start

O coturn é instalado automaticamente pela sua distro. Se o servidor não rodar como root, rode uma vez: sudo bash scripts/install-turn.sh

Portas necessárias

Porta	Protocolo	Função
`3478`	TCP e UDP	Sinalização TURN
`49152-65535`	UDP	Relay de mídia

Devem estar abertas tanto no firewall do Linux quanto no painel do provedor (Oracle Cloud, AWS, etc.).

Verificando

bash

monky status    # deve mostrar ✔ acessível

No painel monky status --watch, a configuração do TURN é relida só quando o banco muda (no máximo a cada 30 s), e as portas são testadas a cada 60 s ou logo que o TURN é ligado.

Desligando

bash

monky stop
monky config set turn false
monky start

Modo SFU (Selective Forwarding Unit)

Por padrão, o Monky opera em P2P Mesh: cada pessoa transmite seus streams diretamente para todos os participantes do canal. No entanto, se um anfitrião for compartilhar tela em 1080p 60fps para 20 pessoas, precisaria de ~120 Mbps de upload contínuo.

O modo SFU centraliza o encaminhamento de mídia via mediasoup. Quem compartilha envia uma única vez para o servidor, e o servidor replica o fluxo para os ouvintes/espectadores.

Ativando via CLI

bash

monky stop
monky config set voiceMode sfu
monky start

O CLI calcula e exibe automaticamente uma estimativa de capacidade baseada na quantidade de cores da CPU, memória RAM do servidor e banda de upload.

Portas necessárias para SFU

Porta	Protocolo	Função
`40000`	UDP e TCP	Porta de mídia WebRTC do worker mediasoup, compartilhada por todas as chamadas. Se estiver ocupada, o SFU usa a próxima livre da faixa `40000-49151`; `monky status` e `monky config` mostram qual

O range precisa estar aberto no firewall do servidor (Oracle Cloud, AWS Security Group, iptables/ufw) — em UDP e também em TCP, que é o caminho de quem está numa rede que bloqueia UDP. Os comandos prontos e como conferir estão em Abrindo as portas do Modo SFU.

`monky tls`: conexão segura automática

Faz o servidor aceitar também wss://, criptografado, usando um certificado gratuito da Let's Encrypt emitido direto para o IP público, sem domínio e sem proxy reverso. É o que permite entrar no servidor pela versão web do Monky. O ws:// continua funcionando para quem já usa.

bash

monky tls            # mostra o estado: válido até, próxima renovação, último erro
monky tls enable     # confere a porta 80 e ativa
monky tls disable    # volta a aceitar só ws://

Requisitos: IP público e a porta 80/TCP aberta para a internet, além da porta do servidor. A Let's Encrypt valida o IP acessando a porta 80, que o Monky abre só durante a validação.
Pré-checagem: antes de ativar, o Monky pede um certificado de teste ao ambiente de staging da Let's Encrypt. Se a porta 80 não estiver acessível, a ativação é recusada com o motivo.
Linux sem root: o sistema não deixa um usuário comum abrir a porta 80. O monky tls enable oferece liberar isso com sudo (grava net.ipv4.ip_unprivileged_port_start=80 em /etc/sysctl.d/60-monky-tls.conf). Sem sudo sem senha, ele mostra o comando para você rodar uma vez.
Renovação: o certificado vale cerca de 6 dias e é renovado sozinho 2 dias antes de vencer, sem derrubar ninguém. Se o IP mudar, um certificado novo é emitido. Se a renovação falhar, o servidor continua aceitando ws://, avisa em monky status e tenta de novo.
Não funciona com VPN (Radmin, Hamachi, ZeroTier, Tailscale), CGNAT ou só rede local: nesses casos o app desktop continua conectando por ws://.
A mudança vale a partir do próximo monky start ou monky restart; com o servidor no ar, o comando oferece reiniciar.

Certificado compartilhado entre servidor e bots

O certificado fica numa pasta da máquina, ~/.monky/tls (mude com a variável MONKY_TLS_DIR), e é usado por todos: o servidor e qualquer bot feito com o @monky/bot-sdk. Quem ativa o TLS primeiro emite o certificado; os demais, ao rodar tls enable, só reaproveitam o que já existe para o IP público da máquina, sem pedir outro à Let's Encrypt. Cada servidor ou bot ativa e desativa por conta própria; tls disable nunca apaga o certificado compartilhado.

Renovação: quem estiver com o TLS ativo renova, e um arquivo de trava (renew.lock) garante que só um processo renove por vez e só ele abra a porta 80. Os outros enxergam o arquivo renovado em até 1 minuto e trocam o certificado sem reiniciar.
Migração: se o servidor já tinha um certificado em <dados>/tls/certificate.json, ele é copiado para a pasta compartilhada na primeira vez.

Nos bots

Todo bot do @monky/bot-sdk ganha o mesmo comando (troque <bot> pelo nome do comando do seu bot):

bash

<bot> tls            # mostra o estado
<bot> tls enable     # reaproveita o certificado compartilhado ou emite um novo
<bot> tls disable    # este bot deixa de usar TLS

No código do bot:

const https = require('node:https');
const { createBotTls } = require('@monky/bot-sdk');

const tls = createBotTls({ dataDir: process.env.MONKY_BOT_HOME });
const material = tls.material(); // { cert, key } ou null se o TLS não estiver ativo
const server = material ? https.createServer(material, handler) : http.createServer(handler);
tls.onChange(({ material }) => material && server.setSecureContext?.(material));
tls.start(); // renova e acompanha o arquivo compartilhado

`monky update`

Atualiza o Monky para a última versão publicada.

bash

monky update [--beta] [--check] [--yes]

Opções

Opção	Descrição
`--beta`, `-b`	Considera também as prereleases
`--check`	Apenas verifica e sai, sem atualizar
`--yes`, `-y`	Não pergunta nada — para uso em scripts e no auto-update

O comando baixa e instala o novo pacote com npm install -g a partir dos artefatos da release no GitHub.

Ao final, os servidores em execução são reiniciados (com confirmação, exceto com --yes): todos os desta máquina, ou só o de --data. Servidores parados continuam parados e usam a nova versão no próximo monky start.

Para que uma versão quebrada não deixe o servidor fora do ar:

Antes de reiniciar, o CLI novo é executado uma vez. Se ele não roda nesta máquina (Node antigo, módulo faltando), a versão anterior é reinstalada e nenhum servidor é reiniciado.
Cada servidor tem o server.db copiado para backups/ antes do reinício (ficam as 3 cópias mais recentes) e precisa voltar a responder em até 60 segundos.
Se o primeiro servidor que reinicia na versão nova não responder, a atualização é desfeita: a versão anterior é reinstalada, o banco volta da cópia quando a versão nova já o tinha migrado, e o servidor sobe de novo. O comando termina com erro para avisar, e monky logs mostra o motivo.

monky update nunca instala uma versão mais antiga que a atual. Por exemplo, quem está numa beta mais nova que a última estável não recebe a estável por cima. Forçar a reinstalação só é oferecido para a mesma versão. Duas atualizações na mesma máquina não rodam ao mesmo tempo: a segunda espera a primeira terminar.

Antes de desconectar os participantes para esse reinício, o servidor informa que está em atualização. Os clientes mostram um aviso próprio no idioma selecionado e orientam a reconectar em alguns segundos. Isso exige um processo do servidor que já ofereça esse aviso; um processo antigo, ainda em execução durante a primeira atualização, pode enviar apenas o aviso genérico de encerramento. Recusar o reinício não desconecta participantes nem envia um aviso de atualização.

Exemplos

bash

monky update --check           # há atualização estável?
monky update --check --beta    # e considerando betas?
monky update                   # atualiza para a última estável
monky update --beta            # atualiza para a última, incluindo betas

Atualização automática

bash

monky config set autoUpdate true

Registra no PM2 um único agendamento para a máquina (monky-auto-updater), que roda monky update --yes: instala a atualização uma vez e reinicia os servidores que estiverem em execução. Um servidor parado de propósito não é ligado. Se uma execução encontrar um servidor ainda com o código anterior (por exemplo, depois de um reinício recusado), ela o reinicia, com a mesma cópia do banco e a mesma volta de versão em caso de falha.

No terminal, o CLI pergunta a agenda: diária num horário HH:MM (padrão 04:00) ou a cada 1 a 168 horas. Em scripts, usa a diária às 04:00. O canal segue a versão instalada: se você está numa beta, o auto-update acompanha o canal beta. O script fica em ~/.monky/auto-update.cjs (ou na pasta de MONKY_HOME). Ligar o auto-update substitui os agendamentos por servidor criados por versões anteriores.

Funciona em Linux, macOS e Windows. Para desligar:

bash

monky config set autoUpdate false

`monky destroy`

Apaga permanentemente todos os dados de um servidor.

bash

monky destroy [--data <pasta>]

Remove o banco, anexos, avatares e configurações, encerra o processo PM2 e tira o servidor do registro. Pede duas confirmações: digitar DESTROY e um "sim" final. Só aceita pastas que realmente contenham um servidor Monky.

Sem um PM2 que o CLI consiga usar, os processos PM2 do servidor não podem ser removidos e continuariam reiniciando o servidor apagado. Nesse caso, o aviso mostra os nomes deles e uma terceira confirmação pergunta se os dados devem ser apagados mesmo assim; recusar mantém tudo como está.

Se houver gente conectada, o aviso aparece antes das confirmações, informando quantas pessoas serão desconectadas.

Ver também

Hospedar em VPS — deixar o servidor no ar 24/7
Verificar Releases — conferir a autenticidade dos downloads

Monky CLI ​

Instalação ​

Início rápido ​

Múltiplos servidores ​

Idioma do CLI ​

Opções globais ​

Estrutura da pasta de dados ​

Códigos de saída ​

Alterações com o servidor no ar ​

Referência de comandos ​

monky create ​

Opções ​

Exemplos ​

monky list ​

monky start ​

Opções ​

monky stop ​

monky restart ​

monky status ​

Trocar a versão do Node ​

Procedimento recomendado ​

monky logs ​

Opções ​

Exemplos ​

monky members ​

monky admin ​

monky roles ​

monky config ​

Chaves ​

Exemplos ​

Relay de mídia (TURN) ​

Ativando ​

Portas necessárias ​

Verificando ​

Desligando ​

Modo SFU (Selective Forwarding Unit) ​

Ativando via CLI ​

Portas necessárias para SFU ​

monky tls: conexão segura automática ​

Certificado compartilhado entre servidor e bots ​

Nos bots ​

monky update ​

Opções ​

Exemplos ​

Atualização automática ​

monky destroy ​

Ver também ​

Monky CLI

Instalação

Início rápido

Múltiplos servidores

Idioma do CLI

Opções globais

Estrutura da pasta de dados

Códigos de saída

Alterações com o servidor no ar

Referência de comandos

`monky create`

Opções

Exemplos

`monky list`

`monky start`

Opções

`monky stop`

`monky restart`

`monky status`

Trocar a versão do Node

Procedimento recomendado

`monky logs`

Opções

Exemplos

`monky members`

`monky admin`

`monky roles`

`monky config`

Chaves

Exemplos

Relay de mídia (TURN)

Ativando

Portas necessárias

Verificando

Desligando

Modo SFU (Selective Forwarding Unit)

Ativando via CLI

Portas necessárias para SFU

`monky tls`: conexão segura automática

Certificado compartilhado entre servidor e bots

Nos bots

`monky update`

Opções

Exemplos

Atualização automática

`monky destroy`

Ver também