Pular para conteúdo

As páginas sem tradução abrem em inglês e são identificadas como inglês.

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.

Referência de variáveis de ambiente

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