Environment Reference
July 2, 2026 ยท View on GitHub
Generated by bpfcompat env --markdown. Do not edit by hand.
Agent
| Variable | Default | Description |
|---|---|---|
BPFCOMPAT_AGENT_EXPECTED_DECISION_ID | (unset) | Reviewed agent decision id required by bpfcompat agent apply --approve-load when approval pinning is enabled. |
BPFCOMPAT_AGENT_EXPECTED_SHA256 | (unset) | Reviewed selected artifact SHA-256 required by bpfcompat agent apply --approve-load when approval pinning is enabled. |
BPFCOMPAT_AGENT_IDENTITY_TOKEN | (unset) | Optional identity JWT sent as X-API-Identity-Token by bpfcompat agent plan/apply when --identity-token is omitted. |
BPFCOMPAT_AGENT_LAST_RESULT_PATH | (unset) | Default path read by bpfcompat agent status when --path is omitted. |
BPFCOMPAT_AGENT_LOAD_POLICY_PATH | (unset) | Default local load-policy file used by bpfcompat agent apply --approve-load when --load-policy is omitted. |
BPFCOMPAT_AGENT_REGISTRY_TOKEN | (unset) | Default registry bearer token used by bpfcompat agent plan/apply when --registry-token is omitted. |
BPFCOMPAT_AGENT_REQUIRE_APPROVAL_PINS | false | Require reviewed decision-id and artifact-SHA pins before bpfcompat agent apply --approve-load. The packaged load service sets this to true. |
BPFCOMPAT_AGENT_REQUIRE_LOAD_POLICY | true | Require a local load policy before bpfcompat agent apply --approve-load. Disable only in controlled labs. |
BPFCOMPAT_AGENT_REQUIRE_MANIFEST | false | Require a valid manifest before bpfcompat agent apply --approve-load. The packaged load service sets this to true. |
Artifact Fetch
| Variable | Default | Description |
|---|---|---|
BPFCOMPAT_FETCH_ALLOW_FILE_URI | false | Allow file:// artifact URIs. Off by default; enable only for trusted on-host caches. |
BPFCOMPAT_FETCH_ALLOW_INTERNAL_HOSTS | false | Allow fetches that resolve to RFC1918 / loopback / link-local / cloud-metadata IPs. Off by default to block SSRF. |
BPFCOMPAT_FETCH_MAX_BYTES | 134217728 | Maximum HTTP artifact download size (bytes). Default 128 MiB. |
Auth (API)
| Variable | Default | Description |
|---|---|---|
BPFCOMPAT_API_ALLOW_ANONYMOUS_READ | false | Allow unauthenticated reads of /api/v1/history/*, runtime probe, runtime decisions. Off by default. |
BPFCOMPAT_API_ALLOW_ANONYMOUS_RUNTIME_DELIVERY | false | Allow unauthenticated /api/v1/runtime/select and /api/v1/runtime/fetch for public demos. Does not enable compare, registry writes, or runtime execute. |
BPFCOMPAT_API_ALLOW_ANONYMOUS_VALIDATE | false | Allow unauthenticated calls to /api/v1/validate (also implies anonymous read of /api/v1/validate/status). |
BPFCOMPAT_API_ALLOW_ANONYMOUS_WRITE | false | Allow unauthenticated calls to every write endpoint. Use only for local dev. |
BPFCOMPAT_API_MTLS_IDENTITY_MAP_PATH | (unset) | JSON file mapping verified mTLS client certificates to explicit API identities, tenants, projects, scopes, and roles. Required before mTLS can authenticate API requests. |
BPFCOMPAT_API_REGISTRY_REQUIRE_IDENTITY | false | When true, every /api/v1/registry/* call must carry an identity JWT. |
BPFCOMPAT_API_WRITE_JWT_AUDIENCE | (unset) | Expected 'aud' claim. |
BPFCOMPAT_API_WRITE_JWT_HS256_SECRET | (unset) | Shared HS256 secret used to verify identity JWTs. Mutually exclusive with JWKS_URL/JWKS_PATH. |
BPFCOMPAT_API_WRITE_JWT_ISSUER | (unset) | Expected 'iss' claim. When set, tokens with a mismatching issuer are rejected. |
BPFCOMPAT_API_WRITE_JWT_JWKS_CACHE_TTL | 5m | How long to cache the JWKS document before refreshing. |
BPFCOMPAT_API_WRITE_JWT_JWKS_HTTP_TIMEOUT | 5s | Per-request HTTP timeout when fetching JWKS/OIDC documents. |
BPFCOMPAT_API_WRITE_JWT_JWKS_PATH | (unset) | Filesystem path to a JWKS document (alternative to JWKS_URL). |
BPFCOMPAT_API_WRITE_JWT_JWKS_URL | (unset) | HTTPS URL serving a JWKS document. http:// is rejected. |
BPFCOMPAT_API_WRITE_JWT_OIDC_DISCOVERY_CACHE_TTL | 10m | TTL on the OIDC discovery (jwks_uri) cache entry. |
BPFCOMPAT_API_WRITE_JWT_OIDC_ISSUER_URL | (unset) | OIDC issuer URL; the discovery document is fetched to resolve jwks_uri. https:// only. |
BPFCOMPAT_API_WRITE_JWT_REQUIRED_ROLES | (unset) | Roles every JWT must carry. |
BPFCOMPAT_API_WRITE_JWT_REQUIRED_SCOPES | (unset) | Space- or comma-separated scopes that every JWT must carry. |
BPFCOMPAT_API_WRITE_KEY | (unset) | Pre-shared API key required by write endpoints when JWT identity is not configured. Compare is constant-time. |
BPFCOMPAT_API_WRITE_REQUIRE_IDENTITY | false | When true, write endpoints require a valid X-API-Identity-Token JWT (API key alone is rejected). |
Cloud Registry
| Variable | Default | Description |
|---|---|---|
BPFCOMPAT_REGISTRY_AUDIT_MAX_BYTES | 67108864 | Active audit-log size before rotation (bytes). 0 disables rotation. |
BPFCOMPAT_REGISTRY_AUDIT_MAX_FILES | 10 | Max rotated audit-log files retained (active file is additional). |
BPFCOMPAT_REGISTRY_AUTH_TOKEN | (unset) | Bootstrap superuser token. Use only for initial setup; rotate to per-tenant grants ASAP. |
BPFCOMPAT_REGISTRY_AUTH_TOKEN_EXPIRES_AT | (unset) | Optional RFC3339 expiration timestamp for the bootstrap superuser token. |
BPFCOMPAT_REGISTRY_AUTH_TOKEN_NOT_BEFORE | (unset) | Optional RFC3339 not-before timestamp for the bootstrap superuser token. |
BPFCOMPAT_REGISTRY_MAX_ARTIFACT_BYTES | (unset) | Per-artifact upload size cap. |
BPFCOMPAT_REGISTRY_MAX_ARTIFACT_VERSIONS_PER_NAME | (unset) | Max retained versions per artifact name. 0 disables. |
BPFCOMPAT_REGISTRY_MAX_PROJECT_STORAGE_BYTES | (unset) | Total bytes stored across all artifacts in a project. |
BPFCOMPAT_REGISTRY_RATE_LIMIT_MAX_REQUESTS | 120 | Max requests per (subject, tenant, project, action) window. 0 disables rate limiting. |
BPFCOMPAT_REGISTRY_RATE_LIMIT_WINDOW_SECONDS | 60 | Rate-limit window length in seconds. |
BPFCOMPAT_RUNTIME_DECISIONS_MAX_BYTES | 67108864 | runtime_decisions.jsonl rotation cap. |
BPFCOMPAT_RUNTIME_DECISIONS_MAX_FILES | 10 | runtime_decisions retention. |
GitHub Marketplace
| Variable | Default | Description |
|---|---|---|
BPFCOMPAT_GITHUB_MARKETPLACE_WEBHOOK_SECRET | (unset) | Shared secret for the GitHub Marketplace listing webhook. Deliveries to /github/marketplace/webhook are authenticated by their HMAC-SHA256 signature against this value. When unset, the endpoint returns 503 (never runs open). |
HTTP Server
| Variable | Default | Description |
|---|---|---|
BPFCOMPAT_API_AUTO_SYNC_PROJECT | (unset) | Project for auto-sync. |
BPFCOMPAT_API_AUTO_SYNC_PROJECT_VISIBILITY | private | Visibility applied when auto-sync creates the project: private | public. |
BPFCOMPAT_API_AUTO_SYNC_REGISTRY | false | Auto-publish completed validate runs into the cloud registry. Requires AUTO_SYNC_TENANT/PROJECT. |
BPFCOMPAT_API_AUTO_SYNC_TENANT | (unset) | Tenant for auto-sync. |
BPFCOMPAT_API_CLIENT_CA_PATH | (unset) | When set, enables mutual TLS. File must contain PEM-encoded CA certs; every client must present a chain that verifies against this pool. Requires TLSCertPath/TLSKeyPath. Verified client cert CN is accepted as identity (AuthType="mtls"). |
BPFCOMPAT_API_ENABLE_METRICS | false | Expose /metrics (Prometheus) gated by read auth. |
BPFCOMPAT_API_ENABLE_PPROF | false | Expose /debug/pprof/* runtime profiles gated by real API-key/JWT auth. Anonymous demo modes never open pprof. Off by default; exposes goroutine stacks and heap addresses when on. |
BPFCOMPAT_API_MAX_ACTIVE_VALIDATE_JOBS | 2 | Maximum concurrent VM-backed validate jobs. Hard cap is 64. |
BPFCOMPAT_API_MAX_QUEUED_VALIDATE_JOBS | 20 | Maximum queued validate jobs. Beyond this, /api/v1/validate/start returns 429. |
BPFCOMPAT_API_MAX_VALIDATE_CONCURRENCY | 8 | Per-job profile concurrency cap. |
BPFCOMPAT_API_MAX_VALIDATE_PROFILES | 32 | Maximum profile selections per request. |
BPFCOMPAT_API_MAX_VALIDATE_TIMEOUT | 15m | Upper bound on the per-job timeout parameter. |
BPFCOMPAT_API_SHUTDOWN_DRAIN_TIMEOUT | 10m | Maximum wait for in-flight validate jobs during graceful shutdown. |
BPFCOMPAT_API_SOURCE_COMPILE_ALLOW_EXTRA_FLAGS | false | Allow per-request extra -D/-U flags to clang. Off by default. |
BPFCOMPAT_API_SOURCE_COMPILE_TIMEOUT | 30s | clang timeout when compiling source uploads. |
BPFCOMPAT_API_TRUSTED_PROXIES | (unset) | Comma-separated CIDRs of trusted upstream proxies. Only requests from these peers have X-Forwarded-For honored. |
Logging
| Variable | Default | Description |
|---|---|---|
BPFCOMPAT_LOG_FORMAT | json | slog handler format: 'json' (default) for log shippers, 'text' for local dev. |
BPFCOMPAT_LOG_LEVEL | info | slog level filter: debug | info | warn | error. |
Runtime Execute
| Variable | Default | Description |
|---|---|---|
BPFCOMPAT_API_ENABLE_RUNTIME_EXECUTE | false | Master switch for the host-load endpoint. Off by default; never enable on a multi-tenant host. |
BPFCOMPAT_API_REDACT_RUNTIME_DETAILS | true | Redact filesystem paths in success and error responses. Disable only when debugging. |
BPFCOMPAT_API_RUNTIME_EXECUTE_APPROVAL_TOKEN | (unset) | Required value for the X-Execute-Approval-Token header. Constant-time compared. |
BPFCOMPAT_API_RUNTIME_EXECUTE_JWT_REQUIRED_ROLES | (unset) | Additional JWT roles required specifically for /api/v1/runtime/execute. |
BPFCOMPAT_API_RUNTIME_EXECUTE_JWT_REQUIRED_SCOPES | (unset) | Additional space- or comma-separated JWT scopes required specifically for /api/v1/runtime/execute. |
BPFCOMPAT_API_RUNTIME_EXECUTE_KILL_SWITCH | false | Emergency: when true, every /api/v1/runtime/execute call returns 503. Leaves the endpoint registered for audit. |
BPFCOMPAT_API_RUNTIME_EXECUTE_POLICY_PATH | (unset) | Path to a YAML policy file evaluated before each execute. See docs/runtime-execute-policy.md. |
BPFCOMPAT_API_RUNTIME_EXECUTE_REQUIRE_POLICY | false | Refuse runtime execute if no policy is configured (defense in depth). |
BPFCOMPAT_API_RUNTIME_EXECUTE_REQUIRE_WORKER_IDENTITY | false | Refuse runtime execute if WORKER_USER is unset. |
BPFCOMPAT_API_RUNTIME_EXECUTE_WORKER_BINARY | (unset) | Absolute path to the bpfcompat binary used as the worker. Defaults to os.Executable(). |
BPFCOMPAT_API_RUNTIME_EXECUTE_WORKER_USER | (unset) | OS username to run the worker as via sudo -u. Leave empty to run as the API process user. |
Signing
| Variable | Default | Description |
|---|---|---|
BPFCOMPAT_SIGNING_EXTERNAL_ARGS | (unset) | Whitespace-split extra args for the external signer. |
BPFCOMPAT_SIGNING_EXTERNAL_CMD | (unset) | Command to invoke for external signing. Stdin = canonical payload; stdout = signature envelope JSON. |
BPFCOMPAT_SIGNING_MODE | local | Where the registry signing key lives: 'local' (default, on disk) or 'external-cmd'. |
BPFCOMPAT_TRUSTED_SIGNING_KEYS_PATH | (unset) | Path to a keyring file (one trusted key per line). |
BPFCOMPAT_TRUSTED_SIGNING_PUBLIC_KEYS | (unset) | Inline trusted public keys (kid:base64, comma-separated). |
VM Runner
| Variable | Default | Description |
|---|---|---|
BPFCOMPAT_AARCH64_UEFI_CODE | /usr/share/AAVMF/AAVMF_CODE.fd | Path to the aarch64 UEFI firmware CODE image (pflash). aarch64 virt has no built-in firmware, so VM boots need it; install qemu-efi-aarch64 or point this at your distro's edk2 build. Ignored on x86_64. |
BPFCOMPAT_AARCH64_UEFI_VARS | /usr/share/AAVMF/AAVMF_VARS.fd | Path to the aarch64 UEFI vars template (pflash). A per-VM writable copy is staged from it so guest NVRAM writes don't touch the shared template. Ignored on x86_64. |
BPFCOMPAT_ALLOW_VVFAT_SEED | false | Re-enable the legacy vvfat config-drive seed for RHEL-family/Amazon/Oracle/SUSE profiles when cloud-localds is missing. Off by default: those guests are known not to boot from the vvfat fallback on some hosts (0-byte serial, then an SSH timeout), so seed selection fails fast with an install hint instead. Prefer installing cloud-image-utils (provides cloud-localds). |
BPFCOMPAT_ENABLE_RHCOS | false | Enable the RHEL CoreOS (rhcos) profile. RHCOS boots via the same Ignition path as Fedora CoreOS, but its image ships with an OpenShift release rather than a public URL. Stage the image with make rhcos-image and set this to 1/true once it is present; left off, rhcos stays unsupported so it is never claimed runnable without a real image. |
Validator
| Variable | Default | Description |
|---|---|---|
BPFCOMPAT_VALIDATOR_BIN | (unset) | Absolute path to the C validator binary; wins over the /usr/libexec search path. |
BPFCOMPAT_VALIDATOR_SHA256 | (unset) | Expected SHA-256 of the validator binary. When set, mismatched binaries are refused before exec. |