> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurar Tunnels

> Configure o Replit Tunnels para conectar projetos a serviços TCP privados, implante um conector com Docker ou Helm, verifique endpoints e gerencie chaves de registro.

## O que isso habilita

> [!NOTE]
>
> O Tunnels precisa estar habilitado para o seu workspace. Se o Tunnels não estiver disponível nas configurações do seu workspace, entre em contato com o Replit para confirmar a disponibilidade e a habilitação.

Um tunnel permite que um Replit Development Environment compatível alcance um destino TCP aprovado na sua rede privada por meio de um conector operado por você. Esta é uma abordagem de conectividade alternativa a permitir os IPs de saída do sandbox na sua rede.

Execute o conector em uma rede onde ele possa resolver e alcançar seus serviços TCP privados. Você pode usar o comando Docker gerado ou implantar o conector no Kubernetes com o chart Helm abaixo. O Replit opera o plano de controle do tunnel. O chart abaixo implanta apenas o seu conector.

Caminho da conexão: projeto Replit → infraestrutura de tunnel do Replit → seu conector → serviço TCP privado. A autenticação do serviço e o TLS permanecem independentes do registro do tunnel.

## 1. Crie o tunnel no Replit

1. No Replit, use o seletor de workspace para escolher o workspace que possui seus projetos. Abra Settings → Workspace overview e role até Tunnels.

![Abra a seção Tunnels nas configurações do seu workspace.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/tunnels-create.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=074526eae05d0445b5277ce23d8d62f5)

Abra a seção Tunnels nas configurações do seu workspace.

2. Clique em Create tunnel e insira um nome descritivo.

![Crie um tunnel.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/create-dialog.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=b3d3ae820d6cf213aef88dfa12be42c7)

Crie um tunnel.

3. Na caixa de diálogo Save your enrollment key, use os botões de copiar ao lado de Tunnel ID e Enrollment key. Salve a chave de registro no seu gerenciador de segredos aprovado antes de clicar em I’ve saved my key. A chave é exibida apenas uma vez e não pode ser vista novamente depois que você fechar esta caixa de diálogo.

![A caixa de diálogo de chave de registro de uso único. A chave está intencionalmente oculta nesta captura de tela.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/save-key.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=37e69ca9e1702744b64a7c7de8530ca6)

A caixa de diálogo de chave de registro de uso único. A chave está intencionalmente oculta nesta captura de tela.

4. Abra Settings → Workspace overview → Tunnels e selecione seu tunnel. O ID dele aparece abaixo do nome do tunnel, com um botão de copiar. Antes de o conector ficar online, o painel Complete tunnel setup mostra o comando Docker. Substitua o placeholder da chave de registro pela chave que você salvou.

![Copie o comando Docker de Complete tunnel setup.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/setup.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=bf1e6b498d5f788a606142f93e2f21a9)

Copie o comando Docker de Complete tunnel setup.

Para o Helm, copie os valores completos de `RPTUN_TUNNEL_REF` e `RPTUN_ENROLL_ADDR` do comando de configuração para `tunnelRef` e `enrollAddr`. Copie a imagem do contêiner da última linha do comando para `image`. A referência completa do tunnel é diferente do ID curto do tunnel exibido abaixo do nome do tunnel. A chave de registro vem da caixa de diálogo de chave de uso único, não do comando de configuração.

Execute o comando Docker em um host que possa resolver e alcançar seu serviço privado. Para o Kubernetes, use o chart Helm abaixo.

## 2. Implante o conector com Helm

Este chart de exemplo executa o conector do lado do cliente no Kubernetes. Adapte-o aos padrões do seu cluster e valide-o em um ambiente de não produção antes de implantá-lo.

### Crie os arquivos do chart

Crie esta estrutura de diretórios:

```txt theme={null}
replit-tunnel-connector/
  Chart.yaml
  values.yaml
  templates/
    deployment.yaml
customer-values.yaml
```

```bash theme={null}
mkdir -p replit-tunnel-connector/templates
```

`replit-tunnel-connector/Chart.yaml`

```yaml theme={null}
apiVersion: v2
name: replit-tunnel-connector
description: Example customer-side Replit tunnel connector.
type: application
version: 0.1.0
```

`replit-tunnel-connector/values.yaml`

```yaml theme={null}
# Use the image and connection settings from your own tunnel's setup panel.
# Do not put enrollment keys in Helm values or --set arguments.
image: ""
tunnelRef: ""
enrollAddr: ""
existingSecret: replit-tunnel-enrollment
secretKey: enrollment-key
resources: {}
nodeSelector: {}
tolerations: []
affinity: {}
```

`replit-tunnel-connector/templates/deployment.yaml`

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}
  labels:
    app.kubernetes.io/name: replit-tunnel-connector
    app.kubernetes.io/instance: {{ .Release.Name }}
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app.kubernetes.io/name: replit-tunnel-connector
      app.kubernetes.io/instance: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app.kubernetes.io/name: replit-tunnel-connector
        app.kubernetes.io/instance: {{ .Release.Name }}
    spec:
      automountServiceAccountToken: false
      containers:
        - name: connector
          image: {{ required "Set image to the connector image from your tunnel setup panel" .Values.image | quote }}
          imagePullPolicy: IfNotPresent
          env:
            - name: RPTUN_ENROLLMENT_KEY
              valueFrom:
                secretKeyRef:
                  name: {{ required "Set existingSecret" .Values.existingSecret | quote }}
                  key: {{ required "Set secretKey" .Values.secretKey | quote }}
            - name: RPTUN_TUNNEL_REF
              value: {{ required "Set tunnelRef from your tunnel setup panel" .Values.tunnelRef | quote }}
            - name: RPTUN_ENROLL_ADDR
              value: {{ required "Set enrollAddr from your tunnel setup panel" .Values.enrollAddr | quote }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
      nodeSelector:
        {{- toYaml .Values.nodeSelector | nindent 8 }}
      tolerations:
        {{- toYaml .Values.tolerations | nindent 8 }}
      affinity:
        {{- toYaml .Values.affinity | nindent 8 }}
```

### Configure seu tunnel

Crie o namespace e provisione a chave de registro por meio do seu processo aprovado de gerenciamento de segredos. O exemplo espera um Secret chamado `replit-tunnel-enrollment` com um campo chamado `enrollment-key` no namespace `replit-tunnels`. Não coloque a chave de registro em valores do Helm, no controle de versão ou em argumentos `--set`.

`customer-values.yaml` — substitua os três placeholders usando o comando de configuração gerado para o seu próprio tunnel:

```yaml theme={null}
# Replace all three placeholders using your own tunnel's setup command.
image: "CONNECTOR_IMAGE_FROM_REPLIT"
tunnelRef: "TUNNEL_REFERENCE_FROM_REPLIT"
enrollAddr: "ENROLLMENT_ADDRESS_FROM_REPLIT"
existingSecret: replit-tunnel-enrollment
secretKey: enrollment-key
```

Use um digest de imagem de conector imutável aprovado para produção, quando disponível. O chart preserva o entry point da imagem e passa as variáveis de ambiente mostradas no comando Docker gerado. Valide a compatibilidade com a sua imagem exata.

### Renderize e instale

Com o Helm e o `kubectl` configurados para o cluster Kubernetes pretendido, execute estes comandos a partir do diretório que contém `customer-values.yaml` e o diretório do chart. O namespace e o Secret já devem existir:

```bash theme={null}
helm lint ./replit-tunnel-connector -f customer-values.yaml
helm template replit-tunnel ./replit-tunnel-connector \
  --namespace replit-tunnels -f customer-values.yaml
helm upgrade --install replit-tunnel ./replit-tunnel-connector \
  --namespace replit-tunnels -f customer-values.yaml \
  --wait --timeout 5m
kubectl -n replit-tunnels rollout status deployment/replit-tunnel
kubectl -n replit-tunnels get pods -l app.kubernetes.io/instance=replit-tunnel
```

O chart executa uma réplica com a estratégia `Recreate`, então as atualizações causam indisponibilidade. Ele não cria nenhum Service público ou LoadBalancer e não define probes de integridade. A prontidão do Kubernetes por si só não comprova a conectividade do tunnel: confirme **Online** no Replit e conclua os testes de Shell do projeto abaixo.

Antes de usar em produção, valide recursos, arquitetura de CPU, necessidades de estado gravável, contexto de segurança, comportamento de reinicialização e requisitos de rede de saída. O conector precisa alcançar o hostname DNS e a porta TCP do seu serviço privado. Obtenha do Replit os requisitos completos de saída do conector.

Para solução de problemas, revise os logs localmente e remova credenciais e informações privadas antes de compartilhá-los:

```bash theme={null}
kubectl -n replit-tunnels logs deployment/replit-tunnel --tail=100
```

## 3. Confirme que o conector está online

Volte para Settings → Workspace overview → Tunnels e selecione seu tunnel. Aguarde o card Status mostrar Online. Se ele continuar offline, verifique a configuração de registro, o acesso de rede de saída, os eventos do pod e os logs do conector.

![Online significa que o conector está conectado. Never é esperado antes de qualquer tráfego de aplicativo.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/online-empty.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=7930e84bdab9e71e80c25dee819bb7cd)

Online significa que o conector está conectado. Never é esperado antes de qualquer tráfego de aplicativo.

## 4. Registre um endpoint privado

1. Na página de detalhes do tunnel, clique em Add endpoint na seção Endpoints.
2. Insira um nome descritivo e o hostname do destino privado com sua porta TCP, por exemplo database.internal.example:5432.
3. Use um hostname que possa ser resolvido a partir da rede do conector. A interface atual não oferece suporte a destinos com endereço IP.
4. Selecione Test connection. Um check verde significa que o conector consegue alcançar o destino.
5. Adicione o endpoint e confirme que ele aparece na tabela.

![Teste de conexão bem-sucedido: o check verde ao lado de Destination confirma que o conector consegue alcançar o serviço.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/endpoint-connection-test-success.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=05866622a7ec96e3fd06c80010bb9373)

Teste de conexão bem-sucedido: o check verde ao lado de Destination confirma que o conector consegue alcançar o serviço.

O endpoint aparece na tabela, onde você pode copiar seu destino ou abrir o menu de ações de três pontos.

![Endpoint Redis salvo com o conector Online e o destino Reachable.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/endpoint.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=b957c4f84856b532d427d558b723b7e2)

Endpoint Redis salvo com o conector Online e o destino Reachable.

## 5. Verifique a resolução do endpoint em um Shell de projeto do Replit

Use o seletor de workspace para voltar ao workspace que possui o tunnel, abra um projeto nele e abra a aba **Shell** no editor do projeto. Execute as verificações a seguir nesse Shell, não em um chat independente.

### Confirme que o hostname é resolvido

Use o hostname do campo Destination do endpoint, sem a porta nem o esquema de URL:

```bash theme={null}
getent hosts YOUR_ENDPOINT_HOSTNAME
```

Uma consulta bem-sucedida imprime um endereço IP e o hostname. A resolução de DNS por si só não confirma a conectividade com o serviço; execute em seguida o teste de serviço abaixo.

### Teste a conexão com o serviço

Use o cliente nativo do seu serviço para uma solicitação leve, com os requisitos normais de TLS e autenticação. Para o Redis:

```bash theme={null}
redis-cli -h YOUR_ENDPOINT_HOSTNAME -p 6379 PING
```

`6379` é a porta padrão do Redis. Substitua-a, se necessário, para corresponder à porta do seu endpoint registrado.

Resultado esperado: `PONG`. Este é o `PING` no nível de aplicação do Redis, não um ping de rede ICMP.

![Resolução de hostname e um PONG do Redis bem-sucedido no Shell do projeto.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/shell-proof.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=0cac629de7d995bb6424d2b0d84a1a22)

Resolução de hostname e um PONG do Redis bem-sucedido no Shell do projeto.

Após uma solicitação bem-sucedida, o painel do tunnel passa a mostrar os carimbos de data/hora do tráfego recente.

![Atividade do tunnel após a solicitação Redis bem-sucedida.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/traffic.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=089a5eed1d316701d3ac49647e7c15b5)

Atividade do tunnel após a solicitação Redis bem-sucedida.

## 6. Gerencie chaves de registro

De volta ao painel de tunnels, abra o menu de três pontos ao lado do nome do tunnel e selecione **Manage enrollment key**.

![Abra o gerenciamento de chaves de registro.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/key-menu.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=bb6c5735f27d191245ea425601f8f4fe)

Abra o gerenciamento de chaves de registro.

![Lista de chaves ativas e ações disponíveis.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/keys.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=bb4515355377b012c9b7f0d59a46a436)

Lista de chaves ativas e ações disponíveis.

### Adicione uma chave de registro

Escolha Add enrollment key quando houver um slot disponível. Isso abre a mesma caixa de diálogo Save your enrollment key exibida durante a configuração inicial. Copie a nova chave imediatamente e salve-a com segurança: ela é exibida apenas uma vez.

Se os dois slots de chave estiverem ocupados, identifique a chave a ser revogada ou substituída antes de continuar. Não revogue uma chave às cegas. Retry key delivery serve para uma solicitação interrompida, não para exibir novamente uma chave entregue anteriormente.

### Revogue uma chave de registro

Escolha **Revoke** na chave desejada, confira os detalhes da chave selecionada e escolha **Confirm selected key revocation**. Isso bloqueia novos registros usando essa chave.

> [!WARNING]
>
> Revogar uma chave não desconecta sessões de conector já estabelecidas. Reinicie o conector com uma nova chave para encerrar as sessões existentes.

![Revise e confirme a revogação da chave selecionada.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/revoke.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=6d448ab1dc83729ef72f0678341b4360)

Revise e confirme a revogação da chave selecionada.

![Após a revogação, a contagem de chaves ativas é atualizada. O conector já estabelecido ainda pode estar Online.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/revoked.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=02695158c64bb5c4155f35864888255f)

Após a revogação, a contagem de chaves ativas é atualizada. O conector já estabelecido ainda pode estar Online.

### Atualize um conector após alterar sua chave

Provisione a nova chave por meio do seu gerenciador de segredos aprovado. Reinicie o deployment do conector após a atualização do Secret:

```bash theme={null}
kubectl -n replit-tunnels rollout restart deployment/replit-tunnel
kubectl -n replit-tunnels rollout status deployment/replit-tunnel
```

Confirme **Online** e repita a solicitação de serviço no Shell do projeto. Planeje uma indisponibilidade com a estratégia `Recreate` de réplica única deste exemplo. Não presuma que a revogação por si só encerra uma conexão existente.

## 7. Desconecte e limpe

Quando o conector é interrompido, o tunnel passa a Offline e o endpoint não deve ser tratado como alcançável.

![Tunnel Offline e endpoint Unreachable após desconectar o conector.](https://mintcdn.com/replit/tf-DypNXeTHeMPj_/images/tunnels/offline.png?fit=max\&auto=format\&n=tf-DypNXeTHeMPj_\&q=85\&s=6deb9a3547a92b22a887feb6179614da)

Tunnel Offline e endpoint Unreachable após desconectar o conector.

Para remover o release Helm do conector:

```bash theme={null}
helm uninstall replit-tunnel --namespace replit-tunnels
```

O chart não gerencia o Secret, o namespace, o tunnel do Replit nem os endpoints. Remova-os separadamente somente quando não forem mais necessários. Nunca remova um namespace compartilhado nem o endpoint de outro aplicativo.

## Solução de problemas

### Tunnels indisponível

Peça ao Replit para verificar a habilitação do workspace e a disponibilidade do serviço antes de alterar a configuração do conector ou da rede.

### Falha no pod do conector

Inspecione erros de pull de imagem, agendamento, referências ao Secret e inicialização do contêiner.

### Tunnel offline

Inspecione a configuração de registro e a conectividade de saída do conector.

### Endpoint inalcançável

Verifique o DNS privado, o serviço e a porta de destino, o roteamento, as regras de firewall e quaisquer NetworkPolicies do Kubernetes a partir da rede do conector.

### O teste de conexão é bem-sucedido, mas a consulta falha

Verifique o TLS do banco de dados, as credenciais, as permissões do banco de dados e o caminho de roteamento do sandbox do Replit compatível.

### Destino duplicado

Verifique os endpoints existentes em todo o workspace antes de criar outro registro.

### O hostname não é resolvido

Confirme que você está em um **Shell** de projeto do Replit, no mesmo workspace do endpoint salvo. Verifique o hostname de destino exato e o status do tunnel.

Se o problema persistir, entre em contato com o Replit informando o workspace/projeto e o erro. **Nunca compartilhe a chave de registro.**