> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Devin Connect
> O Devin Connect dá ao Devin acesso privado a sistemas internos: implante um gateway como proxy de política, acessado por um túnel outbound-only ou pelo AWS PrivateLink.
O Devin Connect está atualmente em **acesso antecipado**. Recursos e configurações podem mudar. Entre em contato com a equipe de conta da Cognition se tiver interesse no acesso antecipado.
O Devin Connect dá às sessões do Devin acesso a sistemas internos (controle de código-fonte, registros de artefatos, APIs internas) sem exigir a criação de um caminho de rede para cada recurso. Você implanta um gateway leve dentro da sua própria rede, e o Devin o acessa por meio de uma conexão privada.
**Versão atual do gateway: v0.0.2**
O que o Devin Connect faz
O Devin Connect tem duas partes, configuradas de forma independente.
**Um proxy de política dentro da sua rede.** O Gateway é um proxy HTTP CONNECT com uma lista de permissões de negação por padrão. Ele recebe uma requisição de conexão para `host:port`, confere se ela corresponde às suas rotas, resolve o nome com o seu próprio DNS, abre a conexão com o destino e retransmite bytes opacos. Nem o Gateway nem a infraestrutura do Devin terminam ou inspecionam o TLS entre a VM do Devin e o seu serviço, e toda conexão é registrada em log de auditoria.
**Um caminho privado do Devin até esse proxy.** O Devin precisa alcançar o proxy sem que nenhum dos lados exponha nada à internet pública. Há duas maneiras de fazer isso, e o proxy se comporta de forma idêntica nas duas:
* **Túnel reverso**: o Gateway abre uma conexão de saída até um endpoint do lado do Devin via TLS, e o Devin envia as requisições de conexão de volta por esse túnel. Nada é aberto para entrada na sua rede, e nenhuma integração com provedor de nuvem é necessária.
* **AWS PrivateLink**: você coloca um Network Load Balancer e um VPC Endpoint Service na frente do Gateway, e a Cognition o consome com um Interface VPC Endpoint na VPC do seu dedicated tenant. O tráfego permanece no backbone da AWS e o Devin se conecta diretamente ao Gateway por IPs privados.
Escolha um nas abas de [Modos de conectividade](#connectivity-modes) abaixo; todo o restante desta página vale para os dois.
Propriedades válidas nos dois casos:
* **VPC single-tenant dedicada.** O seu Devin deployment roda na própria VPC (veja o [modelo de deployment dedicado ao cliente](/pt-BR/enterprise/deployment/overview#customer-dedicated-deployment-architecture)). As VMs do Devin enviam o tráfego dos destinos roteados em direção ao Gateway por meio do controle de saída configurado pela Cognition.
* **Negação por padrão, aplicada duas vezes.** As rotas são aplicadas no Gateway e no lado do Devin, de modo que uma alteração apenas de configuração em um dos lados não amplia o acesso. Rotear um destino nunca amplia as permissões de uma sessão: o [security profile](/pt-BR/product-guides/security-profiles) da sessão ainda precisa permitir o acesso.
* **O TLS da sua aplicação é ponta a ponta.** O Gateway encaminha fluxos de bytes opacos.
* **O DNS permanece dentro da sua rede.** Os destinos das rotas são resolvidos pelos seus resolvedores (por padrão, o resolvedor de sistema do host do Gateway, ou nameservers que você configurar).
* **Um único deployment cobre todos os destinos roteados.** Você adiciona hostnames e intervalos IPv4 nas configurações do Devin, sem precisar montar uma estrutura específica para cada serviço.
Escolhendo um modo de conectividade
| | Túnel reverso | AWS PrivateLink |
| - | - | - |
| Exposição de entrada | Nenhuma; o Gateway inicia a conexão | Nenhuma na internet; o endpoint service é acessível apenas pela conta da Cognition |
| Requisitos de nuvem | Qualquer rede com saída para `:443` | O Gateway deve rodar na AWS, com um NLB e um VPC Endpoint Service |
| Autenticação da conexão | Token de inscrição emitido pelo Devin | Principal da AWS account no endpoint service |
| Caminho do tráfego | Internet pública (TLS) ou o attachment da sua VPN/Transit Gateway | Backbone da AWS |
| Entre regiões | Não se aplica | Compatível, se você ativar no endpoint service |
Nos dois modos, a configuração é feita no aplicativo web do Devin, na página "Devin Connect" das configurações do enterprise, disponível para usuários com a função de administrador adequada. Uma conta pode ter vários gateways, cada um roteando seu próprio grupo de destinos: no máximo um gateway de túnel reverso e qualquer quantidade de gateways PrivateLink.
1. Escolha "Add gateway", dê um nome a ele e selecione uma conexão: "Tunnel" para o túnel reverso ou "Direct" para o AWS PrivateLink. No caso de "Direct", informe também o nome DNS e a porta do interface endpoint (consulte a aba [AWS PrivateLink](#connectivity-modes)).
2. No cartão do gateway, escolha "Add destination" para cada destino que o Devin deve acessar por meio dele: um hostname exato ou um endereço IPv4 ou CIDR, como `10.20.0.0/16`. Curingas não são suportados. Cada destino pode pertencer a apenas um gateway.
3. Para um gateway de túnel, escolha "Generate token" para inscrevê-lo. O token de inscrição é exibido uma única vez, nunca é armazenado pelo Devin e pode ser rotacionado ou revogado a qualquer momento com "Regenerate token". Gateways diretos não têm túnel para autenticar, então esta etapa não se aplica a eles.
4. Para um gateway de túnel, copie o trecho de código de deployment da sua plataforma (Docker, Kubernetes, AWS ECS, Terraform em ECS ou EC2, ou um host Linux). O trecho de código contém um `config.yaml` pronto para execução, gerado a partir dos destinos do gateway; por isso, copie-o novamente sempre que alterar os destinos.
O cartão de cada gateway de túnel também mostra se ele está conectado no momento e quando foi visto pela última vez.
Destinos por hostname e IPv4
* **Hostnames** são correspondidos pelo nome ao qual a sessão se conecta, obtido do TLS SNI ou do header HTTP `Host`. Por isso, eles roteiam apenas tráfego TLS e HTTP simples. O Gateway resolve o nome usando o seu DNS.
* **Endereços IPv4 e CIDRs** são correspondidos pelo IP de destino da conexão e, portanto, roteiam qualquer protocolo TCP, incluindo conexões SSH e de banco de dados. O Devin não resolve seus nomes internos para essas rotas: as sessões se conectam por endereço IP, ou você fornece a resolução de nomes no ambiente, por exemplo, com entradas em `/etc/hosts` configuradas no seu [blueprint](/pt-BR/onboard-devin/environment/blueprints).
No `config.yaml` do próprio Gateway, permita destinos IPv4 com regras `ipv4`; o trecho de código gerado já as inclui.
Modos de conectividade
O Gateway abre N túneis TLS de saída até o endpoint do seu tenant, `.gateway.devinenterprise.com:443`. Você nunca abre uma porta de entrada. Um túnel registrado transporta apenas os fluxos que o lado do Devin abre em direção ao seu Gateway; ele não é um caminho de entrada para o Devin.
A inscrição funciona assim:
1. O Devin emite para você um token de inscrição para o gateway do túnel na página de configurações "Devin Connect".
2. Você instala o token no host do Gateway, no caminho indicado por `tunnel.auth_token_file`.
3. O Gateway se conecta a `.gateway.devinenterprise.com:443`, verifica o certificado de servidor da borda do Devin e apresenta o token.
4. A borda valida o token (comparação em tempo constante com um digest armazenado; o token bruto nunca é armazenado no lado do Devin) e registra o túnel. A partir daí, as conexões iniciadas pelo lado do Devin para os destinos do gateway passam por ele.
O túnel é configurado com uma seção `tunnel` e sem endereço `listen`, de modo que o host do Gateway não expõe nenhuma porta de proxy:
```yaml theme={null}
tunnel:
endpoint: acme.gateway.devinenterprise.com:443
gateway_id: gw-1
# Token de inscrição, em uma única linha; é relido a cada tentativa de conexão,
# para que possa ser rotacionado sem reiniciar o serviço.
auth_token_file: /etc/devin-gateway/tunnel-token
# carrier: websocket # padrão; use `direct` para desativar o enquadramento WebSocket.
# ca_file: corp-ca.pem # somente se um proxy corporativo de inspeção TLS reassinar
# # a conexão de borda.
# egress_proxy: # proxy HTTP CONNECT de saída do cliente, se necessário.
# addr: proxy.corp.example:3128
```
| Campo | Descrição |
| - | - |
| `endpoint` | O endpoint do seu tenant, `.gateway.devinenterprise.com:443`. |
| `gateway_id` | Identificador desta instância do Gateway, usado em logs e métricas. |
| `auth_token_file` | Caminho para o arquivo de uma linha com o token de inscrição. |
| `carrier` | `websocket` (padrão) ou `direct`. Ambos executam o mesmo protocolo dentro da mesma conexão TLS; o `websocket` adiciona enquadramento HTTP Upgrade para caminhos de saída que não permitem TLS puro. |
| `ca_file` | Pacote de CAs em PEM para verificar o certificado da borda do Devin; necessário apenas quando há um corporate TLS-inspection proxy que reassina certificados. |
| `egress_proxy` | Seu proxy HTTP CONNECT de saída (`addr` e, opcionalmente, `auth`), caso o tráfego de saída precise passar por um. |
| `connection_pool` | `size` (1 a 16 túneis, recarregável) e `max_streams_per_connection` (2 a 2048). |
Itens adicionais de verificação para este modo:
* Libere a saída do Gateway para `.gateway.devinenterprise.com:443` e para os serviços internos da sua lista de permissões. Não é necessário criar regras de entrada.
* Armazene o token de inscrição no seu gerenciador de secrets e monte-o como arquivo. Nunca o embuta em images, em configurações sob version control ou em logs; o Gateway nunca o registra em log.
* Opcionalmente, informe à Cognition suas faixas CIDR de saída para restringir o endpoint público no nível de IP (defesa em profundidade; o token de inscrição continua sendo o mecanismo de autenticação).
O Gateway disponibiliza o proxy de lista de permissões em um listener HTTP CONNECT local, e o Devin alcança esse listener via PrivateLink:
1. Você implanta o Gateway em uma sub-rede privada na sua AWS VPC com um endereço `listen`.
2. Você coloca um Network Load Balancer na frente dele apontando para a porta do listener e cria um VPC Endpoint Service a partir desse NLB.
3. Você adiciona a AWS account da Cognition como principal permitido e envia à Cognition o nome do endpoint service.
4. A Cognition cria um Interface VPC Endpoint na VPC do seu dedicated tenant e envia para você o nome DNS dele. Isso envia uma requisição de conexão ao seu endpoint service, que você aprova (ou que é aceita automaticamente, caso você tenha ativado essa opção no serviço).
5. Na página de configurações "Devin Connect", você adiciona um gateway com a conexão "Direct", informa o nome DNS do interface endpoint e a porta do listener e adiciona os destinos que ele deve atender. Coloque os mesmos destinos nas `routes` do Gateway.
Como o endpoint service só pode ser consumido pela account da Cognition e o NLB é interno à sua VPC, não existe listener público. O acesso é autorizado pelo principal da AWS no endpoint service e pela própria lista de permissões com negação por padrão do Gateway.
A configuração do Gateway define `listen` com a porta para a qual o NLB direciona o tráfego:
```yaml theme={null}
schema_version: 1
admin_listen: 0.0.0.0:9090
# O listener HTTP CONNECT local para o qual o NLB direciona o tráfego.
listen: 0.0.0.0:8443
routes:
- name: devin
rules:
- hostname: "git.corp.example"
- hostname: "api.corp.example"
ports: [443]
```
O que fornecer à Cognition:
* O nome do VPC Endpoint Service, por exemplo `com.amazonaws.vpce.us-west-2.vpce-svc-0abc123`.
* A porta do listener exposta pelo NLB.
* Confirmação de que a AWS account da Cognition é um principal permitido.
* Se o endpoint service oferece suporte à região em que o seu tenant do Devin é executado, caso ela seja diferente da região do Gateway.
Itens adicionais do checklist para esse modo:
* Execute os targets do NLB em várias Zonas de Disponibilidade.
* Se os seus serviços estiverem em uma região diferente da do seu tenant do Devin, ative o suporte entre regiões no endpoint service. As etapas são as mesmas descritas em [Rede privada do Dedicated Deployment](/pt-BR/enterprise/deployment/dedicated_saas_private_networking#cross-region-privatelink-if-your-services-are-in-a-different-region).
Referência de configuração
O Gateway é configurado por meio de um único arquivo YAML, validado de forma estrita e fail-closed: uma configuração que não passa na validação é rejeitada por completo e a configuração anterior permanece ativa. O arquivo é consultado a cada 5 segundos e recarregado a quente.
```yaml theme={null}
schema_version: 1
# listener de administração (/healthz, /readyz, /metrics).
admin_listen: 127.0.0.1:9090
# Listener do plano de dados. Somente no modo PrivateLink (direct): obrigatório sem
# uma seção `tunnel`, rejeitado quando há uma.
# listen: 0.0.0.0:8443
# DNS do cliente para resolver os destinos das rotas (resolver do sistema, se omitido).
dns:
nameservers: ["10.0.0.2:53"]
timeout: 5s
# Lista de permissões com negação por padrão. As Rules aceitam hostnames e CIDRs ipv4/ipv6.
# Portas omitidas significam qualquer porta.
routes:
- name: scm
rules:
- hostname: "git.corp.example"
- hostname: "artifacts.corp.example"
ports: [443]
- name: internal-api
rules:
- hostname: "api.corp.example"
ports: [443]
- name: build-hosts
rules:
- ipv4: "10.20.0.0/16"
ports: [22]
# Túnel de saída para a borda do lado do Devin. Omita no modo PrivateLink.
tunnel:
endpoint: acme.gateway.devinenterprise.com:443
gateway_id: gw-1
auth_token_file: /etc/devin-gateway/tunnel-token
```
Rotas (lista de permissões)
Tudo o que não corresponder a uma rota é negado; uma lista de rotas vazia nega tudo. As rotas são avaliadas em ordem e a primeira correspondência prevalece.
| Campo | Descrição |
| - | - |
| `name` | Nome único da rota; aparece nos logs de auditoria de conexão. |
| `rules` | Regras de correspondência de destino; a rota corresponde se qualquer uma das regras corresponder. A correspondência de `hostname` não diferencia maiúsculas de minúsculas. Regras CIDR `ipv4`/`ipv6` correspondem apenas a conexões feitas com IP literal. |
| `ports` | Portas de destino permitidas. Se omitido, qualquer porta é permitida. |
| `upstream_proxy` | Proxy HTTP CONNECT upstream opcional para encadear nesta rota (`addr`, `auth` opcional). |
Os hostnames são comparados conforme solicitados, antes da resolução de DNS, de modo que a policy se aplica ao nome, e não ao IP para o qual ele porventura resolva.
Listeners
| Campo | Descrição |
| - | - |
| `admin_listen` | Listener de administração para `/healthz`, `/readyz` e `/metrics`. |
| `listen` | Listener HTTP CONNECT do plano de dados. Defina-o no modo PrivateLink; omita-o no modo túnel, em que as requisições de conexão chegam somente pelo túnel autenticado. |
| `dial_timeout` | Timeout para conexão com destinos upstream (padrão 10s). |
DNS
| Campo | Descrição |
| - | - |
| `nameservers` | Servidores DNS (`ip:port`) usados para resolver os destinos das rotas. Se omitido, é usado o resolvedor do sistema do host do Gateway, que é o caso mais comum, já que o Gateway é executado dentro da sua rede. |
| `timeout` | Tempo limite por consulta (padrão de 5s). |
Rotas por hostname são recusadas se o seu DNS as resolver para endereços de loopback, link-local ou não especificados, de modo que um nome na lista de permissões não pode ser direcionado ao próprio host do Gateway nem a um endpoint de metadados.
Executando o Gateway
O Gateway é distribuído como uma imagem de contêiner que contém um único binário estático (a imagem é construída `FROM scratch` e executada com um usuário não root). Monte a configuração em `/etc/devin-gateway/config.yaml` e, no modo túnel, o arquivo de token no caminho indicado por `tunnel.auth_token_file`.
```bash theme={null}
gateway serve --config /etc/devin-gateway/config.yaml
gateway validate-config --config config.yaml # validação estrita da config
gateway doctor --config config.yaml # resumo de diagnóstico em JSON
```
Endpoints operacionais em `admin_listen`:
* `/healthz` para liveness do processo.
* `/readyz` para prontidão.
* `/metrics` para métricas do Prometheus.
Checklist de deployment para ambos os modos:
* Execute o Gateway em uma sub-rede privada.
* Integre `/healthz` e `/readyz` aos health checks do seu orquestrador.
* Mantenha os destinos de cada gateway nas configurações do Devin e as rotas na configuração do respectivo Gateway em sincronia; um destino permitido em apenas um dos lados não fica acessível.
Logging e integração com SIEM
O Gateway envia os logs para o stdout. Quando o stdout não é um terminal (o caso normal em um contêiner), os logs são emitidos como linhas JSON, prontos para consumo por máquinas. Para levá-los ao seu SIEM, use o pipeline de logs padrão da sua plataforma: o driver de log do contêiner ou o agente (CloudWatch Logs, Fluent Bit, Vector, agente do Datadog e assim por diante) coleta o stdout e o encaminha como faria com os logs de qualquer outra carga de trabalho. O Gateway não precisa de nenhuma configuração específica de SIEM.
Os eventos de auditoria de conexão incluem:
* `conn_open` e `conn_close`, com host e porta de destino, nome da rota correspondente, endereço do cliente, bytes transferidos em cada direção e duração.
* `deny`, com o destino e o motivo (por exemplo, nenhuma rota correspondente na lista de permissões).
O token de inscrição nunca é registrado em log, assim como o conteúdo do payload.
Para conectividade privada por serviço sem um Gateway, consulte [Rede privada do Dedicated Deployment](/pt-BR/enterprise/deployment/dedicated_saas_private_networking). Para uma visão geral dos modelos de deployment, consulte a [Visão geral de deployment](/pt-BR/enterprise/deployment/overview).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.