Skip to content
quest'n'click

ReferenceReferenceFor authors, admins, contributorsApplies from 4.5.0

Environment variables

Cette page en françaisThis page on the GitHub wiki

Every environment variable quest-n-click reads, and the ones Clever Cloud and its add-ons give the hosted Studio. Each has its own section: link to it as reference.environment-variables.md#studio-session-key (the name in lowercase, _ written -).

How to read this page

  • Origin says who sets the variable: you (the code reads it), the build, the platform (Clever Cloud, GitHub Actions, npm, the system), a Clever Cloud add-on, or a CI workflow. A variable that a command of quest-n-click sets itself says so: you do not set it.
  • Secret: read once when the Studio Server starts, then removed from its environment, so no child process inherits it; never written to a log. Each secret can also come from a file: STUDIO_SESSION_KEY_FILE=/run/secrets/session reads the key from that file, which must be readable by its owner only (mode 0600) on Linux and macOS. The file wins over the variable.
  • Read by links the files of the code that read it, at the documented version.
  • On Clever Cloud, set a variable with clever env set NAME value on the right app; clever env prints multi-line values in full, so filter its output before you share it.

Studio Server (hosted Studio)

What the studio-server app reads: on Clever Cloud, set them with clever env set on the studio app, never on the worker. Each secret can come from a file instead (<NAME>_FILE, mode 0600), and leaves the environment once read.

GIT_DIR

Not taken from your environment: the Studio Server builds the environment of its own git commands, sets GIT_DIR there to the game's repository, and clears it for git init. A GIT_DIR of yours never reaches them.

STUDIO_BACKUP_CRON

1 turns on the daily backup to the bucket that clevercloud/cron.json runs at 03:17 UTC (ops/studio/backup-cron.sh). Set it on the studio app only, never on the worker.

STUDIO_BACKUP_KEEP

How many backups the daily backup keeps in the bucket (--keep); 14 when unset.

STUDIO_CONFIG

The path of the configuration file, read when no --config <file> is given. It wins over STUDIO_CONFIG_JSON.

STUDIO_CONFIG_JSON

The whole configuration as JSON on one line, for a platform that gives no file (Clever Cloud). It holds no secret; the loader refuses an unknown key.

STUDIO_DATABASE_URL

The PostgreSQL connection URI (store.kind: postgres). On Clever Cloud, leave it unset: the linked add-on's POSTGRESQL_ADDON_URI is read instead. For a restore drill, point it at the drill's empty database, never at production.

  • Origin: you set it; the code reads it.
  • Secret: yes: read once at start, then removed from the environment; never logged.
  • From a file: STUDIO_DATABASE_URL_FILE names a file to read it from instead (mode 0600 on Linux and macOS).
  • Read by: studio-server/src/server/config.ts.

STUDIO_GIT_KEY

Optional (4.2.3): the SSH deploy key of the game's Git repository (git.remote). Not needed for a public https remote.

  • Origin: you set it; the code reads it.
  • Secret: yes: read once at start, then removed from the environment; never logged.
  • From a file: STUDIO_GIT_KEY_FILE names a file to read it from instead (mode 0600 on Linux and macOS).
  • Read by: studio-server/src/server/config.ts.

STUDIO_METRICS_TOKEN

Optional (4.2.3): the bearer token of GET /metrics, 32 characters or more. Without it there is no /metrics route (404).

  • Origin: you set it; the code reads it.
  • Secret: yes: read once at start, then removed from the environment; never logged.
  • From a file: STUDIO_METRICS_TOKEN_FILE names a file to read it from instead (mode 0600 on Linux and macOS).
  • Read by: studio-server/src/server/config.ts.

STUDIO_OIDC_CLIENT_SECRET

The OpenID provider's secret for the studio client. Required when the configuration has oidc.

  • Origin: you set it; the code reads it.
  • Secret: yes: read once at start, then removed from the environment; never logged.
  • From a file: STUDIO_OIDC_CLIENT_SECRET_FILE names a file to read it from instead (mode 0600 on Linux and macOS).
  • Read by: studio-server/src/server/config.ts.

STUDIO_S3_KEY_ID

The S3 (Cellar) access key id for the bucket (blobs.kind: s3). On Clever Cloud the add-on's CELLAR_ADDON_KEY_ID is read when it is unset.

  • Origin: you set it; the code reads it.
  • Secret: yes: read once at start, then removed from the environment; never logged.
  • From a file: STUDIO_S3_KEY_ID_FILE names a file to read it from instead (mode 0600 on Linux and macOS).
  • Read by: studio-server/src/server/config.ts.

