Skip to content
Install

Environment variables

Orchard reads its configuration from the environment. The server recognises 267 variables, grouped below as they appear in .env.example. Only DATABASE_URL and JWT_SECRET are required to start the server. The other variables are optional, unless their description says otherwise.

The Example column shows the value from .env.example, which configures a local development server. It is not always the default. For example, .env.example sets SIGNUP_MODE=open for local development, but the server defaults to invite_only. The Helm chart and the installer set production values for you.

VariableExampleDescription
DATABASE_URLpostgresql://orchard:orchard@localhost:5432/orcharddocker compose -f docker-compose.dev.yml up -d gives you this database
JWT_SECRETchange-me-to-a-long-random-stringAt least 32 characters, and not this example: the server refuses to boot otherwise. It signs every session, cookie and sign-in code.
VariableExampleDescription
PORT3001
FRONTEND_URLhttp://localhost:4000The origin the browser actually loads. In dev that is the gateway on :4000, not Vite on :3000: the API’s CORS allowlist is built from this, so pointing it at Vite makes every request from the gateway fail as a CORS error.
PLATFORM_ORIGINSExtra first-party origins allowed to make credentialed API calls, comma separated. e.g. https://docs.orchard.hackclub.com,https://status.example.com Together with FRONTEND_URL these are also the only origins a cookie session may change state from; a POST from anywhere else gets a 403.
SECRETS_ENCRYPTION_KEYEncrypts stored secret env vars; required to save secrets. Falls back to SSO_ENCRYPTION_KEY.
REDIS_URLredis://localhost:6379Cross-replica SSE event bus + cache. Optional: single-instance mode without it.
VariableExampleDescription
SIGNUP_MODEopenopen | invite_only | closed
VariableExampleDescription
USERSPACE_NODE_SCHEDULINGNode pools (taints/labels/affinity) are always superadmin-managed. Whether normal users can pick a superadmin-whitelisted pool for their own workloads is a toggle in the admin panel (Admin -> Nodes). This env var OVERRIDES that toggle when set: ‘true’ forces it on, ‘false’ forces it off and locks the switch. Leave unset to let superadmins control it from the UI (default off).

Kubernetes (optional for UI/API dev; required to deploy anything)

