Configuration

Genie is configured through environment variables at build or start time, and the web frontend can also be configured at load time through a runtime config script. This page lists every setting by component.

How the frontend reads its configuration

The frontend (apps/standalone) resolves each setting in this order:

1. Runtime config. index.html loads /genie-runtime-config.js before the app. That script sets window.__GENIE_RUNTIME_CONFIG__. A non-empty value there wins.
2. Build-time variable. Vite reads .env files in apps/standalone and the process environment. Each setting can be given with either the VITE_ or the NEXT_PUBLIC_ prefix; if both are set, VITE_ wins. The values are baked into the bundle at build time (or when the dev server starts).
3. Code default.

The NEXT_PUBLIC_ prefix is a leftover from an earlier Next.js setup; the app is built with Vite.

The shipped public/genie-runtime-config.js only creates an empty object:

window.__GENIE_RUNTIME_CONFIG__ = window.__GENIE_RUNTIME_CONFIG__ || {};

A deployment can replace that file to change configuration without rebuilding. The AWS CDK stack writes its own version (see Cloud deployment values).

Frontend settings

Setting	Build variable (after the VITE_ or NEXT_PUBLIC_ prefix)	Runtime key	Default
Backend WebSocket URL	GENIE_BACKEND_URL	backendUrl	Empty. The app then uses same-origin /ws when the backend mode is same-origin or when it runs inside Electron, and ws://localhost:8787/ws otherwise.
Backend mode	GENIE_BACKEND_MODE	backendMode	cloud when Vite runs in web mode; otherwise empty
Project API URL	GENIE_CLOUD_API_URL	cloudApiUrl	In web mode: /api/cloud on the dev server, http://localhost:8790 in a build. Otherwise empty, which means "use the backend's HTTP URL".
Assistant enabled	GENIE_ASSISTANT_ENABLED	assistantEnabled	true for the desktop renderer build; false for every other build
Sign-in required	GENIE_AUTH_REQUIRED	authRequired	false
AWS region	GENIE_AWS_REGION	awsRegion	Empty
Cognito user pool id	GENIE_USER_POOL_ID	userPoolId	Empty
Cognito app client id	GENIE_USER_POOL_CLIENT_ID	userPoolClientId	Empty
App target	Derived, see below	appTarget	local

Boolean settings accept the strings true and false (the runtime config also accepts JSON booleans).

The backend HTTP base URL is derived from the WebSocket URL: ws: becomes http:, wss: becomes https:, and a trailing /ws is removed.

Example: run the local web app with the assistant on and a backend on another port.

VITE_GENIE_ASSISTANT_ENABLED=true \
VITE_GENIE_BACKEND_URL=ws://localhost:9787/ws \
pnpm --filter standalone dev

App targets

The app target is set by the build, not by a variable of its own:

App target	How it is selected	Effect
desktop	GENIE_STANDALONE_TARGET=desktop vite build --mode desktop (the build:desktop-renderer script)	Assistant on by default; output goes to apps/standalone/.next-desktop, which the Electron app serves
web	Vite --mode web (pnpm dev:web, pnpm build, pnpm build:web)	Backend mode defaults to cloud; project API defaults to the cloud project API; assistant off by default
local	Any other mode (pnpm dev, pnpm --filter standalone dev)	Backend at ws://localhost:8787/ws serves both chat and project data; assistant off unless enabled

Vite builds always set a target. Only when no valid target is configured does the code fall back to treating a page running inside Electron (where the preload script exposes window.genieDesktop.target === "electron") as desktop.

The project API URL is resolved separately from the backend URL: a configured cloudApiUrl wins; with the web target and nothing configured it falls back to http://127.0.0.1:8790; otherwise project data goes to the backend's HTTP URL.

Backend modes

Backend mode	Effect
Unset	Chat connects to ws://localhost:8787/ws (or the configured URL). Project data goes to the same backend unless a project API URL is set.
same-origin	Chat connects to /ws on the page's own origin (wss: on HTTPS pages). Use this when the backend serves the built frontend through GENIE_STATIC_ROOT.
static	Read at build time only. The build contains only the public browser (/ and /browser/:genomeId, rendered by the native browser packages for hg38 and hg19), read-only shared projects (/shared/:shareId) and developer pages. There are no project or assistant routes.
cloud	Default for web builds. Cloud behaviour comes from the web app target and the project API URL.

What each configuration enables

Configuration	Project data	Assistant	Sign-in	Share links
Desktop app	Embedded local backend	On when the Codex CLI is found	None	No: the dialog shows "Sharing settings could not be loaded."
Local web (pnpm dev)	Local backend on :8787	Only with VITE_GENIE_ASSISTANT_ENABLED=true	None	No: the local backend has no sharing routes
Web, cloud mode (pnpm dev:web)	Cloud project API (genie-local-cloud in development)	Off	Only when authRequired is true	Yes
Hosted cloud build (CDK)	Lambda project API, DynamoDB, S3	Off	Required (Cognito)	Yes
Static build	None (public browser only)	Off	None	Opens /shared/:shareId links

The cloud project API does not serve models or chat: its /models route answers 404 with "Assistant models are not available from the cloud project API." Assistant sessions need the local backend and the Codex CLI.

Backend

The backend (apps/backend, built on packages/backend-core) reads these variables when it starts.

Variable	Default	Purpose
PORT	8787	HTTP and WebSocket port
HOST	127.0.0.1	Bind address
GENIE_SESSION_DATA_ROOT	genie/session-data	Folder for projects, sessions, assets, results and logs
GENIE_RESOURCE_ROOT	The genie/ repository root	Root for bundled resources the backend reads
GENIE_STATIC_ROOT	Unset	If set, the backend serves this folder (a built frontend) and answers HTML requests for app routes with the frontend's index.html
GENIE_CODEX_COMMAND	codex	Command used to start <command> app-server
GENIE_CLOUD_API_URL	Unset	If set, the backend mirrors project browser state to a cloud project API and reads it back before genome tools run

The backend sends Access-Control-Allow-Origin: * and has no authentication. Keep it bound to 127.0.0.1.

Desktop app

Variable	Default	Purpose
GENIE_CODEX_COMMAND	Discovered	Path or command name of the Codex CLI. Without it the app checks /opt/homebrew/bin/codex, /usr/local/bin/codex, then a login shell.
GENIE_CLOUD_API_URL	Unset	Passed to the embedded backend
GENIE_DESKTOP_LOG_PATH	/tmp/genie-desktop-runtime.log	Startup log file

The embedded backend always binds 127.0.0.1 on a random free port and stores data in session-data/ under Electron's user-data folder.

Local cloud simulator

genie-local-cloud is a separate checkout next to genie/.

Variable	Default	Purpose
PORT or GENIE_LOCAL_CLOUD_PORT	8790	Listen port
HOST or GENIE_LOCAL_CLOUD_HOST	localhost	Bind address
GENIE_LOCAL_CLOUD_DATA_ROOT	genie-local-cloud/.local-cloud	Storage folder (dynamodb/single-table.json, s3/objects/)
GENIE_LOCAL_CLOUD_LATENCY_MS	0	Fixed delay added to every non-preflight request
GENIE_LOCAL_CLOUD_LATENCY_JITTER_MS	0	Extra random delay of 0 to N ms

pnpm dev:local-cloud:latency and pnpm dev:web-cloud set the latency to 800 ms with 400 ms of jitter.

Cloud deployment values

The CDK app in infra/aws-cdk takes these inputs:

Input	Kind	Default
appName	CDK context	genie-dev (prefix for resource names)
stackName	CDK context	GenieDevCloudStack
removalPolicy	CDK context	retain (destroy deletes data with the stack)
webDistPath	CDK context	apps/standalone/dist
CDK_DEFAULT_ACCOUNT, CDK_DEFAULT_REGION	Environment	Region us-east-1 if unset

At deploy time the stack writes this runtime config to the web bucket as genie-runtime-config.js:

window.__GENIE_RUNTIME_CONFIG__ = {
  "appTarget": "web",
  "backendMode": "cloud",
  "assistantEnabled": "false",
  "authRequired": "true",
  "awsRegion": "<stack region>",
  "cloudApiUrl": "<HTTP API URL>",
  "userPoolId": "<Cognito user pool id>",
  "userPoolClientId": "<Cognito app client id>"
};

Other variables

Variable	Used by	Purpose
TEST_PORT	apps/backend/integration-server.js	Port for the backend smoke test (default 8790, the same as the local cloud simulator; set another port if the simulator is running)
GENIE_AC_NETWORK	packages/backend-core tests	Set to 1 to run the acceptance tests that fetch live public files
EG_REACT_FRONTEND_ROOT	@genie/genome-catalog generator	Path to the eg-react frontend folder used to regenerate the genome catalog
DOCS_SITE_URL, DOCS_BASE_URL	apps/docs build	Site URL and base path of this documentation site
DOCS_TEST_PORT	apps/docs Playwright suite	Port for the served docs build (default 3101)

Ports

Port	Service	Notes
8787	Genie backend (HTTP and WebSocket /ws)	PORT
3000	Vite dev server for apps/standalone	Moves to the next free port if taken
8790	genie-local-cloud project API	Also the default TEST_PORT for the backend smoke test
Random	Desktop app's embedded backend	Bound to 127.0.0.1
3100	Docs dev server	pnpm --filter genie-docs dev
3101	Docs static server and Playwright tests	pnpm --filter genie-docs serve

Related pages

• Getting started
• Desktop and cloud
• Backend reference