Environment variables

Synthigy is configured with environment variables. synthigy up reads them from the instance's .env (a value in the file wins over the shell) and passes them to the engine. synthigy doctor prints every value in effect and where it came from, and the portal edits most of them.

Instance

Where the instance lives and which engine runs.

Variable	Default	Description
SYNTHIGY_HOME		Instance directory: .env, pid files, logs, and the local database files in db/ (synthigy.db, audit.db, logs.db). Unset, the CLI uses the nearest .synthigy/ above the current directory, else ~/.synthigy.
SYNTHIGY_ENV_FILE		Profile file to use instead of <home>/.env (same as --env).
SYNTHIGY_BUNDLE		Which engine bundle runs: sqlite, postgres or postgres-clickhouse. Unset, synthigy up opens the setup page.
SYNTHIGY_VERSION	latest	Engine release to run, e.g. v0.2.12, or latest.
SYNTHIGY_RELEASES_REPO	synthigy/synthigy	GitHub repository releases are downloaded from (owner/repo).
SYNTHIGY_PROFILE	full	full runs identity, OAuth and the console. bare runs the data API alone with NO authentication — trusted networks only.
SYNTHIGY_JAR		A local jar, or a classpath of jars, to run instead of a downloaded release — custom builds, air-gapped machines and app jars (EMBEDDED.md).
SYNTHIGY_REQUIRE		Namespaces the engine loads before starting, comma separated. For app jars.
SYNTHIGY_MODULES		Modules the engine starts instead of the default server and console, comma separated (:my/app,:synthigy/console). Dependencies start on their own.
SYNTHIGY_LICENSE		Commercial license key. Synthigy runs without one.

Server

Variable	Default	Description
SYNTHIGY_SERVER_HOST	localhost	Interface the engine binds.
SYNTHIGY_SERVER_PORT	7887	Port the engine serves on.
SYNTHIGY_PORTAL_PORT	7888	Port of the portal (always bound to 127.0.0.1).
SYNTHIGY_IAM_ROOT_URL		Public URL of this instance, e.g. https://id.example.com. Issuer of tokens and base of every login and redirect link — set it whenever the instance is reached by any other name than localhost.
SYNTHIGY_SERVER_ALLOWED_ORIGINS		Extra browser origins allowed to call the API, comma separated (CORS.md).
SYNTHIGY_SERVER_TRUST_PROXY		Any value: take the client address from X-Forwarded-For. Set only behind a reverse proxy (PROXY.md).
SYNTHIGY_SERVER_SSE_MAX_LIFETIME_MS	900000	Longest life of one subscription stream, in milliseconds, before the server closes it; clients reconnect on their own.

SQLite

The sqlite bundle keeps synthigy.db and audit.db in <home>/db/.

Variable	Default	Description
SQLITE_POOL_SIZE	8	Most connections in the pool.

PostgreSQL

The postgres and postgres-clickhouse bundles. Synthigy never creates the database itself.

Variable	Default	Description
POSTGRES_HOST	localhost	Server host.
POSTGRES_PORT	5432	Server port.
POSTGRES_DB	synthigy	Database name.
POSTGRES_USER	postgres	User.
POSTGRES_PASSWORD		Password.
POSTGRES_POOL_SIZE	20	Connections in the main pool.
POSTGRES_DRAINER_POOL_SIZE	2	Connections of the separate pool that writes audit history.

Logs and traffic (local)

The sqlite and postgres bundles keep logs and traffic in <home>/db/logs.db, capped by size and age. Audit history is never pruned.

Variable	Default	Description
SQLITE_LOGS_MAX_MB	1024	Size cap of the log file.
SQLITE_LOGS_RETENTION_DAYS	30	Days logs are kept.
SQLITE_LOGS_BUFFER_SIZE	8192	Log entries held in memory while waiting to be written.
SQLITE_LOGS_BATCH_ROWS	500	Most rows written in one batch.
SQLITE_LOGS_BATCH_MS	250	Longest wait, in milliseconds, before a batch is written.

ClickHouse

The postgres-clickhouse bundle sends audit, logs and traffic to ClickHouse.

Variable	Default	Description
CLICKHOUSE_URL		HTTP URL of ClickHouse, e.g. http://clickhouse:8123. Required.
CLICKHOUSE_DB	synthigy	Database.
CLICKHOUSE_USER		User.
CLICKHOUSE_PASSWORD		Password.
CLICKHOUSE_LOG_RETENTION_DAYS	30	Days logs are kept, applied when the table is created.
CLICKHOUSE_BUFFER_SIZE	8192	Rows held in memory while waiting to be written.
CLICKHOUSE_BATCH_ROWS	500	Most rows written in one batch.
CLICKHOUSE_BATCH_MS	1000	Longest wait, in milliseconds, before a batch is written.

