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.
Core (required)
Section titled “Core (required)”| Variable | Example | Description |
|---|---|---|
DATABASE_URL | postgresql://orchard:orchard@localhost:5432/orchard | docker compose -f docker-compose.dev.yml up -d gives you this database |
JWT_SECRET | change-me-to-a-long-random-string | At least 32 characters, and not this example: the server refuses to boot otherwise. It signs every session, cookie and sign-in code. |
Core (recommended)
Section titled “Core (recommended)”| Variable | Example | Description |
|---|---|---|
PORT | 3001 | |
FRONTEND_URL | http://localhost:4000 | The 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_ORIGINS | Extra 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_KEY | Encrypts stored secret env vars; required to save secrets. Falls back to SSO_ENCRYPTION_KEY. | |
REDIS_URL | redis://localhost:6379 | Cross-replica SSE event bus + cache. Optional: single-instance mode without it. |
Signups
Section titled “Signups”| Variable | Example | Description |
|---|---|---|
SIGNUP_MODE | open | open | invite_only | closed |
Node scheduling
Section titled “Node scheduling”| Variable | Example | Description |
|---|---|---|
USERSPACE_NODE_SCHEDULING | Node 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)”| Variable | Example | Description |
|---|---|---|
KUBECONFIG_PATH | Defaults to ~/.kube/config. Accepts either a path or the kubeconfig itself base64 encoded. The server boots fine without a cluster. | |
CILIUM_ENABLED | Cilium-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_LOGIN | Offer “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_REPLICAS | Most 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_IMAGE | Image of the Tailscale proxy pod. Defaults to a ghcr.io/tailscale/tailscale release pinned by digest. | |
RESERVED_NAMESPACES_EXTRA | ||
CPU_REQUEST_RATIO | Fraction 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 |
Domains
Section titled “Domains”| Variable | Example | Description |
|---|---|---|
APP_DOMAIN | Wildcard 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_STYLE | opaque | Style 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_CNAME | CNAME target users point their own domains at. Unset disables DNS validation for custom domains. | |
INSTALL_INGRESS_MODE | Set 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_PORT | The 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_PORT | The TLS half of the same. Both default to the standard ports. | |
BASE_DOMAIN | The 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_HOSTS | Comma-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_SUFFIXES | Comma-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_DOMAIN | Also 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_MODE | wildcard | per-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_KIND | ClusterIssuer | |
PUBLIC_DB_TLS_LEGACY_HOSTNAMES | false | |
PUBLIC_DEPLOYMENT_DOMAIN | Parent for publicly exposed deployment ports. | |
PUBLIC_EXPOSURE_IP | Fallback 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_EXPOSURE | Set 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_ORG | Most 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_BANDWIDTH | Caps 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_SIZE | Largest persistent volume a tenant may request. Defaults to 200Gi. Also under Admin -> Limits; setting it here pins it there. | |
PLATFORM_WILDCARD_DOMAINS | Comma-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)”| Variable | Example | Description |
|---|---|---|
AUTH_PROVIDER | hackclub | oidc | none. Defaults to hackclub when HACKCLUB_CLIENT_ID is set, none otherwise. | |
HACKCLUB_CLIENT_ID | hackclub preset | |
HACKCLUB_CLIENT_SECRET | ||
HACKCLUB_REDIRECT_URI | http://localhost:3001/apiv1/auth/callback | |
AUTH_OAUTH_CLIENT_ID | generic OIDC (any IdP: Keycloak, Authentik, Dex, Google, …) | |
AUTH_OAUTH_CLIENT_SECRET | ||
AUTH_OAUTH_REDIRECT_URI | ||
AUTH_OAUTH_ISSUER | discovery 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_ID | claim mapping; defaults sub / email / name | |
AUTH_OAUTH_CLAIM_EMAIL | ||
AUTH_OAUTH_CLAIM_NAME | ||
AUTH_OAUTH_TRUST_EMAIL | true 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_PKCE | PKCE: on when the discovery document lists S256; true or false overrides |
Auth: WebAuthn/passkeys
Section titled “Auth: WebAuthn/passkeys”| Variable | Example | Description |
|---|---|---|
WEBAUTHN_RP_ID | localhost | |
WEBAUTHN_RP_NAME | Orchard | |
WEBAUTHN_ORIGIN | http://localhost:4000 |
GitHub App (deploy-from-GitHub, webhooks)
Section titled “GitHub App (deploy-from-GitHub, webhooks)”| Variable | Example | Description |
|---|---|---|
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)”| Variable | Example | Description |
|---|---|---|
R2_ACCOUNT_ID | Set 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_URL | Empty serves uploads through the API, so the bucket can stay private. | |
R2_ENDPOINT | ||
R2_REGION | The signing region. Empty means auto, which R2 expects. | |
R2_PATH_STYLE | true sends requests to <endpoint>/<bucket>, false to <bucket>.<endpoint>. | |
LOCAL_DEPLOYS_ENABLED | Lets 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_BUCKET | Private bucket for those uploads. Build pods must be able to reach it. | |
LOCAL_STORE_ENDPOINT | The 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_URL | https://assets.orchard.my/registry | Community 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_LOOKUP | Import 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_PROVIDERS | Comma-separated, tried in order. Defaults to “libravatar,gravatar”. | |
SIGN_IN_LOCATION_LOOKUP | Show 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. |
Image builds
Section titled “Image builds”| Variable | Example | Description |
|---|---|---|
BUILD_MODE | local | local (docker daemon) | kubernetes (in-cluster buildkit jobs) |
ALLOW_LOCAL_BUILD_IN_PRODUCTION | Local 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_PUSH | Both are required to build images. With either unset, builds fail and say so. | |
DOCKER_REGISTRY_PULL | ||
REGISTRY_PROJECT | orchard | |
REGISTRY_IMAGE_POLICY | What 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_HOSTS | Comma-separated registry hosts reached over plain HTTP. Anything not listed is HTTPS. | |
HARBOR_USERNAME | Login 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_URL | Harbor 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 |
Image scanning
Section titled “Image scanning”| Variable | Example | Description |
|---|---|---|
IMAGE_SCANNER | Which 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_URL | The Orchard scanner. The chart sets all of these when trivy.enabled is true. Trivy server the scan jobs ask for vulnerability matches. | |
TRIVY_SERVER_TOKEN | Shared token between the scan jobs and the Trivy server, if it requires one. | |
TRIVY_SCAN_NAMESPACE | orchard-scans | Namespace the one-off scan jobs run in. It must exist; the chart creates it. |
TRIVY_IMAGE | ghcr.io/aquasecurity/trivy:0.76.2@sha256:8f6bb947dbc528902e11f2f5be52f7b519f6a39d5d148f41166f2040499768fb | Image the scan jobs run. Must be an Alpine-based Trivy image (it uses sh and wget). |
TRIVY_MAX_CONCURRENT_SCANS | 3 | Scans allowed at once across the instance, and how long one may run. |
TRIVY_SCAN_TIMEOUT_SECONDS | 900 | |
TRIVY_MAX_SCANS_PER_ORG | Of those, how many one organization may hold at once (default 1). Also under Admin -> Limits; setting it here pins it there. | |
ORCHARD_INTERNAL_URL | How 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_INTERNAL | Project registry credentials are verified against the registry before they are stored; registries on private or cluster-internal addresses are refused unless this is true. |
Pod shell sessions
Section titled “Pod shell sessions”| Variable | Example | Description |
|---|---|---|
EXEC_DETACH_GRACE_MS | How long a shell survives a dropped browser before it is reaped. | |
EXEC_SNAPSHOT_SCROLLBACK | Scrollback 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_NAMESPACE | orchard-builders | |
BUILDER_SOURCE_CPU_LIMIT | 2 | |
BUILDER_RUNTIME_CLASS | RuntimeClass build pods run under, such as kata. Empty uses the cluster default. | |
BUILDER_MEMORY_REQUEST | Memory 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_PLATFORM | Architecture 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_ORG | Most 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_MB | Memory 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_MB | Memory 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_TOKEN | Optional Depot remote builders | |
DEPOT_PROJECT_ID | ||
MAX_CONCURRENT_DEPOT_BUILDS | Most Depot builds that run at once (default 4). | |
FC_BUILDER_ENABLED | Experimental 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_HOSTS | Comma-separated fc-builder host URLs, e.g. http://fc-builder-0.fc-builder.orchard-fc-builders.svc.cluster.local:8080 | |
FC_BUILDER_TOKEN | Shared secret the server signs fc-builder API tokens with; must match the fc-builder pods. | |
MAX_CONCURRENT_FC_BUILDS | Queue slots for fast builds (default 16), separate from MAX_CONCURRENT_BUILDS. | |
BUILDKIT_S3_CACHE_ENABLED | Optional buildkit cache (S3-compatible or local PVC) | |
BUILDKIT_S3_BUCKET | ||
BUILDKIT_S3_ENDPOINT | ||
BUILDKIT_S3_VIA_PROXY | auto (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_KEY | true 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_GIB | Default 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_DAYS | Default 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)”| Variable | Example | Description |
|---|---|---|
SMTP_HOST | ||
SMTP_PORT | 587 | |
SMTP_USER | ||
SMTP_PASS | ||
SMTP_SECURE | ||
SMTP_FROM | ||
SMTP_FROM_NAME | Orchard | |
EMAIL_ASSET_BASE_URL |
Enterprise SSO / SCIM (optional)
Section titled “Enterprise SSO / SCIM (optional)”| Variable | Example | Description |
|---|---|---|
SSO_ENCRYPTION_KEY | ||
SSO_ALLOWED_EMAIL_DOMAINS | ||
SSO_DEFAULT_ROLE | ||
SSO_REQUIRE_EMAIL_VERIFIED | ||
SSO_ALLOW_INTERNAL_IDP | true lets an identity provider URL resolve to a private or cluster-internal address. | |
SCIM_BASE_URL | ||
ORG_IDENTITY_CAP | Most 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)”| Variable | Example | Description |
|---|---|---|
POSTHOG_API_KEY | ||
POSTHOG_HOST | ||
ORCHARD_TELEMETRY | Anonymous 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_ENABLED | false | |
DD_AGENT_HOST | ||
VICTORIAMETRICS_URL | ||
VICTORIALOGS_URL | VictoriaLogs holding app logs and ingress access logs (the chart’s logs stack). Empty uses http://victorialogs.orchard-metrics.svc.cluster.local:9428. | |
INGRESS_METRICS | Which 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_JOB | Only 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 |
Misc (optional)
Section titled “Misc (optional)”| Variable | Example | Description |
|---|---|---|
COOKIE_DOMAIN | ||
SESSION_COOKIE_SECURE | false | |
TRUST_PROXY | 1 | Proxy 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_RANGES | Extra proxy CIDRs trusted at any position, comma-separated. | |
TRUST_CLOUDFLARE | false stops skipping Cloudflare’s published edge ranges. | |
CLIENT_IP_HEADER | Cloudflare 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_WINDOW | Default 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_CRON | Pins one cron for every default schedule instead of spreading them. | |
CNPG_BARMAN_PLUGIN | on: 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_URL | Tenant 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_17 | Pins one major to an exact image, e.g. POSTGRES_IMAGE_17=registry/postgresql:17.11 | |
POSTGRES_AUTO_UPDATE | Databases 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_LIMITS | Resource 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_CHOICE | The 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_PODS | ResourceQuota 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_LOADBALANCERS | Always 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_CPU | Seed 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_ORG | A 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_ROLE | Set by the chart: the ClusterRole the server binds into each tenant namespace for secrets and configmaps. Unset, the server mints a per-namespace Role. |
Cloudflare Tunnel (optional)
Section titled “Cloudflare Tunnel (optional)”| Variable | Example | Description |
|---|---|---|
CLOUDFLARE_API_TOKEN | A 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 |
| Variable | Example | Description |
|---|---|---|
MCP_BASE_URL | The public origin of the MCP server, used as the OAuth issuer and resource identifier. The chart derives it from mcp.ingress.host. | |
MCP_ENABLED | Whether 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_ENFORCED | Pins 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_ORGS | Pins “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_VERIFICATION | Pins 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_SHARING | Pins “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_ORG | Most 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_TOKEN | Shared 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. |
Greenhouse (AI dev machines)
Section titled “Greenhouse (AI dev machines)”| Variable | Example | Description |
|---|---|---|
SANDBOX_NAMESPACE | orchard-sandboxes | Namespace the Kubernetes runner creates machines in. |
SANDBOX_IMAGE | ghcr.io/hackclub/orchard/sandbox:latest | Image 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_CLASS | Agent 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_MODE | Home volume mode: block, filesystem, or auto (block when a RuntimeClass is set). | |
SANDBOX_STORAGE_CLASS | StorageClass for home volumes. Empty uses the cluster default. | |
SANDBOX_DISK_SIZE | Size 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_USER | Default number of machines each person may own. Admins override it per person under Admin -> Greenhouse; superadmins are uncapped. Defaults to 1. | |
SANDBOX_IDLE_TIMEOUT_MINUTES | Stop 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_HOURS | Stop machines this many hours after their last start, active or not. Defaults to 168; 0 never stops them. | |
SANDBOX_MCP_URL | The 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_ENABLED | Runners. 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_RUNNER | kubernetes or vercel. Unset picks the first available runner. | |
SANDBOX_VERCEL_TOKEN | Vercel 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_IMAGE | Image, 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_GIB | Size 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_URL | https 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_SHA256 | SHA-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_DOMAIN | Bare 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_SECRET | Slack 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_SECRET | Signing secret of the Linear webhook that delivers /greenhouse comments. |
Background workers
Section titled “Background workers”| Variable | Example | Description |
|---|---|---|
TENANT_EGRESS_NAMESPACES | Namespaces 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_NAMESPACES | Namespaces of the ingress controllers, comma separated. Empty means network,orchard. | |
TENANT_RUNTIME_CLASS | RuntimeClass tenant pods run under, such as gvisor. Empty uses the cluster default. | |
TENANT_INGRESS_PORTS | TCP 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_PORTS | Outbound TCP ports tenant pods may not use on the public internet, as a comma-separated list. Empty blocks nothing. | |
TENANT_DENY_ENTITIES | Cilium 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_CIDRS | Extra 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_INTERNAL | false | Let 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_ENDPOINT | false | Let 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_SECONDS | 3600 | SQL 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_DATABASE | 3 | |
JOB_RUNTIME_IMAGE_BASH | debian:12.15-slim@sha256:734a72b3d6142a71993b4bc580ca01d8ca687f77a2c422d96a961d3376b179bc | Image that bash script steps in jobs run in. |
JOB_RUNTIME_IMAGE_PYTHON | python:3.12.16-slim@sha256:5e2bdb1b0d542d5039cffb8181c65930093949194a65c365dfb1b0fe13a4fa5b | Image that python script steps in jobs run in. |
JOB_RUNTIME_IMAGE_NODE | node:22.23.5-slim@sha256:e9f565d32859f0cbfb52125eafe8be39390f24dac302dc3cdf566e8ba3ab21ee | Image that node script steps in jobs run in. |
DOCTOR_PROBE_IMAGE | docker.io/library/debian:12.15-slim@sha256:734a72b3d6142a71993b4bc580ca01d8ca687f77a2c422d96a961d3376b179bc | orchard 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_IMAGE | docker.io/library/busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4 | |
DOCTOR_EXTERNAL_TARGET | 1.1.1.1:443 | host:port the probe must reach as a positive control. Without it a broken probe would report every target blocked. |
DOCTOR_PLATFORM_NAMESPACES | Namespaces whose services the probe must not reach. Empty means the Orchard, r2-proxy and metrics namespaces. | |
DOCTOR_INGRESS_DEBUG_PORTS | Extra ingress controller ports to probe besides 1024, 1042 and 6060 and the ports the controller pods declare. |