STUDIO_S3_KEY_SECRET

The S3 (Cellar) secret key for the bucket. On Clever Cloud the add-on's CELLAR_ADDON_KEY_SECRET is read when it is unset.

  • Origin: you set it; the code reads it.
  • Secret: yes: read once at start, then removed from the environment; never logged.
  • From a file: STUDIO_S3_KEY_SECRET_FILE names a file to read it from instead (mode 0600 on Linux and macOS).
  • Read by: studio-server/src/server/config.ts.

STUDIO_SESSION_KEY

The keys that seal the members' session cookies: one key, or several separated by commas, each 32 characters or more (openssl rand -base64 48). The first key seals; every key listed opens. To rotate, put the new key first and keep the old one listed until the sessions it sealed have expired; dropping a key logs out the sessions sealed with it. Required with oidc.

  • Origin: you set it; the code reads it.
  • Secret: yes: read once at start, then removed from the environment; never logged.
  • From a file: STUDIO_SESSION_KEY_FILE names a file to read it from instead (mode 0600 on Linux and macOS).
  • Read by: studio-server/src/server/config.ts.

STUDIO_WORKER_KEY

The Ed25519 private key (PEM) that signs the jobs sent to the worker; line breaks may be written \n. Made by npm run studio-server -- worker-keys --out <folder>. Required with a worker.

  • Origin: you set it; the code reads it.
  • Secret: yes: read once at start, then removed from the environment; never logged.
  • From a file: STUDIO_WORKER_KEY_FILE names a file to read it from instead (mode 0600 on Linux and macOS).
  • Read by: studio-server/src/server/config.ts.

WEB_SCUMM_STUDIO_CLIENT

The folder of the built Studio page the server serves, when the configuration has no clientDir; .cache/studio-client beside the engine by default. The release archive's launcher sets it.

Studio worker

What the processing worker (npm run studio-worker) reads. The worker holds no secret: only the public key that checks the jobs the Studio signs.

WORKER_INSTANCE

The name of the one Studio whose jobs this worker runs: the same as worker.instance in the Studio's configuration.

WORKER_PUBLIC_KEY

The Ed25519 public key (PEM) that checks the Studio's signed jobs: the content of studio-worker.pub.

WORKER_PUBLIC_KEY_FILE

A file holding the public key, read in place of WORKER_PUBLIC_KEY when set.

WORKER_PYTHON_PATH

Where the build hook installed the asset tools' Python packages; .python in the worker's folder when unset.

Set by Clever Cloud and its add-ons

Clever Cloud gives these to an app, or reads them itself to build and run it. The add-ons' variables reach the studio app only when the add-on is linked to it.

APP_FOLDER

Leave it unset: both apps build from the repository's root. An app that held another project may still have one (clever env rm APP_FOLDER).

  • Origin: set by you; Clever Cloud reads it.
  • Read by: no file of the code; the platform reads it.

APP_HOME

The app's folder on the instance; the daily backup runs from it (cd "$APP_HOME" in a clever ssh session too).

CC_HEALTH_CHECK_PATH

The path Clever Cloud probes before it sends traffic to a new instance: /startz on the studio app.

  • Origin: set by you; Clever Cloud reads it.
  • Read by: no file of the code; the platform reads it.

CC_NODE_DEV_DEPENDENCIES

Set it to install on both apps: the server runs from the repository with tsx, a development dependency.

  • Origin: set by you; Clever Cloud reads it.
  • Read by: no file of the code; the platform reads it.

CC_POST_BUILD_HOOK

A command Clever Cloud runs after the build: npm run studio-client on the studio app; the worker's installs the Python packages from ops/studio/worker-requirements.lock.

  • Origin: set by you; Clever Cloud reads it.
  • Read by: no file of the code; the platform reads it.

CC_RUN_COMMAND

The command that starts the app: npm run studio-server -- serve on the studio app, npm run studio-worker on the worker.

  • Origin: set by you; Clever Cloud reads it.
  • Read by: no file of the code; the platform reads it.

CELLAR_ADDON_KEY_ID

The Cellar add-on's access key id, read when STUDIO_S3_KEY_ID is not set.

  • Origin: injected by the Clever Cloud Cellar add-on.
  • Secret: yes: read once at start, then removed from the environment; never logged.
  • Read in place of STUDIO_S3_KEY_ID when STUDIO_S3_KEY_ID is not set.
  • Read by: studio-server/src/server/config.ts.

CELLAR_ADDON_KEY_SECRET