Section titled “Kubernetes (optional for UI/API dev; required to deploy anything)”
VariableExampleDescription
KUBECONFIG_PATHDefaults to ~/.kube/config. Accepts either a path or the kubeconfig itself base64 encoded. The server boots fine without a cluster.
CILIUM_ENABLEDCilium-backed edge features: per-tenant CiliumNetworkPolicy, and enforcing basic auth with an Envoy filter bound to the Service instead of with the protection proxy. Leave unset and the server probes the cluster for the cilium.io group plus create permission on ciliumenvoyconfigs; ‘true’ or ‘false’ skips the probe. Basic auth works either way.
PROTECTION_ORCHARD_LOGINOffer “sign in with Orchard” as an ingress protection mode. It sends visitors of a tenant host to this control plane’s login and requires project membership, so it only suits instances whose visitors have Orchard accounts. Basic auth and shared-password protection are always available. Gates picking the mode, not enforcing it: existing walls stand regardless.
K8S_STORAGE_CLASS
MAX_DATABASE_REPLICASMost instances a single managed-database cluster may run (1 primary + standbys). Every instance is a pod with its own volume and bills against quota. Defaults to 5. Also under Admin -> Limits; setting it here pins it there.
K8S_INGRESS_CLASS
CERT_CLUSTER_ISSUER
TAILSCALE_IMAGEImage of the Tailscale proxy pod. Defaults to a ghcr.io/tailscale/tailscale release pinned by digest.
RESERVED_NAMESPACES_EXTRA
CPU_REQUEST_RATIOFraction of a workload’s CPU limit it actually reserves on its node, and the millicore floor that fraction can’t go below. Defaults 0.1 / 50m. Set the ratio to 1 for the old requests == limits behaviour. Memory is unaffected.
CPU_REQUEST_MIN_MILLI
VariableExampleDescription
APP_DOMAINWildcard parent for generated app URLs (main-forge-abc123.<APP_DOMAIN>). Unset means Orchard generates no URLs at all and every deployment needs a custom domain; it never falls back to a built-in default.
HOSTNAME_STYLEopaqueStyle of NEW generated hostnames (app URLs under APP_DOMAIN, per-database TLS hostnames). opaque (default) uses a random-looking label that does not reveal the app, project or namespace, which matters because per-host certificates are published in Certificate Transparency logs. readable keeps <app>-<project>-<hash>; use it only on single-company instances where names are not sensitive. Existing hosts and custom domains are never renamed.
INGRESS_CNAMECNAME target users point their own domains at. Unset disables DNS validation for custom domains.
INSTALL_INGRESS_MODESet by the one-command installer to public, tunnel or lan, so the setup checklist lists only what applies to this instance. Leave unset otherwise.
PUBLIC_HTTP_PORTThe ports this instance is reached on from outside, which are not always the ports Traefik listens on inside the cluster: a single-box install can be told to serve somewhere other than 80 and 443 (install.sh —http-port/—https-port, lan mode only). They appear in the URL the API returns for every ingress, so a client never has to guess. Leave unset unless you moved them.
PUBLIC_HTTPS_PORTThe TLS half of the same. Both default to the standard ports.
BASE_DOMAINThe three below are independent facts, off unless set, and NOT derived from APP_DOMAIN or from each other: each needs its own DNS and wildcard cert, and in practice they diverge (the platform UI, deployed apps and org vanity hosts can all live on different domains). Parent for org vanity subdomains (acme.<BASE_DOMAIN>).
RESERVED_HOSTSComma-separated hostnames that vanity addresses, status page hosts and custom domains can never claim. The dashboard, MCP, API, docs, SCIM, registry and template URLs are always reserved; list extra hosts here.
RESERVED_HOST_SUFFIXESComma-separated domains whose whole subtree is closed to custom domains. A vanity or status label inside such a domain is still allowed when BASE_DOMAIN is that domain.
PUBLIC_DB_DOMAINAlso reserved as vanity/status labels when BASE_DOMAIN is the same domain: generated app hosts (APP_DOMAIN, PLATFORM_WILDCARD_DOMAINS), every label under PUBLIC_DB_DOMAIN and every label under SANDBOX_PREVIEW_DOMAIN. Parent for publicly exposed database hostnames. Keep in sync with the chart’s certificates.wildcards.db.domain.
PUBLIC_DB_TLS_MODEwildcardper-database: cert-manager issues one certificate per public database (own hostname only) instead of copying the shared wildcard private key into every tenant namespace. Needs PUBLIC_DB_TLS_ISSUER_NAME (a DNS-01 issuer).
PUBLIC_DB_TLS_ISSUER_NAME
PUBLIC_DB_TLS_ISSUER_KINDClusterIssuer
PUBLIC_DB_TLS_LEGACY_HOSTNAMESfalse
PUBLIC_DEPLOYMENT_DOMAINParent for publicly exposed deployment ports.
PUBLIC_EXPOSURE_IPFallback external IP that publicly exposed ports and databases are published on, for organizations that have not set one of their own. An organization with its own address still wins. Set here it also locks the matching field in the admin panel (Admin -> Configuration -> Public exposure). Unset means every organization must configure its own before it can expose anything.
TENANT_NODEPORT_EXPOSURESet to false to refuse raw NodePort exposure (exposePublic). Public ports on the organization public IP still work. Also under Admin -> Limits; setting it here pins it there.
MAX_PUBLIC_PORTS_PER_ORGMost public ports (node ports, app public ports, public databases) one organization may hold. Defaults to 20, 0 = unlimited. Also under Admin -> Limits; setting it here pins it there.
TENANT_EGRESS_BANDWIDTHCaps each tenant pod’s outbound bandwidth by setting the kubernetes.io/egress-bandwidth annotation on it, for example 50M. Empty (the default) sets nothing. Only enforced where the CNI shapes traffic: Cilium with bandwidthManager enabled, or the bandwidth CNI plugin, which k3s chains after its default Flannel. Elsewhere the annotation is ignored. Pods pick it up on their next rollout.
MAX_VOLUME_SIZELargest persistent volume a tenant may request. Defaults to 200Gi. Also under Admin -> Limits; setting it here pins it there.
PLATFORM_WILDCARD_DOMAINSComma-separated domain=tlsSecretName pairs for wildcard certs you manage. Overrides the single entry otherwise derived from APP_DOMAIN.
WILDCARD_TLS_SOURCE_NAMESPACE

Auth: OAuth/OIDC login (optional; OTP/passkey work without it)

Section titled “Auth: OAuth/OIDC login (optional; OTP/passkey work without it)”
VariableExampleDescription
AUTH_PROVIDERhackclub | oidc | none. Defaults to hackclub when HACKCLUB_CLIENT_ID is set, none otherwise.
HACKCLUB_CLIENT_IDhackclub preset
HACKCLUB_CLIENT_SECRET
HACKCLUB_REDIRECT_URIhttp://localhost:3001/apiv1/auth/callback
AUTH_OAUTH_CLIENT_IDgeneric OIDC (any IdP: Keycloak, Authentik, Dex, Google, …)
AUTH_OAUTH_CLIENT_SECRET
AUTH_OAUTH_REDIRECT_URI
AUTH_OAUTH_ISSUERdiscovery via issuer, or set the three explicit URLs instead
AUTH_OAUTH_AUTHORIZE_URL
AUTH_OAUTH_TOKEN_URL
AUTH_OAUTH_USERINFO_URL
AUTH_OAUTH_SCOPES
AUTH_OAUTH_CLAIM_IDclaim mapping; defaults sub / email / name
AUTH_OAUTH_CLAIM_EMAIL
AUTH_OAUTH_CLAIM_NAME
AUTH_OAUTH_TRUST_EMAILtrue if the IdP only hands out verified emails but omits email_verified; otherwise such logins get an unverified account (no invites, no linking by email)
AUTH_OAUTH_PKCEPKCE: on when the discovery document lists S256; true or false overrides
VariableExampleDescription
WEBAUTHN_RP_IDlocalhost
WEBAUTHN_RP_NAMEOrchard
WEBAUTHN_ORIGINhttp://localhost:4000
VariableExampleDescription
GITHUB_APP_ID
GITHUB_APP_SLUG
GITHUB_APP_PRIVATE_KEY
GITHUB_APP_WEBHOOK_SECRET
GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET
GITHUB_REDIRECT_URI

