# Terminal web

Console do VPS no navegador que continua viva mesmo se você desconectar: tmux dentro do servidor, com permissões por usuário.

Fonte: https://ardumaker.com/pt/docs/terminal-web/

- Categoria: Servidores e infraestrutura
- Estado: Disponível
- Requisitos: Um VPS ativo da empresa; Ser membro da empresa com acesso a esse VPS
- Ferramentas MCP (Só leem): `ver_historial_comandos_vps`, `leer_archivo_vps`
- Ferramentas MCP (Escrevem ou modificam): `instalar_app`, `controlar_app`
- Ferramentas MCP (Destrutivas): `ejecutar_comando_vps`, `guardar_archivo_vps`

## O que permite fazer?

O terminal web abre um console do VPS no navegador. Não é uma sessão SSH efêmera: é um servidor `tmux` que vive dentro do VPS, então o trabalho continua rodando mesmo que você feche a aba, a rede caia ou o backend reinicie.

- Até 5 terminais vivos por pessoa e por VPS; os de outra pessoa não gastam a sua cota.
- Voltar a se conectar ao mesmo terminal quantas vezes for necessário.
- Um admin escolhe o usuário Linux (por padrão `root`) e vê todos os terminais do VPS; um membro trabalha com o próprio usuário e vê só os seus.
- Selecionar e copiar com o mouse como em qualquer página, com prompt colorido e autocompletar.

## Quando convém usar?

- Tarefas longas (um build, uma migração, um download) que você não quer perder se a conexão cair.
- Verificar ou corrigir algo manualmente sem instalar um cliente SSH nem abrir a porta 22.
- Dar acesso de console a um membro com o próprio usuário Linux, sem compartilhar `root`.

## Como funciona na ArduMaker?

Ao criar um terminal, o backend envia ao agente do VPS um script que:

1. instala `tmux` e `ncurses-term` se faltarem;
2. escreve `/etc/ardumaker/tmux.conf` (sem barra de status e com o mouse desligado, para que a seleção seja feita pelo navegador);
3. escreve `/etc/ardumaker/terminal.sh` com o prompt colorido e o anexa uma única vez ao final do `.bashrc` do usuário;
4. cria `/run/ardumaker/tmux/<id>/` com permissões 700 do usuário Linux;
5. escreve a unidade `ardu-tmux-<id>.service` em `/run/systemd/system/` e a inicia.

A unidade própria é o que torna o terminal persistente: o agente do VPS se atualiza sozinho e, ao reiniciar, mata tudo o que depende dele. Com a sua unidade (`Type=oneshot`, `RemainAfterExit=yes`, `KillMode=process`) o `tmux` não depende do agente.

Para se conectar, o painel pede uma credencial válida por 12 horas e abre um WebSocket com ela. A credencial é a chave do WebSocket, não a sessão: quando vence, pede-se outra e volta-se ao mesmo terminal.

Cada vez que os terminais são listados, há uma reconciliação com o VPS: pergunta-se ao `tmux` se a sessão existe e compara-se o `boot_id` do sistema. Sessão ausente com outro `boot_id` é `perdida_por_reinicio` (há aviso); sessão ausente com o mesmo `boot_id` é um terminal fechado. Se o VPS não responder, nada é alterado.

## O que muda realmente?

| Arquivo ou unidade | Para quê |
| --- | --- |
| `/etc/ardumaker/tmux.conf` | Configuração comum do tmux |
| `/etc/ardumaker/terminal.sh` | Prompt colorido, anexado ao `.bashrc` |
| `/run/ardumaker/tmux/<id>/` | Socket do terminal, só para o seu usuário |
| `ardu-tmux-<id>.service` | Unidade em `/run/systemd/system/`: some com o reinício |

Nada fecha um terminal sozinho: nem desconectar, nem inatividade. Só fechá-lo pelo painel (ou `controlar_app` com `close`) mata o `tmux` e libera a vaga.

## Quem vê e usa cada terminal

O terminal é de quem o criou. O de um admin costuma rodar como `root`; se um membro pudesse se conectar a ele teria um shell de administrador que não pode abrir por outra via. Por isso um membro vê e conecta só os seus, e para ele um terminal alheio não existe (404).

