Public runtime configuration
This reference covers supported public runtime settings for server/container deployments, the desktop app, TypeScript and Python API clients, and the local MCP bridge. Build-only, test-only, CI workflow, launcher handoff, and pass-through environment values are intentionally classified separately and are not presented as supported application runtime settings. The registry is maintained in packages/sketchforge-engine/src/support/lib/operator-configuration.json; regenerate this page with node scripts/generate-operator-configuration.mjs.
required means required to enable the described optional feature; no setting is required for the application to start with its default behavior.
| Name | Default | Required | Validation and behavior | Sensitive | Owning subsystem | Owner guide(s) | Source reader(s) |
|---|---|---|---|---|---|---|---|
SKETCHFORGE_PORT | 3000 | No | Compose host port published to container port 3000; configure this when host port 3000 is already occupied. | No | Docker port publishing | Docker port publishing guide | ../deploy/docker/compose.yaml |
SKETCHFORGE_SHARED_PROJECTS_VOLUME | sketchforge-shared-projects | No | Docker named volume or bind mount source for /data/projects, where shared project files are stored. | No | Docker shared project persistence | Docker shared project persistence guide | ../deploy/docker/compose.yaml |
SKETCHFORGE_PROJECTS_VOLUME | sketchforge-projects | No | Docker named volume or bind mount source for /data/my-projects. Used when SKETCHFORGE_PROJECTS_DIR points to that path. | No | Docker server project persistence | Docker server project persistence guide | ../deploy/docker/compose.yaml |
PORT | 3000 | No | Integer from 1 through 65535; invalid values fall back to 3000. | No | Docker server listener | Docker server listener guide | ../deploy/docker/start-server.mjs |
HOSTNAME | 0.0.0.0 in the Docker launcher; otherwise supplied by the hosting runtime. | No | Passed to the Next.js server as its bind host. | No | Docker server listener | Docker server listener guide | ../deploy/docker/start-server.mjs |
SKETCHFORGE_LEGACY_PORT | 80 | No | Integer from 1 through 65535; invalid values fall back to 80. Set equal to PORT to disable the compatibility proxy. | No | Docker compatibility proxy | Docker compatibility proxy guide | ../deploy/docker/start-server.mjs |
SKETCHFORGE_PROJECTS_DIR | Unset; browser-local storage is used. | No | Filesystem path writable by the server. Enables server-backed project storage and must be paired with SKETCHFORGE_API_TOKEN to enable the scripting REST API. | No | Server project storage and REST API | Server project storage and REST API guide additional guide | ../apps/web/src/lib/serverProjectStore.ts ../packages/sketchforge-client/mcp/localEngine.mjs ../packages/sketchforge-client/mcp/localMacroRunner.mjs |
SKETCHFORGE_MCP_FILES_DIR | SKETCHFORGE_PROJECTS_DIR; unrestricted when both are unset. | No | Filesystem root for MCP file imports and exports. Resolved symlinks must remain inside this directory. | No | MCP host file access | MCP host file access guide | ../packages/sketchforge-client/mcp/filesystemPaths.mjs ../packages/sketchforge-client/mcp/server.mjs ../packages/sketchforge-client/mcp/localEngine.mjs |
SKETCHFORGE_API_TOKEN | Unset; REST API authorization is disabled. | No | Non-empty bearer token. Configure a high-entropy secret; never expose it to browsers or logs. Used with SKETCHFORGE_PROJECTS_DIR. | Yes | REST API authentication | REST API authentication guide additional guide | ../apps/web/src/lib/apiTokens.ts ../packages/sketchforge-client/src/environment.ts ../packages/sketchforge-py/src/sketchforge3d/environment.py ../packages/sketchforge-client/mcp/server.mjs |
SKETCHFORGE_SHARED_PROJECTS_DIR | /data/projects in the Docker image and compose examples. | No | Filesystem path writable by the server; mount persistent storage at this path to retain shared projects across container replacement. | No | Shared project files | Shared project files guide | ../apps/web/src/app/api/shared-projects/route.ts |
SKETCHFORGE_APP_VERSION | Detected from the installed package or project metadata. | No | Semantic version; invalid values are ignored. | No | Update status | Update status guide | ../apps/web/src/app/api/app-update/route.ts |
SKETCHFORGE_UPDATE_MANIFEST_URL | Official SketchForge release manifest URL. | No | HTTP or HTTPS URL returning JSON with a semantic-version version field. | No | Update status | Update status guide | ../apps/web/src/app/api/app-update/route.ts |
SKETCHFORGE_UPDATE_GUIDE_URL | Official SketchForge update guide URL. | No | URL shown to users as the update guide. | No | Update status | Update status guide | ../apps/web/src/app/api/app-update/route.ts |
SKETCHFORGE_UPDATE_TRIGGER_URL | Unset; server-triggered updates are unavailable. | No | HTTP or HTTPS URL for the configured update trigger endpoint. | No | Server-triggered updates | Server-triggered updates guide | ../apps/web/src/app/api/app-update/route.ts |
SKETCHFORGE_UPDATE_ADMIN_KEY | Unset; server-triggered updates are unavailable, and a local-checkout update needs SKETCHFORGE_LOCAL_UPDATE. | No | Secret the administrator enters in the update dialog. Required with SKETCHFORGE_UPDATE_TRIGGER_URL for server-triggered updates. When the server runs from a source checkout and SKETCHFORGE_LOCAL_UPDATE is not set, it also gates the local-checkout update. | Yes | Server-triggered and local-checkout updates | Server-triggered and local-checkout updates guide additional guide | ../apps/web/src/app/api/app-update/route.ts |
SKETCHFORGE_LOCAL_UPDATE | Unset; a local-checkout update requires SKETCHFORGE_UPDATE_ADMIN_KEY. | No | 1 or true lets a request addressed to localhost update a source-checkout install without the admin key. The route cannot see the caller's address, so set it only when the server listens on loopback alone (for example next dev -H 127.0.0.1). Any other value leaves it off. | No | Local-checkout updates | Local-checkout updates guide additional guide | ../apps/web/src/app/api/app-update/route.ts |
SKETCHFORGE_UPDATE_TRIGGER_TOKEN | Unset; trigger requests are unauthorized. | No | Secret bearer token sent to the configured trigger endpoint. Required when that endpoint enforces a trigger token. | Yes | Server-triggered updates | Server-triggered updates guide | ../apps/web/src/app/api/app-update/route.ts |
SKETCHFORGE_URL | http://127.0.0.1:3000 | No | Base URL of the SketchForge server. The TypeScript and Python macro clients use this when no explicit client option overrides it. | No | TypeScript and Python API clients | TypeScript and Python API clients guide | ../packages/sketchforge-client/src/environment.ts ../packages/sketchforge-py/src/sketchforge3d/environment.py |
SKETCHFORGE_PROJECT_ID | Unset; a target macro must receive a project id explicitly or fail. | No | Project identifier used by macros whose project mode is target; --project or an explicit macro option takes precedence. | No | TypeScript and Python macro clients | TypeScript and Python macro clients guide | ../packages/sketchforge-client/src/environment.ts ../packages/sketchforge-py/src/sketchforge3d/environment.py |
SKETCHFORGE_MACRO_DIR | Unset; MCP macro listing and execution are disabled. | No | Path to a directory of reviewed .mjs, .js, or .py macro files exposed by the MCP macro tools. | No | MCP macro discovery and execution | MCP macro discovery and execution guide | ../packages/sketchforge-client/mcp/macroTools.mjs |
SKETCHFORGE_MACRO_TIMEOUT_MS | 120000 milliseconds | No | Positive number of milliseconds before an MCP macro process is stopped; invalid or non-positive values use the default. A per-call timeoutMs overrides it. | No | MCP macro execution | MCP macro execution guide | ../packages/sketchforge-client/mcp/macroTools.mjs |
SKETCHFORGE_MACRO_PYTHON | python3 | No | Executable used to inspect and run Python macros through the MCP bridge. It must be available to the MCP process. | No | MCP Python macro execution | MCP Python macro execution guide | ../packages/sketchforge-client/mcp/macroTools.mjs |
SKETCHFORGE_MACRO_RUNNER_JS | The JavaScript macro runner bundled with @constructorfleet/sketchforge3d. | No | Optional path to an installed sketchforge-macro runner used instead of the package-bundled runner. | No | MCP JavaScript macro execution | MCP JavaScript macro execution guide | ../packages/sketchforge-client/mcp/macroTools.mjs |
SKETCHFORGE_DESKTOP_PORT | 62158 | No | Whole number from 1 to 65535, surrounding whitespace ignored, used as the loopback port for the packaged desktop web server. Unset or blank uses 62158. Any other value, including 0, a negative or fractional number, or trailing text, is ignored and 62158 is used instead: the app writes a warning to the console and shows a notice in the app window naming the rejected value, the port used and this variable. If another program already holds the port, or the user may not listen on it, the app shows a startup error naming the port and this variable instead of a generic web-process failure. Changing it changes the browser storage origin used by the desktop app. | No | Desktop application origin | Desktop application origin guide | ../apps/desktop/main.cjs ../apps/desktop/port.cjs |
SKETCHFORGE_LOCAL_DOWNLOAD_ROOT | Unset; folder downloads are disabled. | No | Absolute or relative directory allowed as a destination for desktop folder downloads. The packaged desktop app sets this to the user's Downloads directory and binds its web server to 127.0.0.1. The route is disabled unless SKETCHFORGE_DESKTOP=1 and this root is set; requested folders must remain inside the root. | No | Desktop folder downloads | Desktop folder downloads guide | ../apps/web/src/app/api/local-download/route.ts ../apps/desktop/main.cjs |
Desktop settings
SKETCHFORGE_DESKTOP_PORT selects the loopback port used by the packaged desktop app. Browser storage is scoped to the full origin, including its port; changing this value makes projects saved under the previous port appear in a different storage origin. For that reason an invalid value is never used silently: anything other than a whole number from 1 to 65535 is ignored, and the app starts on the default port 62158, where projects saved under the configured port will not appear. It writes a warning to the console and, once its window opens, shows a notice naming the rejected value, the port it used and SKETCHFORGE_DESKTOP_PORT. Port 0 is refused because the operating system would choose a different port, and so a different origin, on every launch. Before starting its web process, the app checks that it can listen on the port. If another program holds it, or the operating system does not allow listening on it (for example a port below 1024 on Linux), startup stops with an error naming the port and SKETCHFORGE_DESKTOP_PORT, so you can close that program or choose another port. The check makes it much less likely, though not impossible, that another program takes the port in the moment before the web process starts; if one does, the same error is shown. SKETCHFORGE_LOCAL_DOWNLOAD_ROOT enables folder downloads only in the packaged desktop app and confines them to the configured root; the app sets it to the user's Downloads directory and binds its web server to 127.0.0.1. The App Router cannot inspect the socket peer address, so do not enable this helper on a network listener. The desktop development launcher injects SKETCHFORGE_DESKTOP_DEV_URL as an internal handoff to its temporary web server; it is not a user setting. NODE_PATH is forwarded to the packaged child process and is not a SketchForge desktop setting.
Update settings
The update status and update settings are read by apps/web/src/app/api/app-update/route.ts. The version, manifest URL, and guide URL customize update information. The privileged update action has two modes. Server mode posts to the trigger URL and needs both the trigger URL and the admin key; the trigger token authenticates SketchForge to that endpoint. Local mode applies when the server runs from a git checkout and the request is addressed to localhost: it runs git fetch, git merge --ff-only, and npm install in the checkout and restarts the dev server. Local mode needs SKETCHFORGE_LOCAL_UPDATE=1 or the admin key, and refuses with 403 when neither is set. The route cannot see the caller's address, and the localhost test reads the client-controlled Host header, so set SKETCHFORGE_LOCAL_UPDATE only on a server that listens on loopback alone. Keep both credentials in deployment secrets and only configure a trigger endpoint you control. The packaged desktop app uses its own updater and none of these settings affect it.
Scope and limitations
Compose uses SKETCHFORGE_PORT to choose the host port published to container port 3000. The Docker launcher currently validates PORT and SKETCHFORGE_LEGACY_PORT; invalid values fall back to their listed defaults. Other path and URL settings are validated or interpreted by their owning subsystem at runtime as described above. Keep secrets in the deployment secret store and avoid printing them in logs.
The registry and documentation tests track supported server/container, desktop, client, and local MCP runtime settings against their implementation readers. Each row links to all assigned owner pages and its authoritative reader or deployment declaration. Adding a supported runtime setting requires a registry row with a source and an owning guide; the docs verification fails when a setting in the tracked runtime reader surfaces has no row.
Environment values outside the supported runtime inventory
Repository environment values also include build switches (such as STATIC_EXPORT, SKETCHFORGE_DOCKER_BUILD, and NEXT_PUBLIC_STATIC_EXPORT), test and performance inputs, CI workflow values, and values forwarded to child processes. These are build-only, test-only, CI-owned, launcher handoff, or pass-through inputs; they are not supported application settings in this inventory.
Documentation version: 1.30.0 · Repository revision: 1cb9fee8dff4d394684c229dd67a21da539d167f · View source