Documentação / Avançado

Variáveis de ambiente

O serviço lê a configuração na inicialização. As variáveis do processo têm prioridade sobre o .env encontrado a partir do diretório de trabalho. Reinicie a instância identificada para aplicar alterações. Caminhos relativos dependem desse diretório.

Variáveis booleanas aceitam true/false, yes/no, on/off e 1/0, ignorando maiúsculas e espaços nas pontas, salvo quando a linha indicar outra regra.

HTTP e painel

Variável	Quando ausente	Valores e efeito
`APP_HOST`	`127.0.0.1`	Escuta em um endereço IPv4 ou IPv6. Um valor inválido seleciona loopback. Endereço ocupado ou indisponível impede a inicialização.
`APP_PORT`	`59865`	Porta TCP de 0 a 65535. Valor inválido usa a padrão. Escolha uma porta livre conhecida para reconectar os clientes.
`APP_CORS_ALLOW_ORIGINS`	`*`	Origens HTTP separadas por vírgula. Ausente ou * permite todas; lista vazia não permite nenhuma. Valores de cabeçalho inválidos geram aviso e são ignorados. Afeta o acesso do navegador à API.
`APP_BODY_LIMIT_BYTES`	`1048576`	Tamanho máximo positivo do corpo da requisição em bytes. Zero ou valor inválido restaura o padrão. Rotas com limite rejeitam corpos maiores.
`BEE_FRONTEND_MODE`	`embedded (embedded-ui) / disabled`	disabled serve a API e o MCP. embedded serve o painel em /app/ e exige binário compilado com embedded-ui. Outros valores impedem a inicialização.

Banco de dados

Variável	Quando ausente	Valores e efeito
`DATABASE_DRIVER`	`sqlite`	sqlite ou postgres, sem distinção de maiúsculas. Ausente ou vazio infere PostgreSQL para URLs postgres:// ou postgresql://. Driver desconhecido ou esquema incompatível impede a inicialização.
`DATABASE_URL`	`~/.beeteam/beeteam.sql`	Use sqlite:// com um caminho de arquivo ou uma URL de conexão PostgreSQL. A URL explícita prevalece sobre o arquivo na pasta pessoal. PostgreSQL exige URL. O adaptador abre o banco selecionado e aplica suas migrações.

Transporte MCP

Variável	Quando ausente	Valores e efeito
`MCP_ENABLED`	`true`	Booleano. Ativa o endpoint somente se o binário incluir MCP. Falso remove a rota MCP. Texto inválido usa o padrão.
`MCP_PATH`	`/mcp`	Caminho da rota. Espaços e barras finais são removidos e a barra inicial é adicionada quando ausente. Vazio seleciona /mcp. Use um caminho exclusivo e atualize o registro do cliente.
`MCP_ALLOWED_ORIGINS`	`*`	Lista CORS do MCP, independente da API. Separe origens por vírgula. * ou variável ausente permite todas; lista vazia não permite nenhuma. Valores de cabeçalho inválidos são ignorados.

Transferência portátil

Os seis limites numéricos de transferência exigem inteiros positivos dentro da faixa do tipo de destino. Valores inválidos impedem a inicialização. Exceder um limite pode causar a rejeição da operação. Consulte /api/v1/data-transfers para ver a configuração ativa.

Variável	Quando ausente	Valores e efeito
`BEE_TRANSFER_ENABLED`	`false`	Somente o texto true em minúsculas ativa a administração de transferências. Outros valores deixam o recurso desativado. Limites e origens são validados mesmo desativados.
`BEE_TRANSFER_DIR`	`.local/transfers`	Diretório dos pacotes e das operações, relativo ao diretório de trabalho salvo se absoluto. Use um local dedicado com permissão de escrita ao ativar.
`BEE_TRANSFER_ALLOWED_ORIGINS`	`[]`	Origens http(s) exatas separadas por vírgula, sem barra final, caminho ou curinga. Origem inválida impede a inicialização. Vazio recusa origens do navegador; requisições sem Origin seguem validação separada.
`BEE_TRANSFER_UPLOAD_BYTES`	`2147483648`	Tamanho máximo do pacote compactado em bytes.
`BEE_TRANSFER_EXPANDED_BYTES`	`10737418240`	Tamanho máximo do pacote descompactado em bytes.
`BEE_TRANSFER_MAX_ENTRIES`	`100000`	Número máximo de entradas no pacote.
`BEE_TRANSFER_LINE_BYTES`	`1048576`	Número máximo de bytes por registro JSONL.
`BEE_TRANSFER_TIMEOUT_SECONDS`	`1800`	Tempo máximo de processamento em segundos.
`BEE_TRANSFER_RETENTION_SECONDS`	`86400`	Período de retenção em segundos antes da limpeza dos artefatos elegíveis.