The Cellar add-on's secret key, read when STUDIO_S3_KEY_SECRET is not set.

  • Origin: injected by the Clever Cloud Cellar add-on.
  • Secret: yes: read once at start, then removed from the environment; never logged.
  • Read in place of STUDIO_S3_KEY_SECRET when STUDIO_S3_KEY_SECRET is not set.
  • Read by: studio-server/src/server/config.ts.

INSTANCE_NUMBER

The number of the app's instance. The daily backup runs only on instance 0, so two instances never both back up.

PORT

The port to listen on. Clever Cloud gives it to the studio and worker apps; elsewhere 8080 when unset. A port in the Studio's configuration wins over it.

POSTGRESQL_ADDON_URI

The PostgreSQL add-on's connection URI. The Studio Server reads it when STUDIO_DATABASE_URL is not set.

  • Origin: injected by the Clever Cloud PostgreSQL add-on.
  • Secret: yes: read once at start, then removed from the environment; never logged.
  • Read in place of STUDIO_DATABASE_URL when STUDIO_DATABASE_URL is not set.
  • Read by: studio-server/src/server/config.ts.

ROOT

The app's folder, used by clevercloud/cron.json (crons need absolute paths) and by the backup script when APP_HOME is missing.

Engine, local Studio and tools

Read by the engine's commands, the local Studio and its MCP server, in the engine repository or in a created project.

ASSETS_DIR

