Documentation / Advanced

Environment variables

The service reads its configuration at startup. Existing process variables take precedence over .env discovered from its working directory. Restart the identified instance to apply changes. Relative paths depend on that working directory.

Boolean settings accept true/false, yes/no, on/off and 1/0, ignoring case and surrounding spaces, except where a row specifies a different rule.

HTTP and panel

Variable	When absent	Values and effect
`APP_HOST`	`127.0.0.1`	Bind to an IPv4 or IPv6 address. Invalid input selects loopback. A busy or unavailable address prevents startup.
`APP_PORT`	`59865`	TCP port, 0–65535. Invalid input uses the default. Use a known free port to reconnect your clients.
`APP_CORS_ALLOW_ORIGINS`	`*`	Comma-separated HTTP origins. Omitted or * permits all; an empty list permits none. Invalid header values are skipped with a warning. Affects browser API requests.
`APP_BODY_LIMIT_BYTES`	`1048576`	Positive maximum request body size in bytes. Zero or invalid input restores the default. Oversized bodies on limited routes are rejected.
`BEE_FRONTEND_MODE`	`embedded (embedded-ui) / disabled`	disabled serves API and MCP only. embedded serves the bundled panel at /app/ and requires a binary compiled with embedded-ui. Other values fail startup.

Database

Variable	When absent	Values and effect
`DATABASE_DRIVER`	`sqlite`	sqlite or postgres (case-insensitive). Absent or blank infers PostgreSQL for postgres:// or postgresql:// URLs. Unknown drivers or mismatched schemes fail startup.
`DATABASE_URL`	`~/.beeteam/beeteam.sql`	Use sqlite:// with a file path or a PostgreSQL connection URL. An explicit URL takes precedence over the home default. PostgreSQL requires its URL. The adapter opens the selected database and applies its migrations.

MCP transport

Variable	When absent	Values and effect
`MCP_ENABLED`	`true`	Boolean. Enables the endpoint only when MCP is compiled in. False removes the MCP route. Invalid text uses the default.
`MCP_PATH`	`/mcp`	Route path. Whitespace and trailing slashes are trimmed and a missing leading slash is added. Blank selects /mcp. Use a distinct path, then update the client registration.
`MCP_ALLOWED_ORIGINS`	`*`	Browser CORS list for MCP, independent of API CORS. Comma-separated origins, * or unset allows all; an explicit empty list allows none. Invalid header values are skipped.

Portable transfer

All six numeric transfer limits must be positive unsigned integers within the destination type’s range. Invalid values fail startup. Exceeding a configured limit can reject the transfer. Inspect /api/v1/data-transfers for the active configuration.

Variable	When absent	Values and effect
`BEE_TRANSFER_ENABLED`	`false`	Only literal lowercase true enables transfer administration. Other values leave it disabled. Transfer limits and origins are validated even when disabled.
`BEE_TRANSFER_DIR`	`.local/transfers`	Archive and job directory, relative to the service working directory unless absolute. Use a dedicated writable location when enabled.
`BEE_TRANSFER_ALLOWED_ORIGINS`	`[]`	Comma-separated exact http(s) origins without a trailing slash, path or wildcard. Invalid origins fail startup. Empty denies browser origins; requests without Origin are checked separately.
`BEE_TRANSFER_UPLOAD_BYTES`	`2147483648`	Maximum compressed archive size in bytes.
`BEE_TRANSFER_EXPANDED_BYTES`	`10737418240`	Maximum expanded archive size in bytes.
`BEE_TRANSFER_MAX_ENTRIES`	`100000`	Maximum number of archive entries.
`BEE_TRANSFER_LINE_BYTES`	`1048576`	Maximum bytes per JSONL record.
`BEE_TRANSFER_TIMEOUT_SECONDS`	`1800`	Maximum processing time in seconds.
`BEE_TRANSFER_RETENTION_SECONDS`	`86400`	Retention window in seconds before eligible transfer artifacts can be cleaned up.

Logging and trace export

Variable	When absent	Values and effect
`RUST_LOG`	`info`	Tracing filter, e.g. info,beeteam=debug. Missing or invalid filter falls back to info. The binary adds otel::tracing=info.
`OTEL_ENABLED`	`false`	Boolean. With false the binary logs locally; true initializes a span exporter. Invalid text uses the default.
`OTEL_USE_SIMPLE_EXPORTER`	`false`	Case-insensitive true exports individual spans. Other values use the batch processor when tracing is enabled.
`OTEL_EXPORTER_OTLP_PROTOCOL`	`grpc`	grpc, http/protobuf or http/json. Unrecognized values select gRPC. The binary chooses the trace transport before constructing the exporter.
`OTEL_SERVICE_NAME`	`beeteam`	Service name on exported traces. When unset, Bee Team supplies its Cargo package name.

Trace SDK settings