| Ação | Admin | Membro |
| --- | --- | --- |
| Escolher usuário Linux | Sim (padrão `root`) | Não: o próprio |
| Ver terminais | Todos do VPS | Só os seus |
| Fechar | Qualquer | Só os seus |

## Esquema

**Um terminal web**

```text
Navegador (xterm.js no painel)
  ↓
WebSocket (credencial de 12 h)
  ↓
Backend da ArduMaker (valida permissões e dono)
  ↓
Agente do VPS (conecta o pty)
  ↓
ardu-tmux-<id>.service (servidor tmux como o usuário Linux)
```

## Resultado esperado

O terminal aparece como `viva` na lista, com o usuário Linux, o dono e a última vez que alguém se conectou. Um terminal `perdida_por_reinicio` continua aparecendo de propósito, para avisar que trabalho foi perdido; some ao fechá-lo.

## Erros e resolução

| Sintoma | Causa |
| --- | --- |
| 409 ao criar | Você chegou ao limite de 5 terminais nesse VPS |
| 403 ao criar | Um membro tentou escolher outro usuário Linux: só um admin pode |
| 500 ao criar | O VPS não conseguiu iniciar o tmux; o detalhe vem na mensagem |
| Prompt sem cores, `ls` sem cores ou Tab que não completa | O `TERM` não existe na base terminfo do VPS ou o shell não é bash |
| Uma mudança de configuração não aparece | Terminais já abertos continuam com o antigo: feche e crie outro |

Para diagnosticar um terminal com aparência errada, cole isto dentro dele:

```sh
echo "TERM=$TERM"; echo "bash=${BASH_VERSION:-NO}"; echo "tmux=${TMUX:-NO}"
infocmp "$TERM" >/dev/null 2>&1 && echo "terminfo OK" || echo "terminfo FALTA"
grep -c ardumaker/terminal.sh ~/.bashrc; ls -l /etc/ardumaker/
```

> **INFO:** Se você digitar `exit`, o tmux termina mesmo que a unidade systemd continue aparecendo como ativa: por isso o estado é perguntado ao tmux e não ao systemd.

## Relação com MCP

Um agente MCP não se conecta aos terminais: eles são das pessoas que usam o painel e nada do que roda via MCP compartilha estado com eles. Ele pode abrir um terminal como app (`instalar_app` com `app_type: terminal`, com as regras do seu dono) e fechá-lo (`controlar_app` com `close`; o de outra pessoa só se o dono for admin).

Para executar comandos, o agente usa `ejecutar_comando_vps`: um comando por chamada, com espera de 10 a 300 segundos, saída cortada em 20000 caracteres e o diretório de trabalho lembrado entre chamadas. Comandos que parecem destrutivos (`rm -rf`, `mkfs`, `shutdown`, `DROP DATABASE`…) são recusados com 409 salvo `confirmado=true`. Limite: 10 comandos por segundo por VPS.

- Leitura: `ver_historial_comandos_vps` (o que foi executado, por quem e com que resultado; guardado por 30 dias, com segredos rotulados ocultos) e `leer_archivo_vps`.
- Escrita com risco: `ejecutar_comando_vps` e `guardar_archivo_vps`, marcadas como destrutivas.

> **PRECAUCION:** Um trabalho longo não é deixado em segundo plano com `nohup … &`: morre quando o agente é atualizado. Lance-o em uma unidade transitória própria, por exemplo `systemd-run --unit=trabajo-x --collect /bin/sh -c '…'`.

Referência em [/mcp/docs](https://ardumaker.com/pt/mcp/docs) e [/mcp/vps](https://ardumaker.com/pt/mcp/vps).

## Funcionalidades relacionadas

- [Servidores VPS](https://ardumaker.com/pt/docs/vps/)
- [Usuários Linux](https://ardumaker.com/pt/docs/usuarios-linux/)
- [Serviços systemd](https://ardumaker.com/pt/docs/systemd/)
- [Túneis SSH](https://ardumaker.com/pt/docs/tuneles-ssh/)
- [Servidor MCP](https://ardumaker.com/pt/docs/servidor-mcp/)