---
id: "sistema.ssh-hosts"
titulo: "Hosts SSH"
resumo: "Cadastre as máquinas em que você trabalha por SSH e conecte-se a elas pelo app."
idioma: "pt-br"
tipo: "guia"
categoria: "ambientes"
aplicavelDesde: "0.0.16"
capabilities: ["environment.ssh.hosts"]
estadoEditorial: "aprovado"
nivelEvidencia: "artefato-distribuido"
refFonte: "27574c339b58316408f6be2d62169d59041d07bf"
revisaoFonte: "2026-09-24"
revisor: "mantenedor (v1, 2026-10-03)"
rota: "/docs/pt-br/sistema/ssh-hosts/"
fonte: "pt-br/sistema/ssh-hosts.md"
caminhoPublico: "docs/publica/pt-br/sistema/ssh-hosts.md"
hashFonte: "sha256:15d925dba9c6bf1c69e61dadbd724e830931f1dd2bb502c2208b2fd8d9d2ea88"
hashDestaPagina: "sha256:15d925dba9c6bf1c69e61dadbd724e830931f1dd2bb502c2208b2fd8d9d2ea88"
traducaoAssistidaPorIA: false
traducaoDesatualizada: false
corpoRetido: false
---
Um **host SSH** é uma máquina que o Elyra acessa pela rede para rodar o trabalho pesado: o projeto, os
terminais e os comandos de Git acontecem **no host**, não no seu computador. Cadastrar o host é o passo
que torna possível abrir um projeto remoto, criar um workspace remoto e usar o terminal lá.

## Quando usar

- O projeto mora numa máquina de desenvolvimento, numa VPS ou num servidor de build.
- Você quer usar o poder do servidor (CPU, memória, GPU, ambiente já preparado) mantendo o app na sua
  mesa.
- Você prefere não clonar o repositório de novo no seu computador.

## Pré-requisitos

- O app instalado e com licença ativa.
- Acesso de rede do seu computador até o host.
- Autenticação SSH já resolvida no seu computador — o app reaproveita o que o seu SSH já sabe.
- No host: um shell POSIX funcional. O Elyra não suporta host Windows para esse fluxo.

## Cadastrar um host

1. Abra **Ajustes > Conexões > Hosts SSH**.
2. Escolha uma das duas entradas:
   - **Importar de `~/.ssh/config`** — o app lê os hosts que você já configurou e os traz para a lista.
     É o caminho recomendado quando o seu SSH já funciona no terminal.
   - **Adicionar** — cadastre um host novo informando o alvo.
3. Ajuste o que precisar e salve.
4. Na linha do host, use **Conectar** para abrir a conexão, **Testar** para conferir o acesso sem entrar
   no fluxo de trabalho e **Editar** para corrigir o cadastro.

O que o cadastro grava é a configuração do host. A conexão em si é aberta e encerrada pelos botões
**Conectar** e **Desconectar**.

## A primeira conexão a um host limpo

A primeira conexão costuma ser a mais lenta, porque quase todo o trabalho acontece do outro lado. O app
instala um **auxiliar versionado** no home do host, em `~/.elyra-remote/`, e mantém esse auxiliar rodando
para que os terminais sobrevivam a uma queda da conexão SSH.

Se o host não tiver compilador, `make` ou Python, a instalação dos módulos nativos falha. Nesse caso o
app:

1. verifica o que está faltando no host;
2. monta o comando do gerenciador de pacotes detectado, direto se a conta for `root` e com `sudo -n` se
   não for;
3. **pergunta uma vez, mostrando o comando exato que vai rodar**;
4. se você aceitar, refaz a instalação e segue; se recusar, mostra o comando para você rodar à mão.

A resposta fica guardada por host, então a pergunta não volta a cada conexão. Sem ninguém para responder
— um processo automático, por exemplo — a resposta é sempre não.

## Durante a conexão

Enquanto o host conecta, o cartão dele mostra **em que passo** a conexão está. Essa informação existe
porque conectar a um host novo pode levar de um a três minutos, e sem ela uma conexão que anda é
indistinguível de uma travada.

Depois de conectado, o cartão volta a falar de sincronização do workspace, e não do passo da conexão.

## Resultado

- O host aparece conectado em **Ajustes > Conexões > Hosts SSH**.
- Ele fica disponível para **Adicionar projeto > Outra máquina (SSH)** e para novos workspaces com
  destino SSH.
- Terminal, arquivos e Git das sessões desse host rodam na máquina remota.

## Limites

- **Cada forma de autenticação depende do seu SSH.** O app reaproveita a configuração existente; quando a
  autenticação exige interação específica, ele usa o binário `ssh` do sistema.
- **A disponibilidade do host não é garantida pelo cadastro.** Um host salvo não é um host no ar.
- **`Desconectar` não apaga nada.** Nem arquivos, nem sessões em execução no host.
- **Os números de espera do auxiliar** (tempo de ociosidade, tentativas) são decisão de implementação e
  podem mudar entre releases.
- **Plataformas do host.** O auxiliar do Elyra tem builds para Windows, macOS e Linux.
- **Credenciais não aparecem nesta documentação** — nem chaves, nem senhas, nem nomes de máquinas reais.

## Quando não conectar

1. **Leia a mensagem de erro inteira.** Ela classifica o motivo mais comum — por exemplo, uma chave
   protegida por senha que ninguém informou. Quando o app não reconhece o motivo, ele mostra o texto
   original, sem tradução, justamente para você poder pesquisar ou colar num relato.
2. **Confira se o seu SSH funciona fora do app.** Rode o mesmo alvo no terminal do sistema. Se falhar lá,
   o problema é a conexão, não o Elyra.
3. **Se o erro citar uma versão de auxiliar**, o auxiliar instalado no host e o app são de builds
   diferentes. Reconectar resolve; o host instala a versão nova.
4. **Se o host tiver ficado no meio de uma instalação**, uma conexão lenta logo depois de um reinício
   costuma ser uma trava de instalação órfã. Esperar a trava expirar e tentar de novo é o caminho.

## Próximos passos

- [Abrir um projeto em outra máquina](/docs/pt-br/sistema/ssh-projeto-remoto/)