Logs e exportação de traces

Variável	Quando ausente	Valores e efeito
`RUST_LOG`	`info`	Filtro de logs, por exemplo info,beeteam=debug. Filtro ausente ou inválido usa info. O binário acrescenta otel::tracing=info.
`OTEL_ENABLED`	`false`	Booleano. Falso mantém os logs locais; verdadeiro inicializa a exportação de spans. Texto inválido usa o padrão.
`OTEL_USE_SIMPLE_EXPORTER`	`false`	true, sem distinção de maiúsculas, exporta spans individualmente. Outros valores usam processamento em lotes quando traces estão ativos.
`OTEL_EXPORTER_OTLP_PROTOCOL`	`grpc`	grpc, http/protobuf ou http/json. Valores desconhecidos selecionam gRPC. O binário escolhe o transporte antes de construir o exportador.
`OTEL_SERVICE_NAME`	`beeteam`	Nome do serviço nos traces exportados. Quando ausente, o Bee Team usa o nome do pacote Cargo.

Configuração do SDK de traces

As configurações do SDK de traces se aplicam com OTEL_ENABLED ativo. O binário cria um exportador de traces. Os seletores de métricas e logs em exemplos de coletores não ativam exportadores adicionais no Bee Team.

Variável	Quando ausente	Valores e efeito
`OTEL_RESOURCE_ATTRIBUTES`	`[]`	Pares chave=valor separados por vírgula no recurso de traces. Pares inválidos são ignorados.
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4317 (gRPC), http://localhost:4318 (HTTP)`	URL base do coletor; HTTP acrescenta /v1/traces. O endpoint específico de traces tem prioridade.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	`→ OTEL_EXPORTER_OTLP_ENDPOINT`	URL completa dos traces, incluindo /v1/traces em HTTP. Um endpoint incorreto impede a entrega.
`OTEL_EXPORTER_OTLP_HEADERS`	`[]`	Cabeçalhos chave=valor separados por vírgula. A configuração específica de traces tem prioridade. Mantenha credenciais fora de exemplos compartilhados.
`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	`→ OTEL_EXPORTER_OTLP_HEADERS`	Cabeçalhos de exportação de traces; pares malformados são ignorados.
`OTEL_EXPORTER_OTLP_TIMEOUT`	`10000 ms`	Timeout por exportação em milissegundos sem sinal. Texto inválido usa o padrão do SDK.
`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`	`→ OTEL_EXPORTER_OTLP_TIMEOUT`	Timeout de traces em milissegundos. Valor válido prevalece sobre o genérico.
`OTEL_EXPORTER_OTLP_COMPRESSION`	`—`	Compressão do exportador OTLP. Deixe ausente nesta compilação; algoritmos incompatíveis ou codecs ausentes podem impedir a inicialização.
`OTEL_EXPORTER_OTLP_TRACES_COMPRESSION`	`→ OTEL_EXPORTER_OTLP_COMPRESSION`	A compressão específica de traces prevalece sobre o valor genérico.
`OTEL_TRACES_SAMPLER`	`parentbased_always_on`	always_on, always_off, traceidratio ou cada variante com prefixo parentbased_. Valores desconhecidos usam o padrão.
`OTEL_TRACES_SAMPLER_ARG`	`1.0`	Em amostragem por proporção, use probabilidade de 0 a 1. Valor ausente ou ilegível usa 1.0.
`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`	`128`	Máximo de atributos por span. Inteiro sem sinal; entrada inválida usa o padrão.
`OTEL_SPAN_EVENT_COUNT_LIMIT`	`128`	Máximo de eventos por span. Inteiro sem sinal; entrada inválida usa o padrão.
`OTEL_SPAN_LINK_COUNT_LIMIT`	`128`	Máximo de links por span. Inteiro sem sinal; entrada inválida usa o padrão.
`OTEL_BSP_MAX_QUEUE_SIZE`	`2048`	Processamento em lotes: spans na fila. Valores ilegíveis usam o padrão.
`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`	`512`	Processamento em lotes: spans por lote, limitado ao tamanho da fila. Valores ilegíveis usam o padrão.
`OTEL_BSP_SCHEDULE_DELAY`	`5000`	Processamento em lotes: milissegundos entre exportações agendadas. Valores ilegíveis usam o padrão.
`OTEL_BSP_EXPORT_TIMEOUT`	`30000`	Processamento em lotes: milissegundos (configuração do processador; use o timeout OTLP para E/S). Valores ilegíveis usam o padrão.
`OTEL_BSP_MAX_CONCURRENT_EXPORTS`	`1`	Processamento em lotes: exportações simultâneas (a aplicação depende do processador). Valores ilegíveis usam o padrão.

Entradas do sistema operacional

As entradas do sistema operacional são herdadas da conta do serviço. Caminhos opcionais ausentes são ignorados durante a descoberta. Para definir o local dos dados, informe DATABASE_URL explicitamente.

Variável	Quando ausente	Valores e efeito
`HOME`	`Unix`	Pasta pessoal para SQLite; o sistema pode obtê-la da conta.
`USERPROFILE`	`Windows`	Pasta pessoal para SQLite; defina DATABASE_URL se a busca falhar.
`PATH`	`—`	Localização do Git. A ausência do Git impede a descoberta do repositório.
`SystemRoot`	`Windows`	Local do Explorer e ambiente encaminhado ao Git.
`WINDIR`	`Windows`	Encaminhado ao processo isolado do Git quando presente.
`TEMP / TMP`	`—`	Locais temporários encaminhados ao Git quando presentes.
`LOCALAPPDATA / ProgramFiles / ProgramFiles(x86)`	`Windows`	Verificados nessa ordem na busca do VS Code. Candidatos ausentes são ignorados.

Somente compilação e testes

BEE_FRONTEND_DIST seleciona o diretório do frontend verificado ao compilar embedded-ui. CARGO_TARGET_DIR seleciona a saída do Cargo. BEE_TEST_DRIVER e BEE_TEST_DATABASE_URL selecionam bancos isolados de teste. BEE_API_TARGET controla o proxy Vite de desenvolvimento. Configure o banco do serviço separadamente na inicialização.

Iniciar uma instância isolada

Execute na raiz do checkout após compilar a distribuição com painel. Escolha uma porta loopback livre (os exemplos usam 59875). Cada exemplo seleciona um diretório e um arquivo SQLite novos. Use um segundo terminal para as verificações abaixo.

PowerShell

$binary = (Resolve-Path '.\target\release\beeteam.exe').Path
$dir = New-Item -ItemType Directory -Path (Join-Path ([IO.Path]::GetTempPath()) ([guid]::NewGuid()))
Set-Location -LiteralPath $dir.FullName
$env:APP_HOST = '127.0.0.1'
$env:APP_PORT = '59875'
$env:BEE_FRONTEND_MODE = 'embedded'
$env:DATABASE_DRIVER = 'sqlite'
$env:DATABASE_URL = 'sqlite://' + ($dir.FullName -replace '\\','/') + '/demo.sql'
& $binary

POSIX

binary="$PWD/target/release/beeteam"
dir=$(mktemp -d) && cd "$dir" || exit 1
export APP_HOST=127.0.0.1 APP_PORT=59875 BEE_FRONTEND_MODE=embedded
export DATABASE_DRIVER=sqlite DATABASE_URL="sqlite://$dir/demo.sql"
"$binary"

Abra http://127.0.0.1:59875/api/v1/info e confira apiVersion. Em seguida abra /app/ para ver o painel. Atualize o endpoint do harness para http://127.0.0.1:59875/mcp e execute listBoards. Para reiniciar com os mesmos dados, encerre com Ctrl+C e repita somente o último comando no mesmo terminal.