Storage: any S3-compatible provider (avatars, backups)

Section titled “Storage: any S3-compatible provider (avatars, backups)”
VariableExampleDescription
R2_ACCOUNT_IDSet these and the fields lock under Instance admin. Leave them unset to set storage in the setup flow, under Instance admin, or with orchardctl backups s3. The R2_ names are historical and work with every provider.
R2_ACCESS_KEY_ID
R2_SECRET_ACCESS_KEY
R2_BUCKET_NAME
R2_BACKUP_BUCKET
R2_PUBLIC_URLEmpty serves uploads through the API, so the bucket can stay private.
R2_ENDPOINT
R2_REGIONThe signing region. Empty means auto, which R2 expects.
R2_PATH_STYLEtrue sends requests to <endpoint>/<bucket>, false to <bucket>.<endpoint>.
LOCAL_DEPLOYS_ENABLEDLets orchard up upload a local directory and build it. Empty turns it on when S3 storage is saved under Instance admin and builds can reach its endpoint. false always turns it off. true needs a build context bucket and access keys.
R2_BUILD_CONTEXT_BUCKETPrivate bucket for those uploads. Build pods must be able to reach it.
LOCAL_STORE_ENDPOINTThe store on this server. The chart sets these when objectStorage.local is on. It is the fallback for backups and uploads, and any of the settings above win.
LOCAL_STORE_BACKUP_BUCKET
LOCAL_STORE_UPLOADS_BUCKET
LOCAL_STORE_REGION
LOCAL_STORE_ACCESS_KEY_ID
LOCAL_STORE_SECRET_ACCESS_KEY
TEMPLATE_REGISTRY_URLhttps://assets.orchard.my/registryCommunity template registry. The server pulls the catalogue from here on boot and every six hours and lists those templates alongside the built-in ones. Unset means the public registry below; set it empty on air-gapped instances.
EMAIL_AVATAR_LOOKUPImport a profile picture from Gravatar/Libravatar when a user has one set up for their email. The server does the lookup and copies the image into R2, so users’ browsers never contact the avatar service and no email hash leaks to it from a viewer’s IP. Set to false to never look anything up; requires R2.
EMAIL_AVATAR_PROVIDERSComma-separated, tried in order. Defaults to “libravatar,gravatar”.
SIGN_IN_LOCATION_LOOKUPShow the approximate location of each sign-in in the session list and in sign-in alerts. Set to true to turn it on; it sends the public IP address of every sign-in to ipwho.is. Off by default, and nothing is sent while it is off.
VariableExampleDescription
BUILD_MODElocallocal (docker daemon) | kubernetes (in-cluster buildkit jobs)
ALLOW_LOCAL_BUILD_IN_PRODUCTIONLocal builds clone and build untrusted repositories inside the server process, so they are refused when NODE_ENV=production. Set to true to allow them anyway.
DOCKER_REGISTRY_PUSHBoth are required to build images. With either unset, builds fail and say so.
DOCKER_REGISTRY_PULL
REGISTRY_PROJECTorchard
REGISTRY_IMAGE_POLICYWhat the cluster does with a pod naming another project’s image: enforce, warn or off. Unset enforces unless an existing image would be refused, in which case it warns.
REGISTRY_PULL_SECRET_NAME
REGISTRY_HTTP_HOSTSComma-separated registry hosts reached over plain HTTP. Anything not listed is HTTPS.
HARBOR_USERNAMELogin for the registry above (Harbor, zot or any OCI registry). It needs pull, push and delete: Orchard keeps the ten newest builds of each app and deletes older ones, so without delete the registry fills up. On Harbor, give the robot Delete Artifact and Delete Tag.
HARBOR_PASSWORD
HARBOR_API_URLHarbor API base for vulnerability scan results (the app Security tab). Defaults to https://$DOCKER_REGISTRY_PULL; set it to reach Harbor’s core service in-cluster.
HARBOR_API_TIMEOUT_MS
VariableExampleDescription
IMAGE_SCANNERWhich scanner fills the app Security tab: off | harbor | trivy. Off by default; a superadmin picks one in Admin -> Instance -> Image scanning. Setting this pins the choice and locks the admin control. harbor reads Harbor’s own scan results (needs HARBOR_USERNAME/HARBOR_PASSWORD) and only covers images Orchard builds. trivy is the Orchard scanner and also covers external images.
TRIVY_SERVER_URLThe Orchard scanner. The chart sets all of these when trivy.enabled is true. Trivy server the scan jobs ask for vulnerability matches.
TRIVY_SERVER_TOKENShared token between the scan jobs and the Trivy server, if it requires one.
TRIVY_SCAN_NAMESPACEorchard-scansNamespace the one-off scan jobs run in. It must exist; the chart creates it.
TRIVY_IMAGEghcr.io/aquasecurity/trivy:0.76.2@sha256:8f6bb947dbc528902e11f2f5be52f7b519f6a39d5d148f41166f2040499768fbImage the scan jobs run. Must be an Alpine-based Trivy image (it uses sh and wget).
TRIVY_MAX_CONCURRENT_SCANS3Scans allowed at once across the instance, and how long one may run.
TRIVY_SCAN_TIMEOUT_SECONDS900
TRIVY_MAX_SCANS_PER_ORGOf those, how many one organization may hold at once (default 1). Also under Admin -> Limits; setting it here pins it there.
ORCHARD_INTERNAL_URLHow scan jobs reach this server from inside the cluster to hand back results, e.g. http://server.orchard.svc.cluster.local:3001.
REGISTRY_CREDENTIALS_ALLOW_INTERNALProject registry credentials are verified against the registry before they are stored; registries on private or cluster-internal addresses are refused unless this is true.
VariableExampleDescription
EXEC_DETACH_GRACE_MSHow long a shell survives a dropped browser before it is reaped.
EXEC_SNAPSHOT_SCROLLBACKScrollback lines kept per shell for the reattach snapshot. Each session holds a headless terminal; at the 200-session cap a busy 200x50 screen with 500 lines of scrollback is roughly 1-3 MB, so lower this on small instances.
BUILDER_NAMESPACEorchard-builders
BUILDER_SOURCE_CPU_LIMIT2
BUILDER_RUNTIME_CLASSRuntimeClass build pods run under, such as kata. Empty uses the cluster default.
BUILDER_MEMORY_REQUESTMemory the scheduler reserves for each build pod’s BuildKit container (default 2Gi), and the most it may use (default 32Gi). The installer lowers the request on a small box so a build can schedule at all.
BUILDER_MEMORY_LIMIT
BUILD_PLATFORMArchitecture user images are built for: linux/amd64 (default) or linux/arm64. Build pods run on nodes of that architecture. When set, apps built by Orchard are also pinned to it, so a mixed-architecture cluster stays schedulable.
MAX_CONCURRENT_BUILDS
MAX_CONCURRENT_BUILDS_PER_ORGMost builds one organization may run at once in a pool (default: half the pool, and no limit when the pool has 4 slots or fewer). 0 = no per-org limit. Queued builds are started fairest-first: the organization with the fewest running builds goes first. Also under Admin -> Limits; setting it here pins it there.
DATABASE_DEFAULT_MEMORY_MBMemory request in MB for a database with no size of its own (default 1024, floor 512). The installer lowers it on a box with about 8G of RAM or less.
DEFAULT_APP_MEMORY_MBMemory limit in MB for an app with no size of its own and no organization default (default 128). The installer sets it by RAM on a fresh install.
BUILD_NO_PROXY_EXTRA
DEPOT_TOKENOptional Depot remote builders
DEPOT_PROJECT_ID
MAX_CONCURRENT_DEPOT_BUILDSMost Depot builds that run at once (default 4).
FC_BUILDER_ENABLEDExperimental fast builder: per-project Firecracker microVMs run by the fc-builder service. Builds only route there when this is true AND the PostHog flag firecracker-builder (or a per-deployment override) picks the project; anything else uses the standard builder.
FC_BUILDER_HOSTSComma-separated fc-builder host URLs, e.g. http://fc-builder-0.fc-builder.orchard-fc-builders.svc.cluster.local:8080
FC_BUILDER_TOKENShared secret the server signs fc-builder API tokens with; must match the fc-builder pods.
MAX_CONCURRENT_FC_BUILDSQueue slots for fast builds (default 16), separate from MAX_CONCURRENT_BUILDS.
BUILDKIT_S3_CACHE_ENABLEDOptional buildkit cache (S3-compatible or local PVC)
BUILDKIT_S3_BUCKET
BUILDKIT_S3_ENDPOINT
BUILDKIT_S3_VIA_PROXYauto (default), true or false. Routes the S3 build cache through the r2-proxy with a per-tenant key. auto does so when the proxy is enabled and the cache bucket is the instance backup bucket. true needs the bucket in r2Proxy.allowedBuckets.
BUILDKIT_S3_ACCESS_KEY_ID
BUILDKIT_S3_SECRET_ACCESS_KEY
BUILDKIT_S3_SHARED_KEYtrue lets builds use BUILDKIT_S3_ACCESS_KEY_ID when the r2-proxy does not carry the cache. Any build can read that key and reach every project’s cache, so only set it on a single-tenant instance. Without it the S3 cache is off unless it goes through the r2-proxy.
BUILDKIT_LOCAL_CACHE_ENABLED
BUILDKIT_LOCAL_CACHE_PVC
BUILDKIT_CACHE_MAX_GIBDefault size budget in GiB for the local build cache. Over it, the least recently used environments are evicted before a build. Empty means no budget. Admin -> Build cache overrides it.
BUILDKIT_CACHE_MAX_AGE_DAYSDefault days before an unused cache is evicted (default 14). Admin -> Build cache overrides it.

