---
id: "sistema.ssh-projeto-remoto"
titulo: "Open a project on another machine"
resumo: "Create a project or workspace pointing at a folder that lives on an SSH host."
idioma: "en"
tipo: "tutorial"
categoria: "ambientes"
aplicavelDesde: "0.0.16"
capabilities: ["environment.ssh.project"]
estadoEditorial: "aprovado"
nivelEvidencia: "artefato-distribuido"
refFonte: "27574c339b58316408f6be2d62169d59041d07bf"
revisaoFonte: "2026-09-24"
revisor: "mantenedor (v1, 2026-10-03)"
rota: "/docs/en/sistema/ssh-projeto-remoto/"
fonte: "pt-br/sistema/ssh-projeto-remoto.md"
caminhoPublico: "docs/publica/en/sistema/ssh-projeto-remoto.md"
hashFonte: "sha256:73d2931401e3ee5c8a88ea3142d614506668338edafa474a1d10cb8f6e99f32e"
hashDestaPagina: "sha256:db760801a84550c39141526ef5930e140d4000a687d5f80c6d1aa2b646ec2ef5"
traducaoAssistidaPorIA: true
traducaoDesatualizada: false
corpoRetido: false
---
<!-- traducao-assistida-por-ia: idioma=EN fonte=pt-br/sistema/ssh-projeto-remoto.md fonteHash=sha256:73d2931401e3ee5c8a88ea3142d614506668338edafa474a1d10cb8f6e99f32e estado=atual -->

This tutorial takes you from a registered host to a workspace running on an SSH host. The project **is
not copied**: the app registers a path that exists on the remote machine, and the work starts happening
there.

## Prerequisites

- An SSH host already registered and connected. If you do not have one yet, start with
  [SSH hosts](/docs/en/sistema/ssh-hosts/).
- The path of the project folder **on the host**. You will pick it through the remote folder browser.
- Git installed on the host, if the project is a repository.

## Step 1 — Add the project

1. Open the **Add project** flow.
2. Choose **Another machine (SSH)**.
3. Select the **host** from the list.
4. Choose the **path** of the project folder.

If the host is disconnected, the screen shows **Connect**. Connect before choosing the path — the folder
browser needs the connection to list what exists on the other side.

**The folder browser is the host's, not your computer's.** It lists directories that exist on the remote
machine. If you expect to see your home folder, you are on the wrong screen.

## Step 2 — Confirm the creation

On confirmation, the app registers the project pointing at the remote folder. Nothing is downloaded to
your computer, and no file is uploaded to the host.

## Step 3 — Create a workspace

1. Open **New workspace**.
2. Choose the SSH host as the destination.
3. If the host is not connected, use **Connect**.
4. Provide the workspace path and confirm.

The workspace now exists inside the project, with files resolved on the host's folder.

## Result

- The project appears in the list, marked as remote.
- The workspace terminal runs on the host.
- Git operations resolve the repository that lives on the host.
- No project file was copied to your machine.

## Limits

- **The connection must be up before creation is promised.** If the connection fails, the error must
  appear — a project pointing at an unreachable path is not useful and must not look created.
- **Do not choose a local path for a remote host.** The remote folder browser exists precisely to prevent
  that mistake.
- **The remote path must exist on the host.** The app points at a folder; it does not create the
  repository for you.
- **Git on the host depends on the host.** Version, configuration and credentials are the remote machine's.

## If something does not work

1. **Host disconnected.** Use **Connect** on the screen itself and try again.
2. **Folder does not appear in the browser.** Confirm the path exists on the host and that your account
   can read it.
3. **Connection error at creation time.** Fix the connection first — see the troubleshooting section in
   [SSH hosts](/docs/en/sistema/ssh-hosts/).
4. **Project created pointing at the wrong place.** Fix it through the project registration; nothing was
   copied, so there are no files to clean up.

## Safe cleanup

Removing the project or the workspace from the app **does not delete the folder on the host**. Nothing on this
page authorises deleting files on the remote machine.

## Next steps

- [SSH hosts](/docs/en/sistema/ssh-hosts/)