The folder of the built assets that ship, in place of public/assets (a test fixture's own files).

DIST_DIR

The built folder npm run weight measures; dist when unset.

FURNACE_BIN

The path of the Furnace executable the audio pipeline renders with, when it is not where python -m mdpipe setup put it.

GAME

Which game of games/ the engine repository's commands work on (GAME=reference npm run validate). Without it, the game last selected (npm run game -- <id>), then config.game of package.json, then demo.

GAME_DIR

The game folder the tools work on, anywhere on disk. When set, it is always the folder read, whatever GAME says, in place of games/<GAME> or a created project's game/; without GAME, the game's id is the folder's name.

PROOF_CACHE

0 turns the solver's result cache off for one run (like --no-cache).

PROOF_CACHE_DIR

Where the solver's result cache lives; .cache/proofs of the project when unset.

PYTHON

The Python interpreter quest-n-click assets runs; python3 when unset.

WEB_SCUMM_ALLOW_CUSTOM_PROVIDER

1 lets the Studio's Assistant call a provider URL you type yourself; refused otherwise.

WEB_SCUMM_DEV_URL

The dev server the MCP screenshot tool opens; http://localhost:5173/ when unset.

WEB_SCUMM_LAN

1 makes the dev server and the local Studio listen on the local network, behind a token. npm run dev:lan and studio:lan set it.

WEB_SCUMM_PROJECT

The created project the engine's tools work on. The quest-n-click command sets it to the folder it runs in; you do not set it yourself.

WEB_SCUMM_STUDIO_HOSTS

The host names the local Studio answers to in LAN mode, comma-separated; any other Host is refused. studio:lan sets it from the machine's addresses.

WEB_SCUMM_STUDIO_TOKEN

The token the local Studio asks for in LAN mode. studio:lan draws one at random unless you set it.

Building the pages

Read when Vite builds the game, the Studio or a preview. The npm scripts set most of them; VITE_*, BASE_URL and DEV end up inside the built page.

BASE_PATH

The sub-path the game is served under (/<repo>/ on GitHub Pages); / when unset.

BASE_URL

The base the page was built for, from BASE_PATH.

DEV

True under the dev server (npm run dev), false in a build.

  • Origin: set by Vite (read when the page or the package is built).
  • Read by: src/main.ts.

STUDIO

1 builds or serves the Studio's pages beside the game (npm run studio, the demo Studio).

STUDIO_CLIENT

1 builds the hosted Studio's page only (npm run studio-client).

  • Origin: set by npm run studio-client (read when the page or the package is built).
  • Read by: vite.config.ts.

VITE_STUDIO_DEMO

1 builds the demo Studio, which runs in the browser with no server (npm run build:studio-demo).

VITE_STUDIO_HOSTED

1 builds the Studio for a Studio Server (npm run studio-client).

  • Origin: set by npm run studio-client (read when the page or the package is built).
  • Read by: src/studio/main.ts.

VITE_STUDIO_PREVIEW

1 in a revision's preview, which the worker builds with the editing tools in; 0 in a published build.

Reality Bridge

Read by quest-n-click-bridge (or npm run bridge in the engine repository).

BRIDGE_STORE

The Bridge's store when no --store= is given: jsonl, sqlite, sqlite:<file> or a postgres:// URL. It wins over store in config.json.

BRIDGE_STORE_FILE

A file holding the store's URL, read when BRIDGE_STORE is empty, so a database password is mounted as a secret file and never shows in a process listing.

OTEL_EXPORTER_OTLP_ENDPOINT

Where the Bridge exports its measures over OTLP, when @opentelemetry/sdk-node is installed beside it; nothing is exported otherwise. The SDK reads the other standard OTEL_* variables itself.

Tests, CI and releases of the engine

Read by the engine repository's test, CI and release scripts only. A created project never needs them.

BRIDGE_PG_MODULE

The pg module tools/backup-memory.ts imports, when it is not the repository's own.

BRIDGE_PG_URL

A PostgreSQL URL the tests run the Bridge's store and the mutation runs against; those tests are skipped without it.

CONSUMER_PG_URL

A PostgreSQL URL npm run external-consumer also runs the installed Bridge against.

E2E_BROWSER

The browser an end-to-end test runs in (chromium, firefox, webkit); Chromium when unset.

E2E_CPU

A CPU slow-down factor for the end-to-end tests in Chromium (4 runs four times slower).

E2E_DEBUG

Any value makes the hosted Studio's end-to-end test print what it does.

E2E_INPUT

keyboard plays the end-to-end walkthrough with the keyboard instead of taps.

E2E_OUT

Where an end-to-end test writes its screenshots and reports.

E2E_WEIGHT_DEBUG

Any value makes e2e:weight print the requests it counted.

GH_TOKEN

The GitHub token of the gh command. tools/release/run-jobs.mjs reads it before GITHUB_TOKEN; npm run wiki -- publish reads it only when GITHUB_TOKEN is not set.

GITHUB_TOKEN

A GitHub token for the release and documentation tools. npm run wiki -- publish reads it before GH_TOKEN (after the deploy key WIKI_DEPLOY_KEY); tools/release/run-jobs.mjs reads it only when GH_TOKEN is not set. On a runner GitHub Actions gives it.

MUTATION_SET

The set of tests a mutant is judged by (core, reality…); core when unset. npm run test:mutation:* sets it.

NEEDS

The results of a workflow's jobs, as JSON, that the candidate's verdict reads. The workflow sets it.

QUALIFY_APP

Set by npm run ops:qualify for ops/qualify/compose.yml: the committed tree the speedrun worker reads.

QUALIFY_BUILD

Set by npm run ops:qualify for ops/qualify/compose.yml: the folder of the Bridge image's build context.

QUALIFY_DATA

Set by npm run ops:qualify for ops/qualify/compose.yml: the folder of the two tenants' data.

QUALIFY_GID

Set by npm run ops:qualify for ops/qualify/compose.yml: the group id the containers run as (1000 by default).

QUALIFY_MODULES

Set by npm run ops:qualify for ops/qualify/compose.yml: the installed modules mounted beside it.

QUALIFY_PORT

Set by npm run ops:qualify for ops/qualify/compose.yml: the local port of the proxy (8443 by default).

QUALIFY_PORT_1

Set by npm run ops:qualify for ops/qualify/compose.yml: the proxy's second local port (8444 by default).

QUALIFY_PORT_2

Set by npm run ops:qualify for ops/qualify/compose.yml: the proxy's third local port (8445 by default).

QUALIFY_PORT_3

Set by npm run ops:qualify for ops/qualify/compose.yml: the proxy's fourth local port (8446 by default).

QUALIFY_SECRETS

Set by npm run ops:qualify for ops/qualify/compose.yml: the folder of the database password and the store's URL.

QUALIFY_UID

Set by npm run ops:qualify for ops/qualify/compose.yml: the user id the containers run as (1000 by default).

SHIP_PIDS

The folder where npm run ship writes its process ids; .cache/pids when unset.

SHIP_TRAILERS

Extra trailer lines npm run ship adds to a merge commit, after Agent: Claude.

STUDIO_TEST_S3

The S3 endpoint, credentials and bucket of the CI's object store, as one URL, for the hosted Studio's tests.

WEB_SCUMM_REPO

The GitHub repository the release tools work on; wanoo/quest-n-click when unset.

WIKI_DEPLOY_KEY

The SSH deploy key that pushes the documentation to the GitHub wiki (npm run wiki -- publish); GITHUB_TOKEN is used without it.

Set by the system, npm or GitHub Actions

Nobody sets these by hand: the operating system, npm, Vitest or a GitHub runner does. The code only reads them.

GITHUB_ACTIONS

true on a GitHub runner: the tests and ratchets adapt their output and their limits.

GITHUB_API_URL

The GitHub API's address on a runner.

GITHUB_ENV

The file a step appends NAME=value lines to, for the next steps of its job.

GITHUB_OUTPUT

The file a step writes its outputs to.

GITHUB_STEP_SUMMARY

The file a job writes its summary to; npm run ci:plan writes the plan there.

HOME

The user's home folder. The A7 chain script refuses it as its output folder; the Studio Server gives its own git commands a HOME of its working folder, never yours.

ImageOS

The runner's image, recorded beside a measurement.

PATH

The system's search path. The Studio Server and the worker pass it to their child processes, and nothing else of the environment.

PWD

The shell's current folder.

RUNNER_OS

The runner's system, recorded beside a measurement.

SystemRoot

The Windows folder; the tools find tar.exe under it.

VITEST

Set while Vitest runs: the local Studio's plugin then starts nothing.

npm_lifecycle_event

The npm script that is running; a tool that writes the game records it as the author of the change.

Inside the CI workflows

Set and read by the workflows of .github/workflows/ only: an input handed to a step's shell through env:, or a value one step leaves to the next in $GITHUB_ENV. Nothing to set by hand.

ALL

ci: true when every check runs (a push, or a pull request labelled full-ci).

ARCHIVE

docs-publish: the path of the archive to publish.

ARCHIVE_SHA

docs-publish: that archive's sha256.

CALLED

docs-publish: true when release.yml calls it, with a verified archive.

CANDIDATE

docs-publish: the candidate run whose test report is read.

DISPATCHED_MODE

docs-publish: the mode chosen by hand (revision, rollback, promote, preview).

DOCS_ARCHIVE

release: the documentation archive of the release, when it has one.

EXTRA_ASSETS

release: the other files uploaded with the release.

FILE

mutation: one file to mutate, chosen by hand.

FULL

ci: false in a Pages-only run, which then skips its other steps.

IN_CANDIDATE

docs-publish: the candidate run release.yml passes.

IN_REVISION

docs-publish: the doc revision release.yml passes (r1).

IN_SHA

docs-publish: the tag's commit release.yml passes.

IN_SHA256

docs-publish: the sha256 of the archive ship verify checked.

IN_TAG

docs-publish: the release tag release.yml passes.

MODE

docs-publish: the mode decided for the run, left to the next steps.

MUTATION

ci: true when a pull request labelled full-ci also runs the mutation tests.

NPM_PUBLISH_NODE

release: the Node.js version npm publishing runs on.

NPM_PUBLISH_NPM

release: the npm version that publishes.

P

release: the release's file name prefix (quest-n-click).

PAGES_ONLY

ci: true for a dispatched Pages-only run, which rebuilds the site and /docs/ and nothing else.

POSTGRES_DB

The PostgreSQL service container's database.

POSTGRES_PASSWORD

The PostgreSQL service container's password, CI only.

POSTGRES_USER

The PostgreSQL service container's user, read by its image.

PRODUCT_TAG

docs-publish: the product's tag the documentation describes.

PROFILE

candidate: the deployment smoke's profile, full when started by hand, short otherwise.

RELEASE_TAG

docs-publish: the release that carries the archive (v<v> or docs-v<v>-r<n>).

REMIX_ASSETS

release: the remix files added to the release, when there are some.

REPO

The repository the workflow runs in (owner/name), for its gh calls.

REUSED

docs-publish: true when a release already made by an earlier run is reused.

REVISION

docs-publish: the doc revision being published (r1, r2…).

RUN

ci: whether the plan asks for the Reality jobs.

RUN_ID

docs-publish: this run's id, the archive's build id.

RUN_REF

docs-publish: the ref the run stands on, checked against its mode.

SET

mutation: the mutation set chosen by hand.

SHA

release: the commit the candidate run tested.

STORE

candidate: the store tools/backup-memory.ts measures, sqlite or a PostgreSQL URL.

STUDIO_TEST_CAPTURES

ci: 1 keeps the hosted Studio test's screenshots.

STUDIO_TEST_KEYCLOAK

ci: the Keycloak service the hosted Studio's end-to-end test logs in with.

STUDIO_TEST_KEYCLOAK_ADMIN

ci: that Keycloak's administrator, CI only.

STUDIO_TEST_PG_URL

ci: the PostgreSQL service the hosted Studio's tests use.

TAG

release: the tag being released.

TARGET

docs-publish: the <version>[-r<n>] a rollback or a promotion aims at.

VERSION

docs-publish: the product version to publish (its version input).

WANT

candidate: the full SHA a run started by hand must test (its sha input).