Referência de variáveis de ambiente
Referência de variáveis de ambiente
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Quase tudo o que configura o Loom é um campo de settings: a variável de ambiente LOOM_<FIELD> de um campo em server.settings.Settings, listada com seu valor padrão e seu significado na referência de configuração gerada. Esta página cobre o restante: as variáveis lidas diretamente com os.environ (ou um ${VAR} do shell) pelo servidor, pela CLI, pelos SDKs, pelos plugins, pela imagem de contêiner, pelos arquivos compose e pelos scripts de operação. As variáveis LOOM_* estão listadas em NON_SETTINGS_ENV (server/settings/_env.py) ou, no caso de uma família como os segredos de assinatura de webhook, em NON_SETTINGS_ENV_PREFIXES, e o aviso de variável desconhecida do servidor ignora essas variáveis; tests/unit/test_environment_reference.py mantém essas listas e esta página sincronizadas.
Servidor
| Variável | Lida por | Padrão | Significado |
|---|---|---|---|
OPENAI_API_KEY |
server/embedding/openai.py, server/llm/openai.py |
não definida | Chave do embedder e do LLM da OpenAI. Ausente enquanto um modelo da OpenAI está configurado: o embedder recorre ao embedder falso de n-gramas com um log de ERROR, o LLM recorre ao cliente falso, e loom doctor emite um aviso. |
ANTHROPIC_API_KEY |
server/llm/anthropic.py |
não definida | Chave do provedor de LLM da Anthropic (LOOM_LLM_PROVIDER=anthropic, ou inferido a partir de um modelo claude*). |
GEMINI_API_KEY, GOOGLE_API_KEY |
server/embedding/gemini.py |
não definida | Chave do embedder do Gemini; vale a primeira que estiver definida. |
COHERE_API_KEY |
server/core/provider_keys.py |
não definida | Chave do provedor de rerank hospedado. Sem ela, o reranker registra um aviso e devolve os candidatos na ordem de entrada (fail-open). |
LOOM_EMBEDDING_API_KEY |
server/core/provider_keys.py |
não definida | Chave do provedor de embedding compatible (LOOM_EMBEDDING_PROVIDER=compatible); /v1/health e loom doctor informam que ela está ausente. |
LOOM_ENV_FILE |
server/core/env_file.py, server/cli/app.py |
.env |
O arquivo env que Settings lê e que a CLI loom carrega no ambiente. Vazio para nenhum. |
LOOM_SETTINGS_FILE |
server/core/env_file.py |
não definida (nenhum) | O arquivo de configurações YAML que Settings lê abaixo do arquivo env e do ambiente (referência de configuração). Um arquivo indicado que não existe impede a inicialização. Lido do ambiente ou, na falta, do arquivo env; um valor vazio no ambiente não lê nenhum arquivo, independentemente do que o arquivo env diga. |
LOOM_INSTANCE_LABEL |
server/observability/instance.py |
não definida | Um rótulo para este processo em cada linha do ledger (até 64 caracteres). Um processo iniciado sem ele e sem LOOM_DEPLOYMENT=1 (um campo de configurações que os arquivos compose fornecidos definem) se recusa a iniciar, de modo que toda linha seja atribuível. |
XDG_RUNTIME_DIR |
server/core/runtime_files.py |
não definida | Onde os processos web de um servidor guardam seus arquivos compartilhados (a tabela de rate limit) quando LOOM_RUNTIME_DIR não está definida: o primeiro entre $XDG_RUNTIME_DIR/loom, /run/loom e /tmp/loom-<uid> que seja, ou possa ser criado como, um diretório que só esse usuário possa acessar; com vários processos web e nenhum desses diretórios, scripts/serve.sh inicia um quando ele mesmo escolheu a contagem e, caso contrário, para e os nomeia. scripts/serve.sh faz essa escolha uma vez e a exporta como LOOM_RUNTIME_DIR. |
HOSTNAME |
server/observability/instance.py |
o nome do host do sistema | Nome de host de reserva no id de instância hostname:pid. |
POD_NAMESPACE, POD_NAME |
server/core/provider_process.py |
não definida | O namespace e o nome deste pod (o chart os define a partir da downward API). O líder dos workers retira o participante de provedor de um pod perdido quando a API naquele namespace deixa de ter o pod ou o tem com falha. |
KUBERNETES_SERVICE_HOST, KUBERNETES_SERVICE_PORT |
server/core/provider_process.py |
definidas pelo Kubernetes | O servidor de API que a verificação de pod perdido consulta, com o token da service account. |
NODE_OPTIONS |
server/code/workers/scip_ts_delta.py, scip_py_delta.py |
não definida | Repassada ao subprocesso do indexador da camada do compilador; todas as outras variáveis desse subprocesso são definidas pelo worker. |
SCIP_ENV_JSON |
server/code/workers/scip_py_delta.py |
não definida | Repassada ao indexador Python da camada do compilador. |
PATH |
server/code/workers/scip_go_delta.py |
herdada | Pesquisada em busca da toolchain Go e dos binários do indexador; o subprocesso recebe seu próprio PATH. |
LOOM_WEBHOOK_SECRET_<ORG>__<NAME> |
server/core/webhooks.py |
não definida | Um segredo de assinatura de webhook, nomeado pelo secret_ref de um webhook de memória ou pelo webhook_secret_ref de uma caixa de entrada de tarefas; ORG é o id da organização codificado como em webhooks da caixa de entrada de tarefas. Um prefixo whsec_ indica uma chave em base64, cujos espaços em branco são descartados. Se não estiver definido, se um valor whsec_ for vazio ou não for base64, ou se um valor não for UTF-8, o segredo não é utilizável: os eventos de webhook de memória ficam em espera (mortos após 2.5 dias) e os avisos de uma caixa de entrada de tarefas ficam retidos; o servidor emite um aviso uma vez, nomeando a variável. O aviso de variável desconhecida ignora todo nome com esse prefixo. |
A seleção de provedores em si (LOOM_EMBEDDING_MODEL, LOOM_LLM_PROVIDER,
LOOM_LLM_MODEL) faz parte das configurações; veja
Implantação e
Arquitetura de LLM.
Imagem de contêiner e uvicorn
Lidas por scripts/serve.sh, o comando da imagem, que inicia o uvicorn. Ele as
obtém apenas do seu ambiente, não de .env nem de LOOM_ENV_FILE (o env_file: do compose
as define no ambiente), exceto os campos de configuração
LOOM_WEB_WORKERS, LOOM_TRUSTED_PROXIES e LOOM_RUNTIME_DIR, que ele
resolve conforme o servidor os carrega: o ambiente, depois o arquivo de env, depois o
arquivo de configurações. As variáveis UVICORN_<OPTION> do próprio uvicorn não
são lidas: a camada web se recusa a iniciar enquanto houver uma definida para uma opção do uvicorn que
scripts/serve.sh não repassa:
| Variável | Padrão | Significado |
|---|---|---|
PORT |
7777 |
A porta em que o uvicorn faz o bind dentro do contêiner. |
LOOM_LISTEN_HOST |
127.0.0.1 |
uvicorn --host: o endereço em que ele escuta. A imagem define 0.0.0.0; LOOM_BIND_HOST continua sendo o endereço lido pelas verificações de inicialização, e scripts/serve.sh o define como um endereço de escuta não loopback quando o ambiente não o define (sobrescrevendo um valor do arquivo de env ou do arquivo de configurações). |
LOOM_WEB_WORKERS |
um por CPU, até 8 | uvicorn --workers. Se não definido, um por CPU que o contêiner pode usar (seu cpuset, reduzido por uma cota de CPU), no máximo um por GiB de memória e no máximo 8. Os arquivos compose o definem, a menos que .env indique uma contagem: 2 em deploy/standalone e na stack de desenvolvimento, 1 nas stacks cloud e colour. Também é um campo de configurações, pelo qual o limitador de taxa divide os orçamentos. |
LOOM_UVICORN_LOOP |
asyncio |
uvicorn --loop: asyncio, auto ou uvloop. O uvloop faz fork do processo inteiro a cada git spawn, o que trava seu loop. |
LOOM_TRUSTED_PROXIES |
127.0.0.1 |
uvicorn --forwarded-allow-ips: os peers cujos X-Forwarded-For/-Proto são aplicados. |
LOOM_GRACEFUL_SHUTDOWN_S |
10 |
uvicorn --timeout-graceful-shutdown: por quanto tempo um processo em parada drena as requisições. |
LOOM_KEEP_ALIVE_S |
5 |
uvicorn --timeout-keep-alive: por quanto tempo uma conexão ociosa permanece aberta. Atrás de um balanceador de carga que reutiliza conexões, deve ser maior que o timeout de ociosidade dele. |
Argumento de build: LOOM_BUILD_COMMIT (incorporado à imagem como LOOM_BUILD_COMMIT,
informado como build_commit). A imagem sempre inclui o embedder local de CPU e seu
modelo padrão, e define LOOM_LOCAL_EMBEDDING_MODEL_DIR=/app/models. Os demais
ARGs fixam versões de toolchain e checksums dos indexadores da camada do compilador
(GO_VERSION, NODE_VERSION, SCIP_GO_VERSION, SCIP_CLANG_VERSION, seus
valores *_SHA256* e LLVM_SIGNER_FPR, a impressão digital da chave de assinatura do LLVM);
scripts/install-code-toolchains.sh fixa as ferramentas que instala com o npm
(scip-typescript, scip-python e os gerenciadores de pacotes).
Arquivos Compose
| Variável | Lida por | Padrão | Significado |
|---|---|---|---|
LOOM_CH_HOST_PORT, LOOM_CH_NATIVE_HOST_PORT |
dev/docker-compose.dev.yml, dev/ci_start_clickhouse.sh |
8123, 9000 |
Portas do host que o ClickHouse local publica (HTTP e nativa). |
LOOM_CH_CONTAINER |
dev/ci_start_clickhouse.sh |
loom-ch |
Nome do contêiner, para que um segundo ClickHouse (um por worktree) rode ao lado do primeiro. |
LOOM_COLOUR, LOOM_COLOUR_PORT |
dev/docker-compose.colour.yml |
obrigatória | Qual cor (blue ou green) e qual porta do host (7781 ou 7782) um projeto blue/green usa. |
LOOM_CLICKHOUSE_IMAGE |
compose.yaml, dev/ci_start_clickhouse.sh |
clickhouse/clickhouse-server:latest |
A imagem do ClickHouse que a stack executa. O arquivo compose de um bundle de release usa como padrão a versão com a qual o bundle foi construído e teve o esquema verificado. |
LOOM_IMAGE_REPOSITORY, LOOM_VERSION |
compose.yaml, install.sh |
ghcr.io/clickhouse/loom, latest |
A imagem e a tag que a stack standalone executa; o instalador fixa a tag no .env. |
LOOM_EXTRACTOR_IMAGE_REPOSITORY |
compose.yaml, install.sh |
ghcr.io/clickhouse/loom-extractor |
A imagem do serviço extrator de documentos, executada em LOOM_VERSION. |
LOOM_PORT |
compose.yaml, install.sh |
7777 |
A porta do host que a stack standalone publica. |
LOOM_REPOSITORY |
install.sh |
ClickHouse/loom |
O repositório do GitHub cujas releases o instalador baixa. |
LOOM_RELEASES_URL |
install.sh |
GitHub | De onde o instalador baixa os arquivos de release, uma URL https://; por padrão https://github.com/$LOOM_REPOSITORY/releases. |
LOOM_CONNECT |
install.sh |
não definida | Os agentes de código a conectar sem perguntar, uma lista separada por vírgulas de claude-code, codex e vscode, all, ou none sozinho; se não definida, um terminal recebe a pergunta e uma execução sem terminal não conecta nenhum (guia de início rápido). |
LOOM_LOCAL_MODELS |
install.sh |
não definida | ollama configura os trabalhos de modelo do Loom (extração e, quando habilitado, o assistente) para usar o Ollama desta máquina sem perguntar; off nunca o oferece; se não definida, uma nova instalação em um terminal recebe a oferta de um Ollama em execução (modelos e chaves). |
LOOM_NO_OPEN |
install.sh |
não definida | 1 impede o instalador de abrir o painel em um navegador. |
Quando passada ao instalador, LOOM_VERSION instala a release que ela nomeia. Sem ela, o
install.sh de uma release instala a própria release e a cópia do repositório instala latest;
uma release mais antiga sobre uma instalação mais nova é recusada, a menos que LOOM_VERSION
a nomeie (fixe o ClickHouse primeiro:
como fazer downgrade de uma instalação feita pelo instalador).
As demais referências ${LOOM_*} nos arquivos compose são campos de configuração com um
padrão definido no nível do compose, além das variáveis do uvicorn acima. O instalador mantém no
.env, quando informados, os dois repositórios de imagem (LOOM_IMAGE_REPOSITORY,
LOOM_EXTRACTOR_IMAGE_REPOSITORY), a tag, a porta, o host de bind e LOOM_CLICKHOUSE_IMAGE; o
guia de início rápido descreve o que o .env padrão define.
CLI loom
| Variável | Lida por | Padrão | Significado |
|---|---|---|---|
LOOM_BASE_URL |
server/cli/_client.py e os comandos do cliente |
http://localhost:7777 |
O servidor com o qual os comandos do cliente (install, demo, export-okf, …) se comunicam. |
LOOM_API_KEY |
server/cli/_client.py e os comandos do cliente |
não definida, depois ~/.loom/token |
O token que eles apresentam. Um valor desatualizado aqui tem precedência sobre ~/.loom/token. |
LOOM_BIND_HOST, LOOM_BIND_PORT |
server/cli/serve.py |
0.0.0.0, 7777 |
Padrões para loom serve --host e --port. |
LOOM_CONFIG_FILE |
server/cli/_client.py |
~/.loom/config.json |
A configuração do cliente que loom doctor --client lê (o arquivo que loom init grava). |
LOOM_API_KEY_FILE |
server/cli/_client.py, o lib/loom-client.mjs dos plugins, o shim do grep |
~/.loom/token |
O arquivo de token lido quando LOOM_API_KEY não está definida. |
Veja a referência da CLI.
SDKs
| Variável | Lido por | Padrão | Significado |
|---|---|---|---|
LOOM_BASE_URL |
SDKs de Python e TypeScript | http://localhost:7777 |
O servidor, quando o construtor não informa nenhum. |
LOOM_API_KEY |
SDKs de Python e TypeScript | a sessão do loom login, depois ~/.loom/token |
O token bearer, quando o construtor não informa nenhum. Valor em branco conta como não definido. |
LOOM_PROFILE |
SDKs de Python e TypeScript | default |
A sessão do loom login em ~/.loom/credentials que um cliente usa quando o construtor não indica nenhuma. |
LOOM_LOG_LEVEL |
SDKs de Python e TypeScript | não definido | O nível do logger do SDK (debug, info, warning/warn, error, off). |
LOOM_MENTOR_BRIEF |
SDKs de Python e TypeScript | desativado | on busca mentor.brief em segundo plano na primeira chamada. |
LOOM_AUTO_RUN |
SDK de Python | desativado | Vincula uma execução ambiente ao tempo de vida de cada Agent. |
Veja SDK de Python e SDK de TypeScript.
Plugins de agentes de código e scripts de hook
| Variável | Lida por | Padrão | Significado |
|---|---|---|---|
LOOM_ORG, LOOM_NAMESPACE, LOOM_AGENT |
lib/loom-client.mjs, integrations/cursor/, integrations/generic/ e dev/loom_init.py dos plugins |
~/.loom/config.json, depois as claims do token, depois default / coding / o nome do cliente |
A identidade sob a qual os hooks e scripts gravam as linhas capturadas. |
LOOM_HOOK_TIMEOUT_MS |
lib/loom-client.mjs dos plugins |
5 × o tempo de ida e volta medido de /v1/health, entre 3000 e 8000 |
O timeout que aborta cada requisição de hook; loom doctor --client o informa. |
LOOM_HOOK_EXIT_MS |
lib/loom-client.mjs dos plugins |
LOOM_HOOK_TIMEOUT_MS |
Quanto tempo um processo de hook espera depois de enviar antes de encerrar. |
LOOM_SHUNT_READ_CAP |
hooks/loom-code-shunt.mjs dos plugins |
0 (desativado) |
Número de linhas acima do qual uma leitura parcial de um arquivo indexado e não modificado é enviada às ferramentas de código. |
Veja plugin do Claude Code.
Scripts de operador
| Variável | Lida por | Padrão | Significado |
|---|---|---|---|
LOOM_REPO |
redeploy.sh |
o diretório do script | O checkout do deploy. |
LOOM_REDEPLOY_READY_TIMEOUT_S |
redeploy.sh |
180 |
Quanto tempo esperar que o /v1/health da cor ociosa informe que está pronta antes de abortar a troca. |
LOOM_PUBLIC_HEALTH_URL |
redeploy.sh |
não definida | Quando definida, a URL de health que os clientes usam é sondada por último. |
LOOM_PREFLIGHT_STRICT |
redeploy.sh |
1 |
0 transforma linhas de migração presentes apenas no ledger e divergência de checksum em um relatório, em vez de uma parada. |
LOOM_PREFLIGHT_HEALTH_URL |
dev/redeploy_preflight.sh |
http://localhost:7777/v1/health |
A URL de health que o preflight lê. |
LOOM_PREFLIGHT_PORT |
dev/redeploy_preflight.sh |
7777 |
A porta que o preflight verifica. |
LOOM_PREFLIGHT_MIGRATE |
dev/redeploy_preflight.sh |
$PYTHON -m server.core.schema.migrate --dry-run |
O comando de dry-run de migração que o preflight executa. |
HDX_BASE, HDX_COOKIE ou HDX_EMAIL + HDX_PASSWORD, HDX_DB, HDX_PREFIX, HDX_CONNECTION_ID, DRY_RUN |
deploy/clickstack_sources.sh |
HDX_DB=default, HDX_PREFIX=loom, DRY_RUN=0 |
A instância do HyperDX, as credenciais e a nomenclatura para registrar as fontes do ClickStack do Loom. |
LOOM_ADMIN_TOKEN |
dev/onboard_tenant.py |
não definida | O token de admin que faz o onboarding de um tenant. |
LOOM_OUTPUT_DIR |
dev/loom_init.py, dev/onboard_tenant.py |
. |
Onde os scripts de onboarding gravam seus arquivos de saída. |
LOOM_REBUILD_DIR |
scripts/ops/table_rebuild.py, scripts/ops/vector_codec_rebuild.py |
. |
Onde os scripts de rebuild procuram o arquivo ABORT_REBUILD que interrompe uma execução, e onde vector_codec_rebuild.py registra os UUIDs dos gêmeos que cria (<table>_rebuild.uuid), que decidem se um gêmeo é um resíduo; execute todas as linhas de um mesmo rebuild a partir do mesmo diretório. |
LANGFUSE_HOST, LANGFUSE_ORG_API_KEY |
dev/loom_init.py |
não definida | Provisionamento de projeto do Langfuse durante dev/loom_init.py. |
O procedimento de redeploy e seu preflight estão em Implantação e Atualizações; os workers da camada do compilador em Operações do índice de código; o ClickStack em ClickStack.
Relacionados
- Referência de configuração: todos os campos de configuração
LOOM_*. - Implantação: ambiente necessário, provedores e a lista de verificação para produção.