Desenvolvimento remoto com Zed: SSH, tarefas e pré-visualizações locais

Imagine mover um pequeno projeto web para um servidor de desenvolvimento existente. O editor continua com a aparência habitual. Mas qual máquina executa uma tarefa e para onde aponta o localhost do navegador? Essas são as questões a esclarecer antes de alterar as configurações.

O desenvolvimento remoto com Zed conecta seu editor local a uma cópia de trabalho por SSH. A interface permanece no seu computador portátil; servidores de linguagem, tarefas e terminais são executados no servidor remoto. A documentação de acesso remoto do Zed explica essa divisão.

Os exemplos abaixo são propostas baseadas na documentação. Nenhum foi executado para este artigo: nenhuma instalação do Zed ou sessão SSH foi testada, e nenhuma aplicação, porta ou chamada de IA foi validada. Use o guia para planejar uma configuração e diagnosticar seus limites.

O que permanece local e o que é executado no servidor remoto

Mapeie o editor, a cópia de trabalho e os caminhos de execução

Comece identificando onde o trabalho acontece. Uma janela com aparência local revela pouco sobre o processo por trás dela. A arquitetura documentada atribui um local a cada componente:

Um servidor existente com ferramentas ou dados necessários ao projeto oferece um motivo para trabalhar remotamente. A conexão, por si só, não oferece um ambiente reproduzível nem evidências de melhor desempenho.

Trate as solicitações de IA como um caminho separado

A IA precisa de uma análise própria. A visão geral do acesso remoto descreve a comunicação local com os modelos, enquanto a documentação de privacidade de IA do Zed distingue os caminhos das solicitações para chaves de provedores, gateways, agentes externos e Terminal Threads. Não é possível deduzir para onde vai uma instrução enviada à IA com base no local da cópia de trabalho.

Comece com um servidor autorizado e uma cópia de trabalho dedicada ao desenvolvimento

Confirme o acesso SSH sem enfraquecer a verificação

Este guia pressupõe que você já tenha acesso autorizado a um servidor de desenvolvimento. Prepare suas ferramentas separadamente e escolha uma cópia de trabalho dedicada, fora de produção. O nome de máquina devbox.example.com é fictício; substitua-o pelo servidor aprovado ao planejar a conexão.

Na caixa de diálogo Projetos remotos do Zed, escolha Conectar novo servidor e informe a conexão SSH aprovada. O Zed usa o binário e a configuração SSH locais; sua documentação de conexão recomenda autenticação por chave para conexões frequentes. Mantenha a verificação da chave do servidor ativada e siga o processo de acesso da sua organização. Um erro de conexão é motivo para investigar, nunca para colocar chaves privadas nas configurações do projeto ou desativar a verificação.

Selecione a própria pasta do projeto. A mesma documentação alerta contra a abertura de diretórios raiz muito abrangentes, incluindo a raiz do sistema de arquivos ou todo o diretório pessoal.

Verifique os pré-requisitos do servidor remoto e das ferramentas

O servidor precisa de um binário de servidor Zed correspondente. A documentação de desenvolvimento remoto lista servidores macOS, Linux e Windows com ressalvas, incluindo testes não exaustivos das distribuições Linux. Leia os requisitos do seu servidor antes de se comprometer com a configuração.

Use esta lista de preparação:

• Seu acesso SSH aprovado funciona sem enfraquecer a verificação.
• A plataforma remota consegue executar o servidor Zed correspondente.
• A cópia de trabalho dedicada e o ambiente de execução do projeto já existem.
• O binário do servidor dispõe de um meio aprovado de download ou entrega.

A opção documentada upload_binary_over_ssh baixa o binário do servidor localmente e depois o transfere por SSH. As dependências do projeto ainda precisam de preparação separada, e a opção não torna todos os recursos disponíveis sem conexão à internet. A lista acima permanece uma proposta até você verificá-la no seu servidor.

Coloque as configurações e as verificações do ambiente de execução no lugar certo

Separe as configurações locais, do servidor e do projeto

Uma alteração de configuração só ajuda se o processo que precisa dela a ler. Ambos os processos do Zed leem as configurações do projeto, mas nenhum lê o arquivo de configurações principal do outro. A documentação de configurações apresenta os escopos disponíveis:

Mantenha os caminhos específicos de cada máquina fora da configuração compartilhada. Caso contrário, a próxima pessoa que abrir a cópia de trabalho herdará uma dependência do seu sistema de arquivos.

Verifique o ambiente de execução remoto sem expor todo o ambiente

Para um projeto Node.js em um servidor de desenvolvimento semelhante a Unix, considere estas verificações somente de leitura no terminal remoto. Pressupõe-se um shell do tipo POSIX, o utilitário hostname disponível e um ambiente de execução Node.js instalado. Executá-las em um shell separado no computador portátil responde à pergunta errada.

hostname
pwd
command -v node
node --version