Logging and audit

Variable	Default	Description
SYNTHIGY_LOG_LEVEL	info	Lowest level logged: trace, debug, info, warn, error, fatal.
SYNTHIGY_LOG_NS		Per-namespace levels, comma separated: synthigy.dataset*=debug,synthigy.oauth=warn.
SYNTHIGY_LOG_HOST		Host name stamped on log rows. Default: the machine's host name.
SYNTHIGY_LOG_RING_SIZE	10000	Log entries kept in memory before the log store is up.
SYNTHIGY_LOG_POLL_INTERVAL_MS	10000	How often, in milliseconds, log settings changed in the console are picked up.
SYNTHIGY_AUDIT_ALL		true: record history for every entity and relation, not only the ones marked for audit in the model.
SYNTHIGY_NODE_ID		Name of this node on traffic and log rows. Default: derived from the machine.

Encryption

The master key protects the data keys that encrypt sensitive attributes. Keep it out of version control; the portal manages it and its custody.

Variable	Default	Description
SYNTHIGY_ENCRYPTION_MASTER_KEY		Master key, b64: + 32 random bytes in base64. Local custody.
SYNTHIGY_VAULT_ADDR		HashiCorp Vault address. With SYNTHIGY_VAULT_TRANSIT_KEY, Vault Transit wraps the data keys and no master key is kept here.
SYNTHIGY_VAULT_TRANSIT_KEY		Name of the Transit key.
SYNTHIGY_VAULT_TRANSIT_MOUNT	transit	Mount of the Transit engine.
SYNTHIGY_VAULT_TOKEN		Vault token. Use this or the JWT login below.
SYNTHIGY_VAULT_ROLE		Role for Vault's JWT/Kubernetes login.
SYNTHIGY_VAULT_MOUNT		Mount of the JWT/Kubernetes auth method.
SYNTHIGY_VAULT_JWT_PATH		File holding the JWT for that login, e.g. a Kubernetes service account token.
SYNTHIGY_VAULT_TIMEOUT_MS		Timeout of one Vault call.
SYNTHIGY_ENCRYPTION_WEBHOOK_URL		Your own key service: data keys are wrapped and unwrapped by POSTing to this URL.
SYNTHIGY_ENCRYPTION_WEBHOOK_SECRET		Shared secret sent to the key webhook.
SYNTHIGY_ENCRYPTION_WEBHOOK_TIMEOUT_MS		Timeout of one webhook call.

Client connection

Written by synthigy connect and read by synthigy exec and the SDKs. Tokens live in .env.token beside the profile.

Variable	Default	Description
SYNTHIGY_ENDPOINT		URL of the Synthigy server this profile talks to.
SYNTHIGY_CLIENT_ID		Service identity: OAuth client id (client credentials).
SYNTHIGY_CLIENT_SECRET		Service identity: OAuth client secret.
SYNTHIGY_REFRESH_TOKEN		User identity: refresh token from the browser login.
SYNTHIGY_TOKEN		Current access token, a cache refreshed on demand.
SYNTHIGY_TOKEN_EXPIRES		Expiry of that token, unix seconds.

CLI and network

Read by the synthigy CLI only.

Variable	Default	Description
SYNTHIGY_JAVA		Java binary to run the engine with instead of the JRE the CLI downloads.
SYNTHIGY_JAVA_OPTS		Extra JVM options for the engine, e.g. -Xmx2g.
HTTPS_PROXY		Proxy for outgoing HTTPS (also HTTP_PROXY, NO_PROXY). Applied to the CLI and passed to the engine's JVM.
SYNTHIGY_CA_BUNDLE		PEM file of extra certificate authorities, e.g. a corporate proxy's. Trusted by the CLI and the engine.
SYNTHIGY_TRUST_STORE		Java trust store to give the engine as is, instead of one built from SYNTHIGY_CA_BUNDLE.
SYNTHIGY_TRUST_STORE_PASSWORD		Password of that trust store.
SYNTHIGY_TLS_INSECURE		true: the CLI skips TLS certificate checks. Never in production.
SYNTHIGY_NO_UPDATE_CHECK		Any value: never check for a newer CLI.
SYNTHIGY_NO_SCHEMA_CHECK		Any value: never warn about a stale xsql/schema.json.