---
id: "sistema.ssh-hosts"
titulo: "SSH hosts"
resumo: "Register the machines you reach over SSH and connect to them from the app."
idioma: "en"
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/en/sistema/ssh-hosts/"
fonte: "pt-br/sistema/ssh-hosts.md"
caminhoPublico: "docs/publica/en/sistema/ssh-hosts.md"
hashFonte: "sha256:15d925dba9c6bf1c69e61dadbd724e830931f1dd2bb502c2208b2fd8d9d2ea88"
hashDestaPagina: "sha256:2fed58910812068b8bdce22c3eea2418198d12e68ccc14e88cc1431b554cabdc"
traducaoAssistidaPorIA: true
traducaoDesatualizada: false
corpoRetido: false
---
<!-- traducao-assistida-por-ia: idioma=EN fonte=pt-br/sistema/ssh-hosts.md fonteHash=sha256:15d925dba9c6bf1c69e61dadbd724e830931f1dd2bb502c2208b2fd8d9d2ea88 estado=atual -->

An **SSH host** is a machine the Elyra reaches over the network to run the heavy work: the project, the
terminals and the Git commands happen **on the host**, not on your computer. Registering the host is the
step that makes it possible to open a remote project, create a remote workspace and use the terminal
there.

## When to use it

- The project lives on a development machine, a VPS or a build server.
- You want the power of the server (CPU, memory, GPU, a prepared environment) while keeping the app on
  your desk.
- You would rather not clone the repository again on your computer.

## Prerequisites

- The app installed and with an active licence.
- Network access from your computer to the host.
- SSH authentication already resolved on your computer — the app reuses what your SSH already knows.
- On the host: a system where the Elyra helper can run. Windows, macOS and Linux are in the supported
  platform set.

## Registering a host

1. Open **Ajustes > Conexões > Hosts SSH** (Settings > Connections > SSH hosts).
2. Choose one of the two entry points:
   - **Import from `~/.ssh/config`** — the app reads the hosts you already configured and brings them into
     the list. This is the recommended path when your SSH already works in the terminal.
   - **Add** — register a new host by providing the target.
3. Adjust what you need and save.
4. On the host row, use **Connect** to open the connection, **Test** to check access without entering the
   work flow, and **Edit** to fix the registration.

What the registration stores is the host configuration. The connection itself is opened and closed by the
**Connect** and **Disconnect** buttons.

## The first connection to a clean host

The first connection is usually the slowest, because almost all the work happens on the other side. The
app installs a **versioned helper** in the host's home directory, under `~/.elyra-remote/`, and keeps that
helper running so terminals survive an SSH drop.

If the host has no compiler, `make` or Python, installing the native modules fails. In that case the app:

1. checks what is missing on the host;
2. builds the command for the detected package manager — directly if the account is `root`, and with
   `sudo -n` if it is not;
3. **asks once, showing the exact command that will run**;
4. if you accept, it retries the install and continues; if you refuse, it shows the command for you to run
   by hand.

The answer is remembered per host, so the question does not come back on every connection. With nobody to
answer — an automated process, for example — the answer is always no.

## While the connection runs

While the host connects, its card shows **which step** the connection is on. That information exists
because connecting to a new host can take one to three minutes, and without it a connection that is
moving is indistinguishable from one that is stuck.

Once connected, the card goes back to talking about workspace synchronisation, not about the connection
step.

## Result

- The host appears connected in **Ajustes > Conexões > Hosts SSH**.
- It becomes available for **Add project > Another machine (SSH)** and for new workspaces with an SSH
  destination.
- Terminal, files and Git for sessions on that host run on the remote machine.

## Limits

- **Every authentication method depends on your SSH.** The app reuses the existing configuration; when
  authentication requires specific interaction, it uses the system's `ssh` binary.
- **Registering a host does not guarantee it is available.** A saved host is not a host that is up.
- **`Disconnect` deletes nothing.** Neither files nor running sessions on the host.
- **The helper's wait times** (idle time, attempts) are implementation decisions and can change between
  releases.
- **Host platforms.** The Elyra helper has builds for Windows, macOS and Linux.
- **Credentials do not appear in this documentation** — no keys, no passwords, no real machine names.

## When it will not connect

1. **Read the whole error message.** It classifies the most common reason — for example, a passphrase-
   protected key that nobody provided. When the app does not recognise the reason, it shows the original
   text, untranslated, precisely so you can search for it or paste it into a report.
2. **Check that your SSH works outside the app.** Run the same target in the system terminal. If it fails
   there, the problem is the connection, not Elyra.
3. **If the error mentions a helper version**, the helper installed on the host and the app come from
   different builds. Reconnecting fixes it; the host installs the new version.
4. **If the host was left mid-install**, a slow connection right after a restart is usually an orphaned
   install lock. Waiting for the lock to expire and trying again is the way.

## Next steps

- [Open a project on another machine](/docs/en/sistema/ssh-projeto-remoto/)