SDK trace settings apply when OTEL_ENABLED is true. This binary creates a trace exporter. Metrics and log exporter selectors in example collector configurations do not enable additional Bee Team exporters.

Variable	When absent	Values and effect
`OTEL_RESOURCE_ATTRIBUTES`	`[]`	Comma-separated key=value pairs attached to the trace resource. Malformed pairs are ignored.
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4317 (gRPC), http://localhost:4318 (HTTP)`	Collector base URL; HTTP adds /v1/traces. A trace-specific endpoint takes precedence.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	`→ OTEL_EXPORTER_OTLP_ENDPOINT`	Full trace URL, including /v1/traces for HTTP. A wrong endpoint prevents delivery.
`OTEL_EXPORTER_OTLP_HEADERS`	`[]`	Comma-separated key=value request headers. The trace-specific setting takes precedence. Keep credentials outside shared examples.
`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	`→ OTEL_EXPORTER_OTLP_HEADERS`	Headers for trace export; malformed pairs are skipped.
`OTEL_EXPORTER_OTLP_TIMEOUT`	`10000 ms`	Unsigned millisecond timeout per export. Invalid text falls back to the SDK default.
`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`	`→ OTEL_EXPORTER_OTLP_TIMEOUT`	Trace timeout in milliseconds. A valid trace value overrides the generic timeout.
`OTEL_EXPORTER_OTLP_COMPRESSION`	`—`	Compression for the OTLP exporter. Leave unset with this build; unsupported algorithms or missing codec features can fail initialization.
`OTEL_EXPORTER_OTLP_TRACES_COMPRESSION`	`→ OTEL_EXPORTER_OTLP_COMPRESSION`	Trace-specific compression overrides the generic value.
`OTEL_TRACES_SAMPLER`	`parentbased_always_on`	always_on, always_off, traceidratio or the parentbased_ form of each. Unknown values select the default sampler.
`OTEL_TRACES_SAMPLER_ARG`	`1.0`	For ratio sampling use a probability from 0 to 1. Missing or unparseable values use 1.0.
`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`	`128`	Maximum attributes retained per span. Unsigned integer; invalid input uses the default.
`OTEL_SPAN_EVENT_COUNT_LIMIT`	`128`	Maximum events retained per span. Unsigned integer; invalid input uses the default.
`OTEL_SPAN_LINK_COUNT_LIMIT`	`128`	Maximum links retained per span. Unsigned integer; invalid input uses the default.
`OTEL_BSP_MAX_QUEUE_SIZE`	`2048`	Batch processor: spans queued. Unparseable values keep the default.
`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`	`512`	Batch processor: spans in one batch, capped by queue size. Unparseable values keep the default.
`OTEL_BSP_SCHEDULE_DELAY`	`5000`	Batch processor: milliseconds between scheduled exports. Unparseable values keep the default.
`OTEL_BSP_EXPORT_TIMEOUT`	`30000`	Batch processor: milliseconds (processor configuration; use the OTLP timeout for exporter I/O). Unparseable values keep the default.
`OTEL_BSP_MAX_CONCURRENT_EXPORTS`	`1`	Batch processor: concurrent exports (processor setting; applicability depends on processor implementation). Unparseable values keep the default.

Operating system inputs

OS inputs are inherited from the service account. Missing optional paths are skipped during discovery. For a predictable data location, set DATABASE_URL explicitly.

Variable	When absent	Values and effect
`HOME`	`Unix`	User home for default SQLite; OS account lookup may supply the home.
`USERPROFILE`	`Windows`	User home for default SQLite; set DATABASE_URL if home lookup fails.
`PATH`	`—`	Git executable discovery. Missing Git leaves project discovery unavailable.
`SystemRoot`	`Windows`	Explorer location and environment forwarded to Git.
`WINDIR`	`Windows`	Forwarded to the isolated Git process when present.
`TEMP / TMP`	`—`	Temporary locations passed through to Git when present.
`LOCALAPPDATA / ProgramFiles / ProgramFiles(x86)`	`Windows`	Checked in that order for installed VS Code. Missing candidates are skipped.

Build and test only

BEE_FRONTEND_DIST selects the verified frontend build directory for embedded-ui compilation. CARGO_TARGET_DIR selects Cargo output. BEE_TEST_DRIVER and BEE_TEST_DATABASE_URL select isolated test databases. BEE_API_TARGET controls the Vite development proxy. Set runtime database variables separately when starting the binary.

Start an isolated instance

Run from the checkout after building the embedded distribution. Choose an unused loopback port (the examples use 59875). Each example selects a fresh directory and SQLite file. Use a second terminal for the checks below.

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"

Open http://127.0.0.1:59875/api/v1/info to check apiVersion, then /app/ for the panel. Update the harness endpoint to http://127.0.0.1:59875/mcp and call listBoards. To restart with the same data, stop the foreground service with Ctrl+C and rerun only the last command in the same shell.