> For the complete documentation index, see [llms.txt](https://docs.skail.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skail.dev/construir/configurar-e-hospedar/como-configurar-o-runtime.md).

# Como configurar o runtime

As quatro configurações que o runtime precisa para subir, de onde ele as lê e como conferir que deu certo.

## De onde o runtime lê

Na ordem: `appsettings.json`, `appsettings.{DOTNET_ENVIRONMENT}.json` e variáveis de ambiente com prefixo `SKAIL_`. No `appsettings` as chaves ficam na seção `skail`, em minúsculo, sem o prefixo. Variável de ambiente sobrescreve arquivo.

{% tabs %}
{% tab title="Variáveis de ambiente" %}

```bash
SKAIL_WORKLOAD=faturamento:v1.0.0
SKAIL_NAMESPACE=<namespace do environment>
SKAIL_KEY=<chave do environment>
SKAIL_SIDECAR=<endereço do skail>
```

{% endtab %}

{% tab title="appsettings.Development.json" %}

```json
{
  "skail": {
    "workload": "faturamento:v1.0.0",
    "namespace": "<namespace do environment>",
    "key": "<chave do environment>",
    "sidecar": "<endereço do skail>"
  }
}
```

{% endtab %}
{% endtabs %}

Chave, namespace e endereço vêm do environment no portal. Não versione `SKAIL_KEY`; em produção, use o mecanismo de segredos do seu host (variáveis do container, Key Vault, secrets do Kubernetes).

## As quatro variáveis

| Variável          | Formato                                             | O que faz                                                                                                                                                                                                                                                                                                                                           |
| ----------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SKAIL_WORKLOAD`  | `nome:versao`, por exemplo `faturamento:v1.0.0`     | Identifica a aplicação e a versão. O runtime monta o endereço de cada function e command como `nome:versao/NomeDoMetodo`; precisa bater com o workload criado no portal e com o caminho usado no trigger. Mudar a versão muda todos os endereços: ver [Versionamento](/aprender/fundamentos/versionamento-de-codigo-com-execucoes-em-andamento.md). |
| `SKAIL_NAMESPACE` | `tenant/environment` (ids, como aparecem no portal) | Identifica o environment. Enviado em toda chamada no header `skail-namespace`.                                                                                                                                                                                                                                                                      |
| `SKAIL_KEY`       | chave do environment                                | Autentica o runtime. Enviada no header `skail-key`. Segredo.                                                                                                                                                                                                                                                                                        |
| `SKAIL_SIDECAR`   | host ou URL                                         | Endereço do skail com quem o runtime conversa. Use o valor fornecido para o environment, como a chave e o namespace.                                                                                                                                                                                                                                |

Com essas quatro a aplicação sobe e passa a receber execuções.

## A URL base da API HTTP

Quem dispara funções (`/trigger/...`) e eventos (`/api/v1/fire/...`) de fora usa a URL base da API do environment, com os mesmos `skail-key` e `Skail-namespace`. Essa URL não é lida pelo runtime; ela é usada pelo seu código de integração (controllers, webhooks, jobs). Nos exemplos da doc ela aparece como `SKAIL_BASE_URL`.

## Verificando a configuração

Depois de configurar, rode a aplicação. Ela deve subir sem erro e ficar em espera por trabalho; dispare uma function pela API HTTP e a execução aparece no Monitor do environment. Se algo falhar, o log do processo mostra a causa:

| Sintoma                                              | Causa provável                                                                                                                                                                                     |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Unauthenticated` ou HTTP 401 no log                 | `SKAIL_KEY` vazia ou inválida, ou `SKAIL_NAMESPACE` de outro environment.                                                                                                                          |
| `There is not Skail runtime available!`              | Faltou `builder.UseSkail()` (ou `services.AddSkail()`), ou o assembly não tem `[assembly: VisibleToSkailPlatform]`, ou o pacote de build (`Skail.Platform.Runtime.Build`) não rodou na compilação. |
| Execução aparece no Monitor mas não avança (Na fila) | `SKAIL_WORKLOAD` do processo diferente do `nome:versao` usado no caminho do trigger.                                                                                                               |
| Trigger aceito mas a execução não aparece no Monitor | O sistema que disparou usou o namespace de outro environment; procure a execução lá.                                                                                                               |
| `Message image mismatch`                             | `SKAIL_WORKLOAD` do processo diferente do workload para o qual a execução foi endereçada.                                                                                                          |
| Runtime não conecta                                  | `SKAIL_SIDECAR` errado (host, porta ou esquema).                                                                                                                                                   |

Mais casos em [Troubleshooting](/operar/troubleshooting.md).

## Próximos passos

[Como hospedar](/construir/configurar-e-hospedar/como-hospedar-worker-service-asp.net-core-container-kubernetes-azure.md) mostra onde colocar essas variáveis em Worker Service, container e Kubernetes. [Variáveis de ambiente do runtime](/construir/variaveis-de-ambiente-do-runtime.md) é a referência. [Ambientes e promoção](/operar/readme.md) explica o que muda entre dev, homologação e produção.