Email (SMTP; email features skip silently without it)

Section titled “Email (SMTP; email features skip silently without it)”
VariableExampleDescription
SMTP_HOST
SMTP_PORT587
SMTP_USER
SMTP_PASS
SMTP_SECURE
SMTP_FROM
SMTP_FROM_NAMEOrchard
EMAIL_ASSET_BASE_URL
VariableExampleDescription
SSO_ENCRYPTION_KEY
SSO_ALLOWED_EMAIL_DOMAINS
SSO_DEFAULT_ROLE
SSO_REQUIRE_EMAIL_VERIFIED
SSO_ALLOW_INTERNAL_IDPtrue lets an identity provider URL resolve to a private or cluster-internal address.
SCIM_BASE_URL
ORG_IDENTITY_CAPMost people an organization’s IdP or SCIM may provision into it (default 20000).

Observability (all optional, off when unset)

Section titled “Observability (all optional, off when unset)”
VariableExampleDescription
POSTHOG_API_KEY
POSTHOG_HOST
ORCHARD_TELEMETRYAnonymous usage reports to the Orchard team. Separate from POSTHOG_API_KEY, which is your own analytics. Off until a superadmin opts in, either during setup or from the prompt they get afterwards (Admin -> Configuration to change it later). ‘false’ turns it off and locks the switch, ‘true’ turns it on without asking. Leave unset to let a superadmin decide.
DD_TRACE_ENABLEDfalse
DD_AGENT_HOST
VICTORIAMETRICS_URL
VICTORIALOGS_URLVictoriaLogs holding app logs and ingress access logs (the chart’s logs stack). Empty uses http://victorialogs.orchard-metrics.svc.cluster.local:9428.
INGRESS_METRICSWhich ingress controller’s metrics describe app HTTP traffic (requests, status classes, latency, per-route stats, HTTP alerts). Empty detects it per app from the metrics store, falling back to K8S_INGRESS_CLASS. Adapters live in apps/server/src/metrics/ingress/ (haproxy, traefik).
INGRESS_METRICS_TRAEFIK_JOBOnly series from this scrape job (and namespaces, comma-separated) are trusted for ingress charts. Defaults: jobs traefik / haproxy-ingress, any namespace. The chart sets the namespaces from metrics.ingress.*.namespaces.
INGRESS_METRICS_TRAEFIK_NAMESPACE
INGRESS_METRICS_HAPROXY_JOB
INGRESS_METRICS_HAPROXY_NAMESPACE
VariableExampleDescription
COOKIE_DOMAIN
SESSION_COOKIE_SECUREfalse
TRUST_PROXY1Proxy hops to trust when finding the client IP (1 = one ingress, 2 = LB + ingress), or a comma-separated CIDR list. Unset trusts no forwarded header.
TRUSTED_PROXY_RANGESExtra proxy CIDRs trusted at any position, comma-separated.
TRUST_CLOUDFLAREfalse stops skipping Cloudflare’s published edge ranges.
CLIENT_IP_HEADERCloudflare Tunnel: header with the real client IP (cf-connecting-ip) and the CIDRs of the hop allowed to supply it. Both required; otherwise the header is ignored.
CLIENT_IP_HEADER_FROM
AI_CHAT_API_URL
AI_CHAT_API_KEY
AI_CHAT_MODEL
BACKUP_PROXY_ENABLED
BACKUP_PROXY_ENDPOINT
DEFAULT_DB_BACKUP_WINDOWDefault nightly base backups are spread across this UTC hour range (inclusive) so every database doesn’t hit storage in the same minute. Default 1-5.
DEFAULT_DB_BACKUP_CRONPins one cron for every default schedule instead of spreading them.
CNPG_BARMAN_PLUGINon: new databases archive with the Barman Cloud plugin (plugin-barman-cloud in the CNPG operator namespace) instead of CNPG’s in-tree barmanObjectStore, which CloudNativePG 1.31 removes. Existing databases keep their method until the plugin migration in Instance admin moves them. The installer sets it on new hosts.
POSTGRES_IMAGE_CATALOG_URLTenant Postgres images follow CNPG’s published catalog (digest-pinned, one per major) so security patches land without an Orchard release. Point this at a mirror for self-hosted or air-gapped installs, or set it to off to use the images compiled into this release.
POSTGRES_IMAGE_17Pins one major to an exact image, e.g. POSTGRES_IMAGE_17=registry/postgresql:17.11
POSTGRES_AUTO_UPDATEDatabases in organizations whose admins turned on automatic Postgres updates move to the catalog’s image a few at a time inside this UTC hour range (default 8-11). Every other database only moves when someone updates it. POSTGRES_AUTO_UPDATE=false stops it for the whole instance, whatever orgs chose.
POSTGRES_IMAGE_ROLLOUT_WINDOW
POSTGRES_IMAGE_ROLLOUT_BATCH
INSTANCE_RESOURCE_LIMITSResource limits for the whole instance: on or off. Set, it wins and locks the setting in Instance admin, and Orchard stores the value, so unsetting it later keeps that value and unlocks the setting. Unset, the stored choice applies, and with no stored choice limits stay on. A change reaches a running app or database at its next restart or redeploy, or when the cluster replaces its pod.
INSTANCE_RESOURCE_LIMITS_CHOICEThe choice from the installer: on or off. Orchard stores it once, as if someone chose it in Instance admin, and the setting stays editable. A different value stores again.
TENANT_QUOTA_FLOOR_PODSResourceQuota floor for tenant namespaces whose org or project has no cap.
TENANT_QUOTA_FLOOR_SERVICES
TENANT_QUOTA_FLOOR_PVCS
TENANT_QUOTA_FLOOR_STORAGE_BYTES
TENANT_QUOTA_FLOOR_LOADBALANCERSAlways applied, whatever the resource limits mode: the most LoadBalancer (default 20) and NodePort (default 10) Services a tenant namespace can hold, and the ephemeral-storage limit in GiB that every container gets by default (default 20, 0 turns the ephemeral-storage quota and default off). Public ports and public databases use these Service types, so 0 stops them. All three are also under Admin -> Limits; setting one here pins it there.
TENANT_QUOTA_FLOOR_NODEPORTS
TENANT_EPHEMERAL_STORAGE_LIMIT_GIB
NEW_ORG_CPUSeed for the CPU and memory caps of NEW organizations. New organizations are uncapped unless this is set or a superadmin sets the instance default for new organizations in the admin panel (which wins over this seed). The value is written into the org’s caps when it is created; existing organizations are untouched, and an administrator can change any organization’s caps afterwards. 0 or “unlimited” means no cap. On an instance with open sign-up, set limits.
NEW_ORG_MEMORY
MAX_PROJECTS_PER_ORGA hard ceiling on projects, extra environments (each is a namespace) and deployments for EVERY organization, whatever its own limit. Unset or 0 means no ceiling; per-organization limits are set in the admin panel. An organization already above a limit keeps everything it has and just cannot create more. Also under Admin -> Limits; setting one here pins it there.
MAX_ENVIRONMENTS_PER_ORG
MAX_DEPLOYMENTS_PER_ORG
TENANT_SECRETS_CLUSTER_ROLESet by the chart: the ClusterRole the server binds into each tenant namespace for secrets and configmaps. Unset, the server mints a per-namespace Role.
VariableExampleDescription
CLOUDFLARE_API_TOKENA token-managed tunnel keeps its routing table in Cloudflare, not in the cluster, so the instance cannot normally see which hostnames reach it. With an API token it can, and Instance admin -> Networking can add a missing route and its DNS record. The token needs Account / Cloudflare Tunnel / Edit, plus Zone / DNS / Edit to create records. Without the zone ID the tunnel route is added but the DNS record is left to you.
CLOUDFLARE_ACCOUNT_ID
CLOUDFLARE_TUNNEL_ID
CLOUDFLARE_ZONE_ID
VariableExampleDescription
MCP_BASE_URLThe public origin of the MCP server, used as the OAuth issuer and resource identifier. The chart derives it from mcp.ingress.host.
MCP_ENABLEDWhether this instance accepts MCP connections at all. Defaults on, and is a toggle in the admin panel (Admin -> Configuration). This env var OVERRIDES that toggle when set: ‘false’ refuses every MCP request and locks the switch. The chart sets it to ‘false’ when mcp.enabled is off, because nothing is serving MCP then.
SSO_ENFORCEDPins the “require single sign-on for everyone” switch in the admin panel. ‘true’ refuses email codes, passkeys and the superadmin password for every account that is not a superadmin; only the configured identity providers sign people in. Leave blank to let the switch decide.
IDP_AUTO_CREATE_ORGSPins “identity providers may create organizations” in the admin SSO page. ‘true’ lets a login whose IdP groups match an auto-create rule on an instance provider create that organization once; ‘false’ keeps it off. Off unless an instance admin turns it on, and the group rules themselves are managed only by instance admins. Leave blank to let the switch decide.
CUSTOM_DOMAIN_VERIFICATIONPins the “require proof of domain ownership” switch in the admin panel. ‘true’ makes people add a TXT record before they can add a custom domain, ‘false’ turns it off. Leave blank to let the switch decide; with nothing stored the switch starts on when SIGNUP_MODE is open and off otherwise. Domains a project already serves are never asked for proof again.
PUBLIC_IP_SHARINGPins “allow organizations to share a public IP” in the admin networking page. Off by default: an organization can’t set a public IP that another organization or another tenant’s load balancer already holds, and its load balancers only share that IP with its own namespaces. ‘true’ lets organizations put their load balancers on the same address. The instance’s default public IP is always shared. Leave blank to let the switch decide.
MAX_CUSTOM_DOMAINS_PER_ORGMost distinct custom (non-generated) hostnames one organization may hold (default 250, 0 = unlimited) and most it may add per hour (default 30, 0 = unlimited). Repeated failed TXT proofs pause an organization’s new domains for 1 minute after the fifth failure, doubling up to a day. Both are also under Admin -> Limits; setting one here pins it there.
MAX_CUSTOM_DOMAIN_CREATES_PER_HOUR
MCP_SERVICE_TOKENShared with the MCP process. It authenticates to this API as a service and passes the consenting user’s identity in headers, so a mismatch surfaces as every tool call failing rather than as anything failing to start.
VariableExampleDescription
SANDBOX_NAMESPACEorchard-sandboxesNamespace the Kubernetes runner creates machines in.
SANDBOX_IMAGEghcr.io/hackclub/orchard/sandbox:latestImage new Kubernetes machines start from. The default ships every agent and the machine daemon; on other images the bootstrap installs what is missing.
SANDBOX_RUNTIME_CLASSAgent new sessions use when nobody picks one: opencode, acp:claude, acp:opencode, acp:fx, acp:codex SANDBOX_DEFAULT_AGENT=opencode off: talk to machines over exec only, never the in-machine daemon SANDBOX_DAEMON= off: do not keep spare worktrees for instant sessions SANDBOX_WARM_POOL= RuntimeClass for Kubernetes machines, usually kata. Empty runs them on the default runtime with a filesystem-mode home volume, a reduced capability set, RuntimeDefault seccomp and a baseline Pod Security namespace.
SANDBOX_HOME_MODEHome volume mode: block, filesystem, or auto (block when a RuntimeClass is set).
SANDBOX_STORAGE_CLASSStorageClass for home volumes. Empty uses the cluster default.
SANDBOX_DISK_SIZESize and limits for new Kubernetes machines. Defaults 10Gi, 2 CPUs, 4Gi.
SANDBOX_CPU_LIMIT
SANDBOX_MEMORY_LIMIT
SANDBOX_TUNNEL_MODE‘portforward’ reaches machines through the API server instead of pod IPs, for a server running outside the cluster.
SANDBOX_MAX_PER_USERDefault number of machines each person may own. Admins override it per person under Admin -> Greenhouse; superadmins are uncapped. Defaults to 1.
SANDBOX_IDLE_TIMEOUT_MINUTESStop running machines with no terminal or SSH activity and no busy agent for this many minutes. Defaults to 60; 0 never stops them.
SANDBOX_MAX_LIFETIME_HOURSStop machines this many hours after their last start, active or not. Defaults to 168; 0 never stops them.
SANDBOX_MCP_URLThe MCP endpoint configured into each machine’s agent, authenticated as the machine’s host. The chart derives it from mcp.ingress.host. Vercel machines only use an https URL.
SANDBOX_RUNNER_KUBERNETES_ENABLEDRunners. Each of the following overrides and locks the matching field under Admin -> Configuration -> Sandbox runners. Kubernetes defaults on, Vercel off.
SANDBOX_RUNNER_VERCEL_ENABLED
SANDBOX_DEFAULT_RUNNERkubernetes or vercel. Unset picks the first available runner.
SANDBOX_VERCEL_TOKENVercel access token, team id and project id that Vercel machines are created under. Vercel machines also require SECRETS_ENCRYPTION_KEY.
SANDBOX_VERCEL_TEAM_ID
SANDBOX_VERCEL_PROJECT_ID
SANDBOX_VERCEL_IMAGEImage, vCPUs (1 to 8) and provider timeout in minutes (1 to 1440) for Vercel machines. Defaults vercel/sandbox/universal, 2 and 60.
SANDBOX_VERCEL_VCPUS
SANDBOX_VERCEL_TIMEOUT_MINUTES
SANDBOX_VERCEL_DRIVE_GIBSize in GiB (1 to 16384) of the Vercel drive that holds each machine’s home. Defaults to 50. 0 turns drives off and keeps homes in snapshots only. A drive keeps the size it was created with.
SANDBOX_BRIDGE_BINARY_URLhttps URL of the linux/amd64 orchard CLI tarball Vercel machines run as their SSH bridge. Unset uses the release that matches this server.
SANDBOX_BRIDGE_BINARY_SHA256SHA-256 of that tarball, required when SANDBOX_BRIDGE_BINARY_URL is set. Machines refuse a bridge download that does not match. Unset with the default URL uses the checksum from that release’s checksums.txt.
SANDBOX_PREVIEW_DOMAINBare domain for Kubernetes previews (<port>-<machine>.<domain>). Needs wildcard DNS and TLS routed to the server, and must not be or share the Orchard cookie domain or hostnames. Unset turns Kubernetes previews off.
SLACK_SIGNING_SECRETSlack app for /greenhouse and mentions (Admin -> Configuration -> Slack app). The bot token starts with xoxb-. The app id, when set, ignores other apps.
SLACK_BOT_TOKEN
SLACK_APP_ID
LINEAR_WEBHOOK_SECRETSigning secret of the Linear webhook that delivers /greenhouse comments.
VariableExampleDescription
TENANT_EGRESS_NAMESPACESNamespaces a tenant pod may reach. Empty means the ingress namespaces without Orchard’s own, so tenants can’t connect to the server or platform database.
TENANT_INGRESS_NAMESPACESNamespaces of the ingress controllers, comma separated. Empty means network,orchard.
TENANT_RUNTIME_CLASSRuntimeClass tenant pods run under, such as gvisor. Empty uses the cluster default.
TENANT_INGRESS_PORTSTCP ports a tenant pod may reach on the ingress namespaces. Empty means 80,443,8000,8080,8443, the serving ports of HAProxy, Traefik and nginx. The controller’s stats and pprof ports are left out because they list every tenant’s backend.
TENANT_EGRESS_BLOCK_PORTSOutbound TCP ports tenant pods may not use on the public internet, as a comma-separated list. Empty blocks nothing.
TENANT_DENY_ENTITIESCilium entities tenant pods may not reach, even if an allow rule would match. Empty means host,remote-node,kube-apiserver. Use “none” to skip the policy. Set it to “none” if the ingress controller runs with hostNetwork and tenant apps call their own public hostname.
PLATFORM_EXTRA_DENY_CIDRSExtra IPv4 addresses or CIDRs (comma separated) added to the egress deny list of tenant, sandbox and builder policies, on top of the node addresses, apiserver endpoints and pod CIDRs the server discovers. Use it for a public load balancer or a non-RFC1918 service CIDR.
DB_IMPORT_ALLOW_INTERNALfalseLet database imports connect to private addresses. Otherwise the source host is resolved once, every address must be public, and both the check and the CNPG import connect to that pinned address.
BACKUP_ALLOW_INTERNAL_ENDPOINTfalseLet organizations point backups at a private storage endpoint. Otherwise the server’s own S3 calls refuse non-public addresses at connect time. Tenant database pods (CNPG barman) reach the endpoint under the tenant NetworkPolicy: any public address is allowed, so restrict egress at the node firewall if you need an allowlist.
PSQL_SESSION_TTL_SECONDS3600SQL shell (orchard db psql, dashboard database console): an ephemeral client pod in the tenant namespace under TENANT_RUNTIME_CLASS. Lifetime in seconds (60-14400) and open sessions per database.
PSQL_SESSIONS_PER_DATABASE3
JOB_RUNTIME_IMAGE_BASHdebian:12.15-slim@sha256:734a72b3d6142a71993b4bc580ca01d8ca687f77a2c422d96a961d3376b179bcImage that bash script steps in jobs run in.
JOB_RUNTIME_IMAGE_PYTHONpython:3.12.16-slim@sha256:5e2bdb1b0d542d5039cffb8181c65930093949194a65c365dfb1b0fe13a4fa5bImage that python script steps in jobs run in.
JOB_RUNTIME_IMAGE_NODEnode:22.23.5-slim@sha256:e9f565d32859f0cbfb52125eafe8be39390f24dac302dc3cdf566e8ba3ab21eeImage that node script steps in jobs run in.
DOCTOR_PROBE_IMAGEdocker.io/library/debian:12.15-slim@sha256:734a72b3d6142a71993b4bc580ca01d8ca687f77a2c422d96a961d3376b179bcorchard doctor isolation self-test (POST /admin/doctor/selftest, superadmin only). It creates two temporary tenant namespaces and a probe pod, then deletes them. The probe needs bash and the listener needs busybox httpd; point these at a mirror on an air-gapped cluster.
DOCTOR_LISTENER_IMAGEdocker.io/library/busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
DOCTOR_EXTERNAL_TARGET1.1.1.1:443host:port the probe must reach as a positive control. Without it a broken probe would report every target blocked.
DOCTOR_PLATFORM_NAMESPACESNamespaces whose services the probe must not reach. Empty means the Orchard, r2-proxy and metrics namespaces.
DOCTOR_INGRESS_DEBUG_PORTSExtra ingress controller ports to probe besides 1024, 1042 and 6060 and the ports the controller pods declare.