# 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.

## 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`;
* `vpcConfig`.

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

## 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tunnelhub.io/cli/tunnelhub-yml.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.