Configuration
Every environment variable this release reads, found by scanning the tree for the ways it reads one — the
kernel’s own env bindings, the names reached through a string, and the $-expansions that compose, the
Dockerfiles and the Caddyfile are configured by. Each row’s sentence lives in a comment beside one of the
reads, so a variable cannot be added without describing it: pnpm codegen refuses, by name.
- 203 variables, across 11 parts of the product.
- 13 are marked must be set: the box refuses to start without them.
- 66 name the value the product falls back to when they are unset. That value is read
out of the code at the read site — it is never typed here, and a fallback this scan cannot reduce to a
value stops
pnpm codegeninstead of reaching this page. - The remaining 124 show —, which means this scan found no fallback value at any read site. It is a statement about the scan, not a promise about the product: what leaving one unset actually does is in its sentence.
- Read at names the FILE and not a line inside it. This page is regenerated from the tree on every
change, so a line number would make it move whenever an unrelated edit shifted one — the variable’s own
name is the anchor, and it is in the same row. A file that reaches for the name more than once carries
(×N), which is the one thing the line numbers were telling a reader that the file alone does not.
⚠️ This page says what the product READS, not what a box should SET. A variable is here because some line
of this release reaches for the name. Which values a given instance needs is the runbook’s question
(docs/operations/), and the answer differs by how the box is deployed.
The variables
Section titled “The variables”Deployment
Section titled “Deployment”| Variable | When unset | What it does | Read at |
|---|---|---|---|
FORGE_ADMIN_DOMAIN | must be set | The admin’s own hostname, on its own DNS record and its own certificate. | infra/caddy/Caddyfileinfra/docker-compose.prod.ymlinfra/env-source.sh (×2)+3 more |
FORGE_ADMIN_HOST_MODE | — | 1 declares this admin serves many tenants resolved from the request host. It refuses to be combined with a pinned tenant, because the pin would silently win. | infra/env-source.sh (×4) |
FORGE_ADMIN_HTTP_PORT | 8201 | The host port of an instance bench’s admin door. Unset: | templates/instance/bench/compose.bench.ymltemplates/instance/bench/lib.sh (×3)templates/instance/bench/up.sh |
FORGE_ADMIN_I18N_HOST_DIR | ./i18n | The host directory mounted into the admin container as its translation overrides. | templates/instance/compose.yml |
FORGE_ADMIN_IMAGE | must be set | The admin image the box runs, by digest. | infra/docker-compose.prod.ymltemplates/instance/compose.yml |
FORGE_ADMIN_PORT | 3031 | Host port the admin is published on in development. | docker-compose.yml (×2)scripts/admin-demo.shscripts/boot/bench-ports.sh |
FORGE_APPLE_DOMAIN_ASSOCIATION | — | The body Apple hands you to serve at /.well-known/apple-developer-domain-association.txt, without which a Services ID is never trusted. Unset: that route 404s. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/storefront-kit/src/config.ts+1 more |
FORGE_APPLE_KEY_ID | — | The id of the Apple .p8 key the client secret is minted with. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/storefront-kit/src/config.ts+1 more |
FORGE_APPLE_PRIVATE_KEY | — | The Apple .p8 private key itself. Newlines may be \n-encoded. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/storefront-kit/src/config.ts+1 more |
FORGE_APPLE_SERVICE_ID | — | Sign in with Apple Services ID — the identifier of the SERVICES ID, never the App ID it is grouped under. Absent: the Apple button renders disabled. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/storefront-kit/src/config.ts+1 more |
FORGE_APPLE_TEAM_ID | — | The Apple developer team the client secret is minted for. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/storefront-kit/src/config.ts+1 more |
FORGE_BENCH_ADMIN_ORIGIN | — | The admin’s origin as a browser opens it on a local bench (derived like the shop’s). | templates/instance/bench/lib.sh (×3)templates/instance/bench/promote.shtemplates/instance/bench/up.sh (×6) |
FORGE_BENCH_AFTER_HOOK | — | Services of an instance bench started AFTER its seed hook (space separated), because they need a value the hook learns (.forge-bench/hook.env) — a totem that serves a store the seed creates. | templates/instance/bench/up.sh (×3) |
FORGE_BENCH_BIND | 127.0.0.1 | Host interface the bench publishes the shop’s plain-http doors on (edge, vitrine, checkout). Loopback by default: a browser drops the Secure cookies these containers set on any plain-http origin that is not localhost, so the cart is lost silently. Set it to 0.0.0.0 to publish them on every interface anyway. | docker-compose.yml (×4)templates/instance/bench/compose.bench.yml (×4)templates/instance/bench/lib.sh (×4) |
FORGE_BENCH_COMPOSE_FILES | — | Extra compose files (relative to the instance root, space-separated) a local bench merges before its own overlay (so the overlay’s guarantees — its database, its mailbox, the edge’s ports — hold over them), for a front or a service the instance adds. | templates/instance/bench/lib.sh (×2) |
FORGE_BENCH_DOORS | — | Doors of an instance bench beyond its own (a totem, a second front the instance’s Caddyfile serves on another edge port): <NAME>:<suffix>:<edge port>[:https] entries, space separated — published on :https, a promoted bench also serves it by https on | templates/instance/bench/lib.sh (×2)templates/instance/bench/up.sh (×2) |
FORGE_BENCH_HOOK_ENV_FILE | — | Set by an instance bench for its seed hook: the file (.forge-bench/hook.env) where the hook writes, NAME=value per line, what it learned (a store id that exists only after the seed); every later compose call of the bench reads it. | templates/instance/bench/lib.sh |
FORGE_BENCH_KEEP_VOLUMES | — | Volumes an instance bench’s bench/down.sh -v keeps (space separated; the key in the compose file or the volume’s full name) — a cache that is expensive to refill. | templates/instance/bench/down.sh (×3) |
FORGE_BENCH_KERNEL_URL | must be set | The kernel’s address as a process on this machine reaches it on an instance bench; derived from the port block, and handed to the seed hook. | templates/instance/bench/lib.shtemplates/instance/bench/seed.example.shtemplates/instance/bench/up.sh (×6) |
FORGE_BENCH_MAILBOX | bench | Where an instance bench’s mail goes: unset (or 1, the reference instance’s spelling) → the bench’s own mailbox, nothing leaves the machine; none → no mailbox, the kernel sends for real through the FORGE_SMTP_* the bench declares (the password from the shell or bench/smtp.pass, never bench.env). | templates/instance/bench/lib.sh (×3) |
FORGE_BENCH_OPERATOR_TOKEN | — | The operator credential an instance bench’s provisioning minted (its first tenant’s), filed in .forge-bench/secrets.env (never printed) for an admin or a script of your own. | templates/instance/bench/up.sh |
FORGE_BENCH_OPERATOR_TOKEN_FILE | must be set | A file holding the operator credential, handed to an instance bench’s seed hook (read it, never print it). | templates/instance/bench/seed.example.sh |
FORGE_BENCH_ORIGIN | must be set | The shop’s origin as a browser opens it on a local bench (an instance bench derives it from the address and the port block before compose reads it; set it only to override). | templates/instance/bench/compose.bench.yml (×2)templates/instance/bench/lib.sh (×4)templates/instance/bench/promote.sh+1 more |
FORGE_BENCH_POSTGRES_PASSWORD | must be set | An instance bench’s own database password, minted once by bench/up.sh into .forge-bench/secrets.env; never production’s. | templates/instance/bench/compose.bench.yml (×2)templates/instance/bench/compose.shtemplates/instance/bench/down.sh+2 more |
FORGE_BENCH_SEED_HOOK | — | A command of the instance an instance bench runs after the box is up, to seed it (bench/bench.env). Empty: the store is born with nothing in it. | templates/instance/bench/up.sh (×5) |
FORGE_BENCH_SMTP_CA_FILE | — | With FORGE_BENCH_MAILBOX=none: a CA file (relative to the instance root) the kernel trusts for the declared SMTP, when no public CA signs its certificate. Unset: the public CAs only. | templates/instance/bench/lib.sh (×4) |
FORGE_BENCH_STORE_ID | must be set | The store an instance bench was born with, handed to its seed hook. | templates/instance/bench/seed.example.sh |
FORGE_BENCH_TENANT | must be set | The tenant an instance bench was born with, handed to its seed hook. | templates/instance/bench/seed.example.sh |
FORGE_BENCH_TENANTS | — | The tenants an instance bench is born with, when more than one: <id>:<store handle>:<store name> entries separated by ;, the first one served by the shop’s door. Unset: the one tenant FORGE_REF_TENANT names. | templates/instance/bench/lib.sh (×2) |
FORGE_BENCH_TLS_BIND | 0.0.0.0 | Host interface the bench’s https edge publishes its doors on (three here, two on an instance bench). Every interface by default; it is https, so the Secure-cookie trap of the plain-http doors does not apply. | docker-compose.yml (×3)templates/instance/bench/compose.edge-tls.yml (×2)templates/instance/bench/lib.sh (×3) |
FORGE_BENCH_TLS_CERT_DIR | ./bench/certs | Certificates of your own for an instance bench promoted to a host or IP (one PEM per file, chain then key; mkcert, an ACME client’s output, a company CA): served by the bench’s https edge instead of its local CA. Default ./bench/certs. The production edge’s FORGE_TLS_CERT_DIR is never read by the bench. | templates/instance/bench/compose.edge-tls.ymltemplates/instance/bench/lib.sh (×2) |
FORGE_BENCH_TLS_HOST | localhost | The hostname or IP the bench’s https edge answers for. Exported by pnpm demo / pnpm admin:demo (and by an instance bench’s bench/up.sh) from FORGE_BENCH_ADDRESS; never declared by hand. | docker-compose.ymlinfra/caddy/Caddyfile.bench-tls (×4)templates/instance/bench/Caddyfile.tls (×3)+2 more |
FORGE_BUILD_DATE | — | When the image was built, ISO-8601, baked at build time. | infra/Dockerfileinfra/admin.Dockerfileinfra/checkout.Dockerfile+3 more |
FORGE_BULK_READ_TOKEN | — | This box’s own bulk reader, minted by node dist/bulk-read-token.js (a platform credential holding only platform.bulk_read). It buys BUDGET, never data. Unset: every server-side read stays on the anonymous face, exactly as before the face existed. | docker-compose.yml (×2)infra/docker-compose.prod.yml (×2)packages/storefront-kit/src/config.ts (×2)+1 more |
FORGE_CADDY_EXTRA_DIR | ./caddy/extra | A directory of extra hostname files the edge loads beside the two it already serves — a second admin for a second tenant, say. | infra/cicd/prove-running-image.shinfra/docker-compose.prod.ymltemplates/instance/compose.yml |
FORGE_CHECKOUT_IMAGE | must be set | The checkout image the box runs, by digest — the fourth tier, a sibling of the storefront rather than a layer of it. | infra/docker-compose.prod.ymltemplates/instance/compose.yml |
FORGE_CHECKOUT_PORT | 3032 | Host port the checkout is published on in development. | docker-compose.ymlscripts/demo-local.sh |
FORGE_COMPOSITION | extensions/composition.base.json | The composition file naming WHICH apps compose the image being baked, read from the build context named list (or from the plain build context when there is none). A list this release cannot serve dies at bake time, by name. | infra/Dockerfile (×5)infra/admin.Dockerfile (×5)infra/checkout.Dockerfile (×5)+2 more |
FORGE_COMPOSITION_APPS | — | The apps that composition names, read out of the lock so a box can compare what it asked for with what the container declares. | templates/instance/bin/images-from-lock.sh (×2) |
FORGE_COMPOSITION_AXIS | — | instance declares that this bake is a box’s own list, which may compose the box’s own apps; the image is stamped not offerable. It must agree with the list’s own axis when the list declares one. Empty takes the list’s axis, then the build matrix, then the strict offer axis. | infra/Dockerfile (×2)infra/admin.Dockerfile (×2)infra/checkout.Dockerfile (×2)+2 more |
FORGE_COMPOSITION_ID | base | The name of that composition, carried into the image so a running box can say which one it is. | infra/Dockerfile (×2)infra/admin.Dockerfile (×2)infra/checkout.Dockerfile (×2)+4 more |
FORGE_CONTROL_ALLOW_CIDR | 127.0.0.1/32 | Space-separated CIDRs allowed to reach the control face. The default is loopback, so the public interface answers 403 — fill it only for a VPN or bastion range. | infra/caddy/Caddyfileinfra/docker-compose.prod.ymltemplates/instance/caddy/Caddyfile+1 more |
FORGE_CUSTOMER_ASSERTION_PRIVATE_KEY | — | The Ed25519 private key the storefront signs the shopper factor assertion with — the private half of the kernel’s public one. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/storefront-kit/src/config.ts+1 more |
FORGE_DB_POOL_AUTH_TYPE | scram-sha-256 | How the pooler authenticates its clients. | infra/docker-compose.prod.yml |
FORGE_DB_POOL_MAX_CLIENT_CONN | 200 | How many clients may queue at the pooler — set it above the whole fleet’s own pools. | infra/docker-compose.prod.yml |
FORGE_DB_POOL_SERVER_TLS_SSLMODE | — | TLS mode on the pooler’s upstream leg, which a managed database usually demands. | infra/docker-compose.prod.yml |
FORGE_DB_POOL_SIZE | 20 | How many server connections the pooler opens — set it under the database’s own maximum. | infra/docker-compose.prod.yml |
FORGE_DB_UPSTREAM_URL | — | The managed Postgres the connection pooler fronts. Only read when the pooling profile is on. | infra/docker-compose.prod.yml |
FORGE_DEMO_CATALOG_BASE_URL | — | A mirror to pull the demo photo tree from instead of the published one. Read by the one-shot seed, ignored by the server. | infra/docker-compose.prod.yml |
FORGE_DEV_ADMIN_UPSTREAM | host.docker.internal:3031 | Where the bench’s https edge falls back to for the admin when no admin container answers: the admin dev server on the host (next dev). | infra/caddy/Caddyfile.bench-tls |
FORGE_DEV_CHECKOUT_UPSTREAM | host.docker.internal:3032 | Where the development edge forwards checkout, account and login paths. | docker-compose.ymlinfra/caddy/Caddyfile.dev (×7) |
FORGE_DEV_STOREFRONT_UPSTREAM | host.docker.internal:3030 | Where the development edge forwards vitrine paths. | docker-compose.ymlinfra/caddy/Caddyfile.dev |
FORGE_DOMAIN | must be set | The public storefront hostname the edge serves and provisions a certificate for. The DNS record must point at the box before it starts. | infra/caddy/Caddyfileinfra/cicd/deploy-remote.sh (×4)infra/cicd/reseed-staging.sh+4 more |
FORGE_EDGE_PORT | 3033 | Host port the development edge is published on. | docker-compose.ymlscripts/boot/bench-ports.shscripts/demo-local.sh |
FORGE_EXTENSIONS_HOST_DIR | ./infra/extensions | The host directory mounted into the kernel as this box’s own apps. | docker-compose.ymlinfra/docker-compose.prod.ymltemplates/instance/compose.yml |
FORGE_GATE_ADMIN_URL | — | The admin origin that gate’s open the admin link navigates to. | docker-compose.yml (×2)infra/docker-compose.prod.yml (×2) |
FORGE_GATE_SITE_URL | — | The back target of the gate a storefront copy may register. Unset: the gate’s own default. | docker-compose.yml (×2)infra/docker-compose.prod.yml (×2) |
FORGE_GOOGLE_CLIENT_ID | — | Google OIDC client id for shopper sign-in. Absent: the Google button renders disabled, never broken. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/storefront-kit/src/config.ts+1 more |
FORGE_GOOGLE_CLIENT_SECRET | — | Google OIDC client secret. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/storefront-kit/src/config.ts+1 more |
FORGE_HTTPS_PORT | 8243 | The https door of the shop: on an instance bench promoted to a host, IP or tailnet (bash bench/promote.sh), the port a browser opens on that address. Unset: | templates/instance/bench/compose.edge-tls.ymltemplates/instance/bench/lib.sh (×3)templates/instance/bench/up.sh (×2) |
FORGE_HTTP_PORT | 8200 | The host port of an instance bench’s shop door (storefront + checkout behind the edge). Unset: | templates/instance/bench/compose.bench.ymltemplates/instance/bench/lib.sh (×3)templates/instance/bench/up.sh |
FORGE_IMAGE | must be set | The kernel image the box runs, by digest. | infra/cicd/prove-running-image.sh (×3)infra/cicd/reseed-staging.sh (×2)infra/cicd/reset-staging-demo.sh (×2)+3 more |
FORGE_INSTANCE_APPS | — | A directory inside the build context holding the OWNER’s own apps, which the oven adopts so they compose like a shipped one. Empty for every platform build; a bake from a published oven hands the owner’s apps in as the build context named apps instead. | infra/Dockerfile (×2)infra/admin.Dockerfile (×2)infra/checkout.Dockerfile (×2)+2 more |
FORGE_KERNEL_PORT | 9030 | Host port the kernel is published on in development. | docker-compose.ymlscripts/admin-demo.shscripts/boot/bench-ports.sh+3 more |
FORGE_KERNEL_SERVICE | kernel | The compose service name the verification script asks for the running composition. | templates/instance/bin/verify-composition.sh (×3) |
FORGE_KERNEL_SHA | — | The git commit the image was built from, baked at build time. | infra/Dockerfileinfra/admin.Dockerfileinfra/checkout.Dockerfile+3 more |
FORGE_LOCK | — | Which lock file a box reads its pinned image digests and composition from. Unset: the forge.lock beside the scripts. | templates/instance/bin/images-from-lock.sh (×14)templates/instance/bin/verify-composition.sh (×6) |
FORGE_MAIL_HTTP_PORT | 8204 | The host port of an instance bench’s mailbox web face, where login codes are read. Unset: | templates/instance/bench/compose.bench.ymltemplates/instance/bench/mail.shtemplates/instance/bench/up.sh (×2) |
FORGE_MEDIA_LOCAL_DIR_HOST | ./.forge-media | The host directory mounted into the kernel as the local media store. | docker-compose.yml |
FORGE_OTLP_GRPC_PORT | 4317 | Host port of the development OTel collector’s OTLP gRPC receiver (default 4317); FORGE_BENCH_PORT_BLOCK sets it with every other bench port. | docker-compose.yml |
FORGE_OTLP_HTTP_PORT | 4318 | Host port of the development OTel collector’s OTLP HTTP receiver (default 4318); FORGE_BENCH_PORT_BLOCK sets it with every other bench port. | docker-compose.yml |
FORGE_POSTGRES_PORT | 5432 | Host port Postgres is published on in development (default 5432). The bench scripts derive the seeds’ DATABASE_URL from it; FORGE_BENCH_PORT_BLOCK sets it with every other bench port. | docker-compose.ymlscripts/admin-demo.shscripts/boot/bench-ports.sh+1 more |
FORGE_PSQL_IMAGE | postgres:18 | The Postgres client image the reset script runs psql from. | infra/cicd/reset-staging-demo.sh |
FORGE_REDIS_PORT | 6379 | Host port Redis is published on in development (default 6379); FORGE_BENCH_PORT_BLOCK sets it with every other bench port. | docker-compose.ymlscripts/boot/bench-ports.sh |
FORGE_REGISTRY | — | The registry prefix the image refs are built from. Set it and the region and repository variables have no job left. | infra/env-source.sh (×6) |
FORGE_RELEASE | — | The release the image is baked as, checked against what the composition may name. Empty on an ordinary build. | infra/Dockerfile (×2)infra/admin.Dockerfile (×2)infra/checkout.Dockerfile (×2)+4 more |
FORGE_SEED_DATASET_BASE_URL | — | Overrides where the dataset’s missing files are pulled from, for a box mirroring the tree into its own bucket. Plain HTTPS, no credential. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/seed-dataset/src/hydrate.ts (×2)+1 more |
FORGE_SEED_DATASET_DIR | /app/seed-dataset | The dataset directory this box mounted, inside the container. Unset — the ordinary case for a customer who wants no example data — makes the seed a no-op that says so. | docker-compose.ymlinfra/cicd/prove-running-image.shinfra/docker-compose.prod.yml+3 more |
FORGE_SEED_DATASET_HOST_DIR | ./instances/reference/dataset | The host directory mounted into the kernel as the seed dataset. | docker-compose.ymlinfra/cicd/prove-running-image.sh (×3)infra/cicd/reset-staging-demo.sh+1 more |
FORGE_STOREFRONT_IMAGE | must be set | The storefront image the box runs, by digest. | infra/docker-compose.prod.ymltemplates/instance/compose.yml |
FORGE_STOREFRONT_PORT | 3030 | Host port the storefront is published on in development. | docker-compose.ymlscripts/admin-demo.sh (×3)scripts/demo-local.sh |
FORGE_STORE_HOSTS | — | A local-development map pinning a hostname to a store id without touching data. Unset in production, where the port answers instead. | docker-compose.yml (×2)infra/cicd/prove-running-image.shinfra/docker-compose.prod.yml (×2)+4 more |
FORGE_TIER_HEALTH_INTERVAL | 3 | How often, in seconds, that probe asks. | infra/cicd/probe-tier-health.sh |
FORGE_TIER_HEALTH_TIMEOUT | 180 | How long, in seconds, the deploy probe waits for a tier to become healthy. | infra/cicd/probe-tier-health.sh |
FORGE_TLS_CERT_DIR | ./infra/caddy/bench-certs | A directory of certificates the box was GIVEN, for a CDN that terminates TLS and never lets the challenge through. Empty: the edge keeps issuing its own. Default ./caddy/certs beside this compose; on a local bench promoted to a hostname (pnpm bench:promote <host>), ./infra/caddy/bench-certs — the PEMs its https edge serves instead of its local CA. | docker-compose.ymlinfra/docker-compose.prod.ymlscripts/boot/bench-address.sh+1 more |
FORGE_TRUSTED_PROXY_CIDRS | — | Space-separated CIDRs of the CDN or load balancer in front of this box, whose x-forwarded-for the edge believes. Empty: no proxy is trusted and the TCP peer is the client, which behind a CDN makes every per-address cap count the CDN’s edge. | infra/caddy/Caddyfileinfra/docker-compose.prod.ymltemplates/instance/caddy/Caddyfile+1 more |
Kernel
Section titled “Kernel”| Variable | When unset | What it does | Read at |
|---|---|---|---|
FORGE_ADMIN_HOST | — | The hostname this tenant’s admin answers on, claimed in the global admin directory at provisioning so one admin deployment can serve many tenants. Undeclared on a deployed box, the deploy glue derives it from FORGE_ADMIN_DOMAIN, so the address the edge serves is the address the box claims; declare it only when the two differ. | apps/api/src/reference-env.tsdocker-compose.ymlinfra/docker-compose.prod.yml+2 more |
FORGE_ADMIN_SEED_EMAIL | (none) | The first admin operator to create when a reference instance is provisioned. Unset: no operator is seeded. On the dev bench it is the operator seed:admin invites: unset there, a reserved bench address is invited and the login code is read from the kernel’s log — and a bench with FORGE_SMTP_* set refuses to seed until it names a mailbox somebody can read. | apps/api/src/demo-operator.ts (×2)apps/api/src/reference-env.tsdocker-compose.yml+5 more |
FORGE_ADMIN_SEED_NAME | — | That first operator’s display name. | apps/api/src/demo-operator.ts (×2)apps/api/src/reference-env.tsdocker-compose.yml+2 more |
FORGE_AUDIT_RETENTION_DAYS | — | How long an audit row is kept before the sweeper deletes it. A zero or negative value would purge everything, so it falls back to the default instead. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/core/src/maintenance/audit-retention.ts+1 more |
FORGE_BULK_READ_LIMIT_PER_CREDENTIAL | 1200 | The bulk read face’s own budget per credential — a separate bucket, so a catalogue sweep and an integration’s writes are not one shared fate. Unset: the measured default. | apps/api/src/bulk-read-cap.tsapps/api/src/index.tsdocker-compose.yml+2 more |
FORGE_CUSTOMER_ASSERTION_PUBLIC_KEY | — | The Ed25519 public key that verifies the storefront’s shopper factor assertion on the anonymous social-login mint, where it is the only trust anchor there is. | apps/api/src/index.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_DECISIONS_POOL_SIZE | — | How many decisions the kernel may consult at once. Anything not an integer of at least one falls back to the default rather than being honoured. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/core/src/decisions/worker-pool.ts+1 more |
FORGE_DISK_ALARM_PERCENT | 85 | Used share of the disk (1–100, as df prints Use%) at or above which the kernel logs disk_alarm state=high once and the admin draws a warning band. Unset: 85. | apps/api/src/index.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_DISK_WATCH_PATH | / | The path, inside the kernel container, whose filesystem the disk alarm measures. Unset: /, which under docker’s overlay storage is the host disk that also holds the volumes. Mount a separate data disk into the kernel and name it here when the database or a cache lives on one. | apps/api/src/index.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_EXTENSIONS_DIR | — | The directory inside the container the kernel loads this box’s OWN apps from. Unset: only the apps compiled into the image. | apps/api/src/app-install.tsapps/api/src/extension-loader.tsapps/api/src/index.ts+4 more |
FORGE_EXTENSION_ACTION_TIMEOUT_MS | — | Ceiling on one app action, in milliseconds. It bounds the pathological case; it does not police duration. Unset or unparseable: thirty minutes (the measured cost of an honest full-catalogue seed, with margin). | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/core/src/extension-exec/timeout.ts+1 more |
FORGE_KERNEL_URL | http://localhost:3000 | Where the instance check drives the port when it probes a running box. | apps/api/src/instance-check.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_KERNEL_VERSION | dev | The release this image is, as read.platform_info reports it. Unset: dev. | docker-compose.ymlpackages/core/src/platform-info.tstemplates/instance/bench/up.sh+3 more |
FORGE_MEDIA_BASE_URL | — | The public base the read face prefixes onto every media key. Explicit wins; otherwise the local driver derives its own and a cloud driver warns and serves media by reference. | apps/api/src/storage-connector.tsapps/storefront/src/app/api/img/[...spec]/route.ts (×2)apps/storefront/src/app/api/media/[...key]/route.ts+8 more |
FORGE_MEDIA_LIMIT_PER_CREDENTIAL | 600 | How many upload plans one CREDENTIAL may be granted per window on the media command face (/v1/media/commands/*). Each plan is a signed URL, i.e. permission to place one object in the tenant’s store, so this bounds licensed bucket writes rather than database work — which is why it is a separate, tighter bucket from the command face’s. Unset: the measured default. Raise it for a one-off catalogue migration that pushes images through the port. | apps/api/src/index.tsapps/api/src/media-cap.tsdocker-compose.yml+2 more |
FORGE_MEDIA_LOCAL_DIR | — | Directory the local driver keeps media bytes in. Unset: an in-process store, which the seed and the server cannot share. | apps/api/src/seed-media.tsapps/api/src/storage-connector.ts (×2)infra/docker-compose.prod.yml+1 more |
FORGE_MEDIA_MAX_DOCUMENT_BYTES | — | Ceiling, in bytes, on a document upload. Unset: the media command’s own default applies. | apps/api/src/index.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_MEDIA_MAX_IMAGE_BYTES | — | Ceiling, in bytes, on an image upload. Unset: the media command’s own default applies. | apps/api/src/index.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_MEDIA_UPLOAD_BASE_URL | — | The base the local driver hands out for an upload, when the address a client should PUT to is not the one the kernel binds. | apps/api/src/storage-connector.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_OPERATOR_ASSERTION_PUBLIC_KEY | — | The Ed25519 public key that verifies the admin’s operator factor assertion. Set: the kernel requires the assertion. Unset in production: it warns and mints as it did before the assertion existed. | apps/api/src/index.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_ORPHAN_RUN_GRACE_MS | — | How long an app invocation may sit without moving before the kernel presumes the process running it died and closes the row as abandoned. Unset: twice the action ceiling, so an instance that raises the ceiling raises this with it. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/core/src/commands/extension-runs.ts+1 more |
FORGE_PLATFORM_EXTENSIONS_DIR | — | Overrides where the kernel finds the apps BUNDLED in the image. It exists for a test packing artifacts into a temp directory; a box never sets it. | apps/api/src/extension-loader.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_PUBLIC_ORIGIN | http://localhost:9030 | The absolute origin this box publishes its store on, for URLs baked into edge-cached pages that no request’s own Host may decide. | apps/api/src/storage-connector.tsapps/storefront/scripts/warm/cli.tsdocker-compose.yml (×2)+3 more |
FORGE_PUBLIC_WRITE_LIMIT_PER_IP | 30 | How many writes one ADDRESS may spend per window on the anonymous public face (/v1/ext-public/*, /v1/ext-customer/*) — the door where a caller with no credential creates an app’s data, a review the commonest. Abuse dampening, never a correctness gate. Unset: 30, which is deliberately tight for production and is the number a from-zero seed has to pace itself under. | apps/api/src/public-write-cap.ts (×2)docker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_PUBLIC_WRITE_WINDOW_SECONDS | 60 | The window the ceiling above is counted in, in seconds. Its OWN variable rather than the credential face’s: an operator retuning an integration’s budget must not silently retune the anonymous door as well. Unset: 60. | apps/api/src/public-write-cap.ts (×2)docker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_RATE_LIMIT_PER_CREDENTIAL | 6000 | Requests one credential may spend per window on commands and internal reads. | apps/api/src/credential-rate-limit.tsapps/api/src/index.tsdocker-compose.yml+2 more |
FORGE_RATE_LIMIT_WINDOW_SECONDS | 60 | The length of that window, in seconds. One window for the whole box, so two RateLimit-Reset headers speak the same units. | apps/api/src/index.ts (×3)docker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_REF_LOCALE | — | The language a reference instance is born declaring (BCP-47, e.g. ‘pt-BR’). It is what operators without a preference read the admin in, and what the shopper’s e-mails are written in. | apps/api/src/reference-env.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_REF_STORE_HANDLE | forge-ref | That reference store’s handle. | apps/api/src/reference-env.tsdocker-compose.ymlinfra/cicd/reset-staging-demo.sh+4 more |
FORGE_REF_STORE_NAME | Loja 1 | That reference store’s display name. | apps/api/src/reference-env.tsdocker-compose.ymlinfra/docker-compose.prod.yml+2 more |
FORGE_REF_TENANT | referencia | The tenant id a reference instance is provisioned and seeded under. | apps/api/src/reference-env.tsdocker-compose.ymlinfra/cicd/reset-staging-demo.sh (×3)+5 more |
FORGE_REF_TIMEZONE | — | The clock a reference instance is born declaring (an IANA name such as ‘America/Sao_Paulo’, never an offset). Every screen and every e-mail renders instants in it. | apps/api/src/reference-env.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_RELAY_SETTLE_INTERVAL_MS | 30000 | Minimum milliseconds between two settlement passes of the relay in one tenant schema. A pass briefly holds that schema’s event writers; between passes an idle relay reads only what was written since the last one. | apps/api/src/index.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_REQUIRE_CUSTOMER_ASSERTION | — | 1 turns the unset shopper assertion key into a fatal boot error. Any box that enables social login should set it. | apps/api/src/index.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_REQUIRE_OPERATOR_ASSERTION | — | 1 turns the unset operator assertion key into a fatal boot error instead of a warning. | apps/api/src/index.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_SEED_DEMO | — | 1 is the explicit opt-in that lets the demo seed run at all. Without it the entrypoint refuses. | apps/api/src/seed-demo.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_SEED_STORE_HOST | — | The routing hostname the demo seed writes onto the store it seeds. Unset: the seed omits the field, so no existing store is repointed by accident. | apps/api/src/seed-storefront.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_SEED_STORE_NAME | — | The display name the demo seed writes onto that store. Unset: the field is omitted. | apps/api/src/seed-storefront.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_SMOKE_HOST | — | A store hostname for the instance check’s smoke test to resolve. Unset: it skips the host-resolution step. | apps/api/src/instance-check.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_SMTP_FROM | — | The From the box sends as. Only the address half is used; the display name is replaced per message by the store’s. | apps/api/src/smtp-channel-driver.ts (×2)docker-compose.ymlinfra/docker-compose.prod.yml+3 more |
FORGE_SMTP_HOST | — | The SMTP host that carries this box’s mail. One of the four that must be set together before the transport is configured at all. | apps/api/src/smtp-channel-driver.ts (×2)docker-compose.ymlinfra/docker-compose.prod.yml+3 more |
FORGE_SMTP_PASS | — | The SMTP password. | apps/api/src/smtp-channel-driver.ts (×2)docker-compose.ymlinfra/docker-compose.prod.yml+2 more |
FORGE_SMTP_PORT | 587 | The SMTP submission port. Unset: 587. | apps/api/src/smtp-channel-driver.tsdocker-compose.ymlinfra/docker-compose.prod.yml+3 more |
FORGE_SMTP_USER | — | The SMTP username. | apps/api/src/smtp-channel-driver.ts (×2)docker-compose.ymlinfra/docker-compose.prod.yml+2 more |
FORGE_STORAGE_ACCESS_KEY_ID | — | The access key ID the s3 driver signs media uploads with. Required by that driver. | apps/api/src/storage-connector.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_STORAGE_BUCKET | — | The bucket a cloud driver writes to. Required by every one of them, which refuse to build without it. | apps/api/src/storage-connector.ts (×2)docker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_STORAGE_CLIENT_EMAIL | — | The service-account address that signs media URLs. Omitted on the keyless path, where the VM’s own identity signs. | apps/api/src/storage-connector.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_STORAGE_DRIVER | local | Which storage backend serves media: local (dev and test), gcs, or s3 for any S3-compatible bucket. A name this build does not carry stops the boot, by name. | apps/api/src/seed-media.tsapps/api/src/storage-connector.tsdocker-compose.yml+2 more |
FORGE_STORAGE_ENDPOINT | — | The S3-compatible endpoint the s3 driver addresses: scheme and host of the account, never a per-bucket URL. Required by that driver. | apps/api/src/storage-connector.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_STORAGE_PRIVATE_KEY | — | A service-account private key that signs media URLs locally, for an organisation that allows key creation. Unset: the box signs through its own attached identity. | apps/api/src/storage-connector.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_STORAGE_REGION | — | The region the s3 driver names in its signature scope. Unset: the value a region-less bucket expects. | apps/api/src/storage-connector.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_STORAGE_SECRET_ACCESS_KEY | — | The secret the s3 driver derives its SigV4 signing key from. Required by that driver, and it never leaves the kernel process. | apps/api/src/storage-connector.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_VAULT_KEY | must be set | The key the kernel encrypts an app’s connection secrets with. A dev default keeps docker compose up working; the production compose refuses to start without a real one, and rotating it re-keys every stored secret. | apps/api/src/index.ts (×2)docker-compose.ymlinfra/docker-compose.prod.yml+5 more |
| Variable | When unset | What it does | Read at |
|---|---|---|---|
FORGE_ADMIN_ACCESS_KEY | — | An operator access key the gated entry route redeems to sign a visitor straight in. Unset: the route is inert and falls through to the ordinary login. | apps/admin/src/app/enter/route.tsapps/admin/src/app/team/page.tsxdocker-compose.yml+2 more |
FORGE_ADMIN_ACCESS_KEYS | — | The gated entry route’s per-tenant redeem inputs on a host-mode box, as JSON {"<tenant-id>": {"store": …, "key": …}}. A tenant absent from it simply has no gated entry; its key is never spent on another tenant’s hostname. | apps/admin/src/lib/config.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_ADMIN_DEFAULT_LOCALE | — | The language an operator lands in before choosing one, ahead of the browser’s Accept-Language. A bootstrap only — the real setting lives in the admin. | apps/admin/src/lib/locale.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_ADMIN_I18N_DIR | — | Directory the admin reads partial translation catalogs from (<dir>/<locale>.json), so a client can change words without a fork. Unset: the shipped catalogs. | apps/admin/src/i18n/catalog.ts (×2)apps/api/src/instance-check.ts (×2)docker-compose.yml (×2)+2 more |
FORGE_ADMIN_OPS_LOGIN | — | 1 turns on the break-glass login: pasting a raw operator token, for recovering a box whose e-mail and OIDC are both broken. | apps/admin/src/lib/config.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_ADMIN_PLATFORM_TOKEN | — | One platform credential per box, scoped to minting a short-lived login driver for a tenant whose hostname this admin serves. Unset: the box keeps using the per-tenant secrets. | apps/admin/src/lib/config.tsdocker-compose.ymlinfra/docker-compose.prod.yml+2 more |
FORGE_ADMIN_SECURE_COOKIE | — | 1 marks the admin’s cookies Secure outside production — for a box that is behind an HTTPS edge without NODE_ENV=production. | apps/admin/src/lib/session.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_ADMIN_SERVICE_TOKEN | — | The instance’s login-driver credential — a narrow tenant actor the admin drives the login commands with, for an operator who has no token yet. | apps/admin/src/lib/config.tsdocker-compose.ymlinfra/docker-compose.prod.yml+2 more |
FORGE_ADMIN_SERVICE_TOKENS | — | The login drivers of a host-mode box, as JSON {"<tenant-id>": "<token>"}. Read only when FORGE_ADMIN_TENANT is unset. | apps/admin/src/lib/config.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_ADMIN_SIBLINGS | — | The other admin instances of the same multi-brand group, as JSON [{"name": …, "url": …}]. Stated by the deployer; never discovered. | apps/admin/src/lib/config.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_ADMIN_TENANT | — | Pins this admin to one tenant. Unset puts the box in host mode, where the request hostname decides which tenant it serves. | apps/admin/src/lib/config.tsdocker-compose.ymlinfra/env-source.sh (×2)+1 more |
FORGE_API_BASE_URL | http://localhost:3000 | Where the admin server reaches the kernel’s command port and internal read face. Compose-internal; never shown to a browser. | apps/admin/src/lib/config.ts |
FORGE_API_PUBLIC_URL | — | The origin the internet reaches this kernel on, for every address the admin asks a human to paste elsewhere (an app’s webhook URL). Unset: those screens say so instead of printing the internal one. | apps/admin/src/lib/config.tsdocker-compose.ymlscripts/admin-demo.sh (×2) |
FORGE_BUILD_STANDALONE | — | 1 builds a Next app in standalone output, set only by the Dockerfiles. Off for the everyday build, which is what the test suite runs. | apps/admin/next.config.mjsapps/checkout/next.config.mjsapps/storefront/next.config.mjs |
FORGE_OPERATOR_ASSERTION_PRIVATE_KEY | — | The Ed25519 private key (PEM) the admin signs the operator factor assertion with. Unset: no assertion is signed. | apps/admin/src/lib/config.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_REVALIDATE_SECRET | forge-local-dev-revalidate-secret | The shared secret the storefront’s /api/revalidate demands, the same value on both sides. Unset: on-demand cache busting is skipped and the fronts refresh on their own TTL. | apps/admin/src/lib/config.tsapps/api/src/storefront-purge.ts (×2)docker-compose.yml (×3)+5 more |
FORGE_STOREFRONT_PUBLIC_URL | — | The BROWSER-reachable origin this box publishes its storefront on. Distinct from the compose-internal URL, which no browser can load. Used to embed the fronts’ component galleries in the admin, and as the address of a store that is served by path (/s/<id>) because it has no public URL of its own. | apps/admin/src/lib/config.tsdocker-compose.ymlscripts/admin-demo.sh (×2) |
FORGE_STOREFRONT_URL | http://storefront:3000 | The storefront origins this admin serves, comma-separated, as its own server reaches them. Drives the synchronous cache bust after a write; the first is also the front Compose asks for the slots of a store with no public URL of its own. | apps/admin/src/lib/config.tsapps/api/src/storefront-purge.tsdocker-compose.yml (×2)+3 more |
FORGE_STORE_ID | — | The store the gated entry route redeems its access key against. The pair belongs to the tenant this admin is PINNED to; a host-mode box states its pairs per tenant instead. | apps/admin/src/app/enter/route.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
Storefront
Section titled “Storefront”| Variable | When unset | What it does | Read at |
|---|---|---|---|
FORGE_EDGE_PURGE_DRIVER | — | Which registered edge-purge driver this build runs. An unknown id degrades to none, never a crash on the invalidation path. | apps/storefront/src/lib/edge-purge.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_INTERNAL_ORIGIN | — | Where the image route calls this very process back on. Never the public host. Unset: loopback on the port the process bound. | apps/storefront/src/app/api/img/[...spec]/route.tsdocker-compose.ymlinfra/docker-compose.prod.yml+1 more |
FORGE_WARM_READ_TOKEN | — | Tenant read token the storefront cache warmer presents on the internal read face when it enumerates the tenant’s stores. Unset: the all-stores mode refuses by name, and warming one named store still works. | apps/storefront/scripts/warm/cli.ts |
Checkout
Section titled “Checkout”| Variable | When unset | What it does | Read at |
|---|---|---|---|
FORGE_HIDE_DEV_INDICATORS | — | 1 hides Next’s development overlay, for a front served to people from a non-production build. | apps/checkout/next.config.mjsapps/storefront/next.config.mjs |
Storefront and checkout
Section titled “Storefront and checkout”| Variable | When unset | What it does | Read at |
|---|---|---|---|
FORGE_COMMAND_BASE_URL | — | The write port the fronts call. Unset: the read base, because in the api app both faces are one server. | packages/storefront-kit/src/config.ts |
FORGE_DATA_CACHE_DIR | — | Where the storefront keeps its cached port reads. A box mounts a volume here so the cache never lands in the container layer. Unset: .next/cache/forge-data-cache beside the app. | packages/storefront-kit/src/data-cache/handler.mjs |
FORGE_DATA_CACHE_MAX_MB | — | Ceiling of the storefront’s cached port reads on disk, in MiB; the least recently used entries are evicted to stay under it. Unset: 2048. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/storefront-kit/src/data-cache/handler.mjs+1 more |
FORGE_DATA_CACHE_MIN_FREE_PERCENT | — | Below this share of free disk (or 1 GiB) the storefront stops writing its data cache and logs it once. Unset: 5. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/storefront-kit/src/data-cache/handler.mjs+1 more |
FORGE_IMAGE_URL_ORIG | — | URL template for the original-format lane of that service — what a browser without webp, a crawler and the fallback all fetch. | docker-compose.yml (×2)infra/docker-compose.prod.yml (×2)packages/storefront-kit/src/media/driver.ts (×2)+1 more |
FORGE_IMAGE_URL_WEBP | — | URL template for the webp lane of an external image service. Both lanes and a media base must be set, or the built-in driver serves everything. | docker-compose.yml (×2)infra/docker-compose.prod.yml (×2)packages/storefront-kit/src/media/driver.ts (×2)+1 more |
FORGE_REVALIDATE_SECONDS | — | How long a port read’s answer stays cached, in seconds. A backstop — invalidation by event is the authority. Never applied below the page window. | docker-compose.yml (×2)infra/docker-compose.prod.yml (×2)packages/storefront-kit/src/config.ts+1 more |
FORGE_STOREFRONT_GATE_COOKIE_DOMAIN | — | the domain suffix one gate dismissal covers (e.g. example.com ⇒ entering at any host under it dismisses at all of them). Unset (the default) = host-only, the address the visitor entered at and no other. Ignored, with a warning, on any address that is not under the suffix — which is why the local bench needs no change. | docker-compose.yml (×2)infra/docker-compose.prod.yml (×2)packages/storefront-kit/src/gate/cookie-scope.ts+1 more |
FORGE_STOREFRONT_SECURE_COOKIE | — | 1 marks the shopper’s cookies Secure outside production, for a front behind an HTTPS edge. One rule for both deployables. | docker-compose.yml (×2)infra/docker-compose.prod.yml (×2)packages/storefront-kit/src/cookies.ts+1 more |
FORGE_THEMES_DIR | — | An extra directory to look for a theme in, ahead of the ones the layout implies. | docker-compose.yml (×2)infra/docker-compose.prod.yml (×2)packages/storefront-kit/src/theme/resolve.ts+1 more |
| Variable | When unset | What it does | Read at |
|---|---|---|---|
FORGE_HOME | — | Where the CLI keeps its custody file. Unset: ~/.forge. It is how one operator runs several identities, and how CI has custody at all. | apps/cli/src/config.ts |
FORGE_INSTANCE | — | Which stored instance a CLI command resolves against, when no --instance is given. | apps/cli/src/connection.ts |
FORGE_TOKEN | — | The credential a CLI command talks with. It deliberately BEATS custody, so a pipeline’s key is not lost to a stale file on a laptop. | apps/cli/src/connection.tsapps/cli/src/login.tspackages/codegen/src/portal.ts |
FORGE_URL | — | The box a CLI command talks to, when no --url is given and before custody is consulted. | apps/cli/src/connection.ts (×2)apps/cli/src/login.ts |
MCP server
Section titled “MCP server”| Variable | When unset | What it does | Read at |
|---|---|---|---|
FORGE_MCP_STORE | — | The store the stdio MCP server buys from. A stdio process has no hostname, so its environment is its server config. | apps/mcp/src/bin-config.ts |
FORGE_MCP_TENANT | — | Which tenant that credential’s commands run against. | apps/mcp/src/bin-config.ts |
FORGE_MCP_TOKEN | — | The single service identity the stdio MCP server acts as. Absent: only the public tools are served. | apps/mcp/src/bin-config.ts |
| Variable | When unset | What it does | Read at |
|---|---|---|---|
FORGE_SEED_CONCURRENCY | 16 | Lowers how hard the demo seed leans on the database: the stock adjusts in flight (1 to 16). Products in flight and the seed’s connection pool follow at today’s ratio (12 and 24 at 16), so a small box can seed slower instead of choking. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/seed-dataset/src/concurrency.ts (×2)+1 more |
FORGE_SEED_DATASET_REFRESH | — | Re-pulls every dataset file even when it is already on disk, for refreshing a stale cache after a re-curation. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/seed-dataset/src/hydrate.ts (×3)+1 more |
FORGE_SEED_PHOTOS_DIR | — | Relocates the per-product photo tree — gigabytes — off the container layer onto a big disk. | docker-compose.ymlinfra/docker-compose.prod.ymlpackages/seed-dataset/src/photos.ts (×3)+1 more |
| Variable | When unset | What it does | Read at |
|---|---|---|---|
FORGE_READ_BASE_URL | http://localhost:3001 | The read port the fronts and the shipped apps call — the only backend they know. | apps/storefront/scripts/warm/cli.tsextensions/leads/block.tsxextensions/leads/submit.ts+10 more |
Repository tooling
Section titled “Repository tooling”| Variable | When unset | What it does | Read at |
|---|---|---|---|
FORGE_ADMIN_DEMO_DRY_RUN | — | Set to any value to make the admin bench script run only its kernel preflight — what it would carry over from a kernel this box already runs, and the warning it would print — and exit before its first side effect, instead of bringing a box up. | scripts/admin-demo.sh |
FORGE_ADMIN_HTTPS_PORT | 6443 | The dedicated https port that fronts the admin in the bench (tailscale serve or the edge-tls Caddy). On an instance bench it is | docker-compose.ymlscripts/admin-demo.shscripts/bench-promote.sh+4 more |
FORGE_BENCH_ADDRESS | localhost | Where the local bench is reached: localhost (the default), tailnet (this machine’s tailnet, TLS by tailscale serve), or a bare hostname/IP (TLS by the bench’s own Caddy, edge-tls). Written into .env by pnpm bench:promote <where>; read by pnpm demo and pnpm admin:demo. An instance bench reads the same name with the same three destinations, written by bash bench/promote.sh <where> into .forge-bench/address.env (templates/instance/bench/lib.sh). | scripts/bench-promote.shscripts/boot/bench-address.sh (×2)templates/instance/bench/lib.sh (×4) |
FORGE_BENCH_PORT_BLOCK | 82 | Two digits (11–99) that move every host port of a local bench to NNxx, so a second bench of this repository can run beside the first; unset keeps the ports of always, and any individual port variable still wins. Read by pnpm demo and pnpm admin:demo, and by an instance bench (templates/instance/bench/up.sh: doors at NN00 shop · NN01 admin · NN04 mailbox · NN05 kernel; unset there means block 82). | scripts/boot/bench-ports.sh (×2)templates/instance/bench/lib.shtemplates/instance/bench/up.sh |
FORGE_DATASET_PUBLISH_ACCESS_KEY_ID | — | The access key ID a pack:dataset publish signs its S3 requests with. Required by the S3-compatible destination. | scripts/publishing/dataset-publish-s3.ts (×2) |
FORGE_DATASET_PUBLISH_BUCKET | — | The bucket a pack:dataset publish writes to on the S3-compatible destination. Required by that destination. | scripts/publishing/dataset-publish-s3.ts (×2)scripts/publishing/pack-dataset.ts |
FORGE_DATASET_PUBLISH_ENDPOINT | — | The S3-compatible endpoint (scheme and host of the account) that pack:dataset publishes a dataset to instead of gcloud storage rsync. Unset: the gcloud destination. | scripts/publishing/dataset-publish-s3.ts (×2) |
FORGE_DATASET_PUBLISH_REGION | — | The region a pack:dataset publish names in its S3 signature scope. Unset: the value a region-less bucket (R2) expects. | scripts/publishing/dataset-publish-s3.ts (×2) |
FORGE_DATASET_PUBLISH_SECRET_ACCESS_KEY | — | The secret a pack:dataset publish derives its SigV4 signing key from. Required by the S3-compatible destination; never printed. | scripts/publishing/dataset-publish-s3.ts (×2) |
FORGE_DEMO_DRY_RUN | — | Set to any value to make the bench script PRINT the front step it would run and exit before its first side effect, instead of bringing a box up. It is how scripts/boot/front-image-mode.guard.test.ts asks which fronts the default mode serves without a machine. | scripts/demo-local.sh |
FORGE_DEMO_HOST | — | DEPRECATED alias of FORGE_BENCH_ADDRESS, read only when that is absent (with a warning): localhost stays localhost, a *.ts.net name becomes the tailnet destination with that name, anything else a hostname destination. | scripts/boot/bench-address.sh (×2) |
FORGE_ENV_FILE | — | The file a bring-up script reads its declared configuration from — the same file compose is pointed at when a run names one. Unset: the .env beside docker-compose.yml, which compose reads by itself. | apps/api/scripts/bench-env.tsscripts/boot/env-file.sh |
FORGE_GUARD_TARBALLS | — | Where the packing step leaves the tarballs the publishing guards install. Set by the suite’s own setup. | scripts/publishing/pack.globalSetup.ts (×2)scripts/publishing/tarballs.ts (×2) |
FORGE_KERNEL_HTTPS_PORT | 9443 | The https port that fronts the kernel’s media in the bench (tailscale serve or the edge-tls Caddy). | docker-compose.ymlscripts/admin-demo.sh (×2)scripts/bench-promote.sh+2 more |
FORGE_PACK_FORCE_BUILD | — | 1 makes the packing script rebuild every package instead of trusting what is already built. | scripts/pack-publishable.sh |
FORGE_SECRETS_FILE | — | The bench box’s secret store: NAME=value per line, git-ignored, read by the bring-up scripts and written by the seed that mints the box’s own credentials (the tenant operator, and the bulk reader the storefront presents). Unset: the .secrets beside docker-compose.yml. | scripts/boot/secrets.sh |
FORGE_STOREFRONT_HTTPS_PORT | 7443 | The https port that fronts the storefront in the bench (tailscale serve or the edge-tls Caddy). | docker-compose.ymlscripts/admin-demo.shscripts/bench-promote.sh+2 more |
FORGE_TAILNET_HOST | — | The MagicDNS name of this machine, for the bench’s tailnet destination. Unset, it is read from tailscale status — only when that destination was asked for. Same name as the demo repository’s, and an instance bench’s (bash bench/promote.sh tailnet). | scripts/boot/bench-address.sh (×4)templates/instance/bench/lib.shtemplates/instance/bench/promote.sh |
FORGE_TAILNET_IP | — | This machine’s tailnet address, claimed beside FORGE_TAILNET_HOST in the bench’s store map so a device with MagicDNS off still reaches the shop. Same name as the demo repository’s; an instance bench claims it too. | scripts/boot/bench-address.shtemplates/instance/bench/lib.sh |
FORGE_TEST_POSTGRES_URI | — | How the shared Postgres container reaches the test workers. Set by the suite’s own setup, never by a person. | packages/test-support/src/shared-postgres.ts (×4) |