Sem argumentos, hostname exibe o nome da máquina; pwd informa o diretório de trabalho. command -v informa como o shell resolve o comando, podendo identificar um alias ou uma função em vez do caminho de um executável. node --version exibe a versão do Node.js. A referência de hostname documenta o comportamento do comando, não o suporte do Zed ao OpenBSD.

Inspecione os resultados em privado. O servidor corresponde à máquina pretendida? O diretório pertence à cópia de trabalho? Compare o ambiente de execução encontrado com os requisitos do projeto. Se a localização do comando falhar, resolva isso antes de solicitar a versão. Nenhuma saída ou versão esperada é afirmada aqui, e não há necessidade de compartilhar nomes de máquinas sensíveis ou expor todo o ambiente.

O sucesso no terminal responde apenas à questão do terminal. A documentação de ambiente do Zed descreve tratamentos diferentes para inicializações pela linha de comando e pela interface gráfica, tarefas, terminais e localização de servidores de linguagem. Verifique separadamente a localização do binário do servidor de linguagem. Não presuma que variáveis ou segredos do computador portátil sejam encaminhados automaticamente.

Para projetos de empacotamento Python, a lista de verificação de compilação e publicação com uv aborda outro limite: uma cópia de trabalho funcional não comprova que o pacote distribuído funciona.

Faça as tarefas remotas usarem o diretório, o arquivo salvo e o contexto pretendidos

Escolha deliberadamente o escopo da tarefa e a política de salvamento

Coloque as tarefas do projeto em .zed/tasks.json. As tarefas globais ficam disponíveis em todos os projetos. A documentação de tarefas do Zed define ambos os escopos e estabelece a raiz do projeto atual como diretório de trabalho padrão.

Esta definição proposta de tarefa de projeto apenas exibe esse diretório em um servidor semelhante a Unix:

[
  {
    "label": "inspect-task-directory",
    "command": "pwd",
    "save": "none"
  }
]

Gravar esse arquivo altera a configuração, embora pwd seja somente de leitura. O exemplo não foi instalado nem executado. Seu rótulo é um identificador de máquina, e seu comando informa o diretório de trabalho. Se adicionar um cwd explícito para um subprojeto, use o diretório remoto pretendido. Um caminho do computador portátil não o identificará.

O padrão de salvamento merece atenção. Com none, um conteúdo editado em memória pode diferir do arquivo que uma ferramenta lê. Escolha current para salvar o conteúdo ativo ou all para salvar todos os conteúdos editados, conforme documentado na referência de tarefas. Verifique quais arquivos essa escolha alteraria antes de adotá-la.

Para uma tarefa posterior baseada em arquivos, siga a separação entre command e args da documentação de tarefas, incluindo o tratamento de variáveis em caminhos com espaços. Este exemplo com pwd não tem argumento de arquivo. Ele não informa quais dados de entrada um teste leria.

Diferencie o contexto da reexecução da reutilização do terminal

Selecionar um arquivo diferente não altera necessariamente uma reexecução. Por padrão, o Zed reutiliza o contexto resolvido, incluindo variáveis de arquivo capturadas anteriormente. O exemplo de controle da reexecução coloca reevaluate_context na ação task::Rerun em uma associação de teclas. Não se trata de um campo do modelo de tarefa.

A reutilização do terminal controla outra coisa. Os padrões documentados reutilizam um terminal e aguardam a conclusão da tarefa anterior. Uma nova aba não selecionará outro servidor ou arquivo. A execução simultânea também não resolverá uma divergência nos dados de entrada.

Antes de executar o comando real do projeto, inspecione a cópia de trabalho e o diretório de trabalho e depois compare os dados salvos com o contexto resolvido. Exibir o diretório com sucesso deixa os testes da aplicação sem verificação.

Acompanhe uma aplicação web remota até a pré-visualização em localhost no navegador

Separe a porta de escuta da aplicação do encaminhamento SSH

Para uma pré-visualização hipotética, suponha que você inicie separadamente uma aplicação de desenvolvimento na porta de loopback 3000 do servidor remoto. A aplicação fica fora da configuração deste guia. Suas instruções de instalação e inicialização não são fornecidas nem executadas aqui.

Este fragmento proposto mapeia a porta local 8080 para a porta remota usando a configuração ssh_connections.port_forwards documentada pelo Zed. Incorpore-o à conexão do seu servidor autorizado, preservando o restante da lista de conexões.

{
  "ssh_connections": [
    {
      "host": "devbox.example.com",
      "port_forwards": [
        { "local_port": 8080, "remote_port": 3000 }
      ]
    }
  ]
}

Acompanhe o caminho pretendido da solicitação até a aplicação que já está em execução:

O encaminhamento não pode iniciar a aplicação. Se a pré-visualização falhar, primeiro verifique se a aplicação está escutando. Depois investigue a rota de encaminhamento, incluindo conflitos de portas locais e o destino remoto. Ter um túnel configurado deixa a prontidão da aplicação sem verificação.

Mantenha a pré-visualização vinculada a localhost

Os padrões de encaminhamento do Zed vinculam ambas as extremidades a localhost. Mantenha-os para esta pré-visualização. Definir local_host como 0.0.0.0 vincula todas as interfaces locais. Configure a conexão e o encaminhamento pretendidos antes de acessar http://localhost:8080; o localhost do navegador continua se referindo ao seu computador portátil.

A vinculação à interface de loopback não fornece autenticação da aplicação nem publicação para acesso público. Assim que conseguir acessar a aplicação pretendida, os testes de estados de acessibilidade com Playwright oferecem uma tarefa separada de verificação da aplicação. Acessar a pré-visualização não comprova a aprovação em um teste.

Use o roteiro Servidor-Tarefa-Pré-visualização para verificar um projeto de desenvolvimento

Servidor-Tarefa-Pré-visualização é a lista de verificação editorial proposta neste guia. Ela reúne os limites documentados em uma matriz de decisão; não é um recurso do Zed nem um padrão do setor e não foi testada como método de implantação.

Servidor: identifique a cópia de trabalho e o escopo da configuração

Use uma cópia de desenvolvimento sem dados sensíveis. Defina qual servidor e qual escopo de configuração está inspecionando antes de diagnosticar a aplicação.

Tarefa: inspecione o ambiente de execução e os dados de entrada salvos

Leia os dados de entrada do comando com o mesmo cuidado dedicado ao seu rótulo. Verifique o comportamento do servidor de linguagem separadamente dos resultados do terminal.

Pré-visualização: verifique a porta de escuta e a rota do navegador

Acompanhe a solicitação até encontrar a primeira divergência. Corrija essa camada antes de alterar outra configuração.

Mantenha um pequeno registro durante a avaliação. Essas observações ajudam a decidir sobre a configuração; não medem um ganho de desempenho.

Para um registro de planejamento legível por máquina, os mesmos limites podem ser representados da seguinte forma. Seu estado continua sendo proposto e não executado.

{
  "framework": "host-task-preview",
  "checks": ["authorized-checkout", "saved-task-input", "running-app-and-local-forward"],
  "status": "proposed-unexecuted"
}

Antes de adicionar repositórios ou dados sensíveis, certifique-se de que consegue explicar cada caminho e limite de acesso. Mantenha as anotações privadas e omita credenciais ou listagens completas do ambiente. Este artigo não registra nenhuma lista de verificação concluída.

Erros comuns e limites: SSH não é um ambiente isolado nem uma política de privacidade de IA

Corrija a suposição antes de alterar a configuração

Observe estes erros de diagnóstico:

• Verificar o ambiente de execução do computador portátil quando a tarefa é executada remotamente.
• Abrir todo o diretório pessoal em vez do projeto.
• Presumir que a reexecução acompanha o arquivo recém-selecionado.
• Esperar que as alterações não salvas sejam os dados de entrada testados.
• Encaminhar uma porta antes de a aplicação estar escutando.

Cada um remete a uma linha específica da matriz de decisão. Use-a para isolar o problema.

Analise separadamente a confiança na árvore de trabalho e o roteamento de IA

O Zed mantém registros de confiança na árvore de trabalho separados para cada servidor SSH. O Modo restrito impede a aplicação das configurações do projeto e a instalação ou inicialização dos servidores de linguagem e MCP não confiáveis associados a elas; ferramentas globalmente confiáveis ainda podem ser executadas. Analise a configuração e as instruções do projeto, junto com as ferramentas que ele pode invocar, antes de conceder confiança. Conceder confiança irrestrita é uma solução inadequada para uma questão de permissão. A confiança na árvore de trabalho não oferece um ambiente completamente isolado.

Para a IA, inspecione o caminho escolhido para as solicitações e os termos do provedor. Agentes externos e ferramentas baseadas em terminal podem gerenciar sua própria autenticação, roteamento e permissões, como explicam as orientações de privacidade do Zed. O transporte SSH não oferece nenhuma garantia universal sobre retenção, treinamento ou confidencialidade.

Se o caminho escolhido incluir um gateway, o guia do Vercel AI Gateway apresenta uma lista de verificação separada para roteamento e política do provedor. Esse link não implica que sua sessão do Zed use o gateway. A edição remota básica não exige chamadas de IA; o guia de início rápido de IA do Zed indica o controle Desativar IA no Editor de configurações.

Saiba quando manter o projeto local

O desenvolvimento remoto deve justificar seu custo de manutenção. Pondere a administração e a preparação das ferramentas em relação ao trabalho que elas ajudam a realizar. Verifique também o suporte à plataforma, a confiabilidade da conexão e a manutenção contínua. Se ativar a IA, analise o comportamento do provedor e sua política de dados. Economia ou menor latência exigem evidências da sua própria carga de trabalho.

Mantenha as práticas normais de salvamento e controle de versão; reconectar não é uma estratégia de cópia de segurança. Se ninguém puder manter o limite de acesso do servidor, mantenha o projeto local. Caso contrário, comece com a menor cópia de trabalho cuja localização resolva um problema real de desenvolvimento. Amplie depois de compreender seus caminhos de execução e pré-visualização.