# Runtime local

> Desenvolvimento desconectado em loopback, com sessão automática de até 30 dias, simulação de perfis e nenhuma dependência da Plataforma.

Desde a linha 0.5, toda Central roda localmente **sem cadastro na Plataforma**. O runtime local é seguro por construção: só aceita loopback, usa cookies HttpOnly com CSRF e nunca emite identidade operacional.

## Início

```bash
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
npm install
npm run dev
```

O orquestrador:

1. inicia o backend em `127.0.0.1:4000` e o frontend em `127.0.0.1:5173`;
2. gera **dois códigos de uso único**, aleatórios e independentes — um para o navegador e um para automação/seed;
3. abre o navegador já com o código de bootstrap.

O Vite encaminha `/api` ao backend para manter cookies e CSRF na mesma origem.

```bash title="backend/.env"
SERVICE_NAME=minha-central
PORT=4000
NODE_ENV=development
OON_RUNTIME_MODE=local
MONGO_URI=mongodb://localhost:27017/minha-central
APP_CODE=minha-central
```

## Sessão

O primeiro acesso troca o código de uso único por:

- cookie de sessão `HttpOnly`, `SameSite=Strict`;
- cookie CSRF de double-submit;
- sessão local cujo banco armazena **somente hashes** e expiração.

O prazo padrão é de **30 dias**. Reiniciar o processo rotaciona o segredo sem ampliar o prazo. Excluir o banco local inicia um novo período (limitação aceita). `Secure` é adicionado aos cookies quando `OON_LOCAL_HTTPS=true`.

## Perfis

O banner superior permite selecionar **apenas os papéis declarados** em `central.app.json`. A permissão é recalculada no backend.

- O principal técnico é `local:developer`.
- O papel inicial é `developer` quando declarado; senão admin ou o primeiro papel.
- Convites e usuários reais não são criados.
- Apps com tenant usam o contexto virtual fixo `local:tenant`, sem criar tenant persistente nem aceitar tenant arbitrário do cliente.

## Ativação

O estado local é `ativa_local`. O `ActivationGuard` não cria nem consulta instâncias da Plataforma. Isso **não** equivale a uma instância `ativa` publicada.

## Integrações e capabilities

- Use dublês ou credenciais explicitamente fornecidas no `.env` local.
- O Core não busca segredos da Plataforma e não cria Deployment, binding ou entitlement.
- Capabilities de plataforma (PDF, e-mail) **falham fechado** localmente — por exemplo `PDF_RENDERING_UNAVAILABLE`.
- `operationalRequestHeaders` falha com `LOCAL_OPERATION_NOT_SUPPORTED`.
- Métricas de uso não são enviadas.

## Seed e automação

Scripts de seed devem usar **exclusivamente o código de Automação/seed** impresso pelo `npm run dev`. Usar o código do navegador num script invalida a sessão do navegador.

## Encerramento

`Ctrl+C` encerra os dois processos.

> [!DANGER]
> Nunca use `--host 0.0.0.0`, token fixo (`DEV_TOKEN`), proxy externo ou credencial de Deployment para "resolver" um erro local. O startup e a conformance reprovam essas configurações.

## Falhas de startup

O Core falha no startup local quando encontra produção, Kubernetes, identidade operacional, bind não-loopback ou `PUBLIC_APP_URL` externa:

| Código | Causa |
|---|---|
| `LOCAL_RUNTIME_ENV_INVALID` | modo local fora de `NODE_ENV=development` |
| `LOCAL_RUNTIME_PLATFORM_IDENTITY` | identidade de plataforma/Kubernetes presente |
| `LOCAL_RUNTIME_BIND_FORBIDDEN` | bind fora de loopback |

Veja também [Fronteira de segurança local](/docs/seguranca/fronteira-local) e [Troubleshooting](/docs/operacao/troubleshooting).

Fonte: https://sdk.oonapps.com/docs/fundamentos/runtime-local