> For the complete documentation index, see [llms.txt](https://docs.tunnelhub.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tunnelhub.io/cli/tunnelhub-yml.md).

# tunnelhub.yml

`tunnelhub.yml` é o manifesto local usado pelos fluxos de scaffold, build e deploy de projetos TunnelHub.

Em geral, ele responde três perguntas:

* qual recurso esse projeto representa;
* como o artefato deve ser gerado ou publicado;
* qual configuração de runtime acompanha a automação.

## Fonte de verdade pública

Use esta página como referência prática e o schema publicado no SchemaStore como referência estrutural:

* `https://json.schemastore.org/tunnelhub.json`

Se você usa editor com suporte a JSON Schema em YAML, vale associar esse schema ao arquivo para ganhar validação e autocomplete. Alguns campos recém-lançados podem aparecer nesta documentação antes da atualização do schema publicado.

## Exemplo mínimo

```yaml
service:
  type: automation
  uuid: 11111111-2222-3333-4444-555555555555

configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs22.x
  memorySize: 512
  timeout: 30

package:
  artifact: dist/artifact.zip
```

## Exemplo com campos opcionais

```yaml
service:
  type: automation
  uuid: 11111111-2222-3333-4444-555555555555
  region: us-east-1

configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs22.x
  memorySize: 1024
  timeout: 120
  lambdaLayers:
    - arn:aws:lambda:us-east-1:123456789012:layer:shared-lib:1
  environmentVariables:
    LOG_LEVEL: info
  vpcConfig:
    subnetIds:
      - subnet-aaaa1111
    securityGroupIds:
      - sg-bbbb2222
    assignPublicIp: false

package:
  artifact: dist/artifact.zip
```

## Bloco `service`

Esse bloco identifica o tipo de recurso e o vínculo com a plataforma.

Campos mais importantes:

* `type`: normalmente `automation` no fluxo público atual;
* `uuid`: UUID da automação no TunnelHub;
* `region`: opcional em cenários que precisam declarar região explicitamente.

Durante `create-automation`, a CLI escreve `service.uuid` automaticamente no template baixado.

## Bloco `configuration`

Esse bloco orienta o runtime do projeto.

Campos mais comuns:

* `runtimeEngine`: como `LAMBDA` ou `ECS_FARGATE`;
* `entrypoint`: função ou arquivo de entrada esperado pelo bundle;
* `runtime`: runtime Node.js alvo;
* `memorySize`: memória esperada;
* `timeout`: tempo máximo de execução.

Também podem aparecer campos opcionais, como:

* `lambdaLayers`;
* `environmentVariables`;
* `runInVpc`;
* `sqlTables`;
* `vpcConfig`.

O schema publicado é a melhor referência para validar combinações e tipos desses campos.

### Tabelas de Apoio

Para usar [Tabelas de Apoio](/produto/sql-tables.md) em automações, habilite o bloco `sqlTables`:

```yaml
configuration:
  runtimeEngine: LAMBDA
  entrypoint: index.handler
  runtime: nodejs24.x
  memorySize: 1024
  timeout: 60
  runInVpc: true
  sqlTables:
    enabled: true
```

Quando `sqlTables.enabled` é `true`, a automação precisa usar `runtime: nodejs24.x`, `runInVpc: true` e `runtimeEngine: LAMBDA` ou `ECS_FARGATE`.

Nota: a documentação deste campo pode preceder a atualização do schema publicado no SchemaStore. Até que `tunnelhub.json` seja atualizado, editores podem não validar ou autocompletar `configuration.sqlTables`.

## Bloco `package`

Esse bloco é especialmente importante para o deploy da CLI.

Campo crítico:

* `artifact`: caminho do artefato ZIP que será enviado para a plataforma.

Sem esse valor, `deploy-automation` não consegue concluir o fluxo de publicação.

## Quem usa cada parte do arquivo

* **CLI scaffold**: preenche `service.uuid`.
* **CLI deploy**: lê `service.uuid` e `package.artifact`.
* **SDK build tooling**: usa `configuration` para empacotar o projeto corretamente.

## O que é obrigatório na prática

Para o fluxo público atual de automações, o contrato mínimo é:

* `service.type`;
* `service.uuid`;
* `configuration.runtimeEngine`;
* `configuration.entrypoint`;
* `configuration.runtime`;
* `configuration.memorySize`;
* `package.artifact`.

## Erros comuns

* **`tunnelhub.yml` ausente**: execute o deploy na raiz do projeto correto.
* **`service.uuid` ausente**: recrie o projeto com `create-automation` ou informe `--automation` no deploy.
* **`package.artifact` ausente**: configure o caminho do ZIP antes do deploy.
* **artefato em caminho errado**: confirme se o arquivo realmente existe no caminho configurado.
* **bundle incompleto**: garanta que o artefato gerado contenha o que o runtime precisa.

## Relação com o fluxo de trabalho

O ciclo mais comum é:

1. `create-automation` gera o projeto e grava `service.uuid`;
2. o projeto gera o artefato configurado;
3. `deploy-automation` lê `tunnelhub.yml` e publica a nova versão.

Consulte também [Comandos e referência](/cli/commands.md) e [Criando sua primeira automação](/primeiros-passos/creating-your-first-automation.md).