Node Environment Variables

This is the consolidated reference for node environment variables used by node-core.

Prefix Configuration

The default environment variable prefix is TWIN_, so variables look like TWIN_PORT and TWIN_ENTITY_STORAGE_CONNECTOR_TYPE.

The prefix is configurable for custom node implementations:

Set envPrefix in node options when calling run(...).
Or pass the CLI option --env-prefix <PREFIX>.

When you change the prefix, all variables in this document use your custom prefix instead of TWIN_.

Core Runtime Variables

Variable	Possible Values	Default	Notes
`TWIN_DEBUG`	`true`, `false`	`false`	Enables engine debug mode.
`TWIN_SILENT`	`true`, `false`	`false`	Suppresses console output.
`TWIN_STORAGE_FILE_ROOT`	File system path	None	Root directory for file-based state and storage.
`TWIN_STATE_FILENAME`	File name or path	`engine-state.json` (when storage root is set)	State file used by node state storage.
`TWIN_NODE_IDENTITY_ENABLED`	`true`, `false`	`true`	Enables node context identity flow.
`TWIN_TENANT_ENABLED`	`true`, `false`	`false`	Enables tenant-scoped flow.
`TWIN_EXTENSIONS`	Comma-separated module list	None	Extension modules to load. Supports local, `npm:`, and `https:` entries.

Connector and Component Selection Variables

Variable	Possible Values	Default	Notes
`TWIN_ENTITY_STORAGE_CONNECTOR_TYPE`	`file`, `memory`, `aws-dynamodb`, `azure-cosmosdb`, `gcp-firestoredb`, `scylladb`, `mysql`, `mongodb`, `postgresql`	None	Comma-separated list allowed.
`TWIN_ENTITY_STORAGE_CONNECTOR_DEFAULT`	Any configured entity storage type	First configured type	Default entity storage connector.
`TWIN_BLOB_STORAGE_CONNECTOR_TYPE`	`memory`, `file`, `ipfs`, `aws-s3`, `azure-storage`, `gcp-storage`	None	Comma-separated list allowed.
`TWIN_BLOB_STORAGE_CONNECTOR_DEFAULT`	Any configured blob storage type	First configured type	Default blob storage connector.
`TWIN_BLOB_STORAGE_CONNECTOR_PUBLIC`	Any configured blob storage type	None	Marks the public blob connector feature.
`TWIN_VAULT_CONNECTOR`	`entity-storage`, `hashicorp`	None	Selects vault backend.
`TWIN_LOGGING_CONNECTOR`	`console`, `entity-storage`	None	Comma-separated list allowed.
`TWIN_EVENT_BUS_CONNECTOR`	`local`	None	Selects event bus connector.
`TWIN_EVENT_BUS_COMPONENT`	`service`	None	Selects event bus component implementation.
`TWIN_MESSAGING_EMAIL_CONNECTOR`	`entity-storage`, `aws`	None	Messaging email connector type.
`TWIN_MESSAGING_SMS_CONNECTOR`	`entity-storage`, `aws`	None	Messaging SMS connector type.
`TWIN_MESSAGING_PUSH_NOTIFICATION_CONNECTOR`	`entity-storage`, `aws`	None	Messaging push connector type.
`TWIN_TELEMETRY_CONNECTOR`	`entity-storage`	None	Telemetry connector type.
`TWIN_FAUCET_CONNECTOR`	`entity-storage`, `iota`	None	Faucet connector type.
`TWIN_WALLET_CONNECTOR`	`entity-storage`, `iota`	None	Wallet connector type.
`TWIN_NFT_CONNECTOR`	`entity-storage`, `iota`	None	NFT connector type.
`TWIN_IDENTITY_CONNECTOR`	`entity-storage`, `iota`	None	Identity connector type.
`TWIN_IDENTITY_RESOLVER_CONNECTOR`	`entity-storage`, `iota`	None	Identity resolver connector type.
`TWIN_IDENTITY_PROFILE_CONNECTOR`	`entity-storage`	None	Identity profile connector type.
`TWIN_VERIFIABLE_STORAGE_CONNECTOR`	`entity-storage`, `iota`	None	Verifiable storage connector type.
`TWIN_ATTESTATION_CONNECTOR`	`entity-storage`, `iota`	None	Attestation connector type.
`TWIN_DATA_CONVERTER_CONNECTORS`	`json`, `xml`	None	Comma-separated list allowed.
`TWIN_DATA_EXTRACTOR_CONNECTORS`	`json-path`	None	Comma-separated list allowed.

Feature Toggle and Behaviour Variables

Variable	Possible Values	Default	Notes
`TWIN_MESSAGING_ENABLED`	`true`, `false`	`false`	Enables messaging components.
`TWIN_DATA_PROCESSING_ENABLED`	`true`, `false`	`false`	Enables data processing.
`TWIN_AUDITABLE_ITEM_GRAPH_ENABLED`	`true`, `false`	`false`	Enables auditable item graph.
`TWIN_AUDITABLE_ITEM_STREAM_ENABLED`	`true`, `false`	`false`	Enables auditable item stream.
`TWIN_DOCUMENT_MANAGEMENT_ENABLED`	`true`, `false`	`false`	Enables document management.
`TWIN_SYNCHRONISED_STORAGE_ENABLED`	`true`, `false`	`false`	Enables synchronised storage.
`TWIN_FEDERATED_CATALOGUE_ENABLED`	`true`, `false`	`false`	Enables federated catalogue.
`TWIN_TRUST_ENABLED`	`true`, `false`	`false`	Enables trust features.
`TWIN_RIGHTS_MANAGEMENT_ENABLED`	`true`, `false`	`false`	Enables rights management.
`TWIN_BACKGROUND_TASKS_ENABLED`	`true`, `false`	`false`	Enables background tasks.
`TWIN_TASK_SCHEDULER_ENABLED`	`true`, `false`	`false`	Enables task scheduler.
`TWIN_DATASPACE_ENABLED`	`true`, `false`	`false`	Enables dataspace features.
`TWIN_BLOB_STORAGE_ENABLE_ENCRYPTION`	`true`, `false`	`false`	Enables blob encryption in blob storage component flow.
`TWIN_IDENTITY_WALLET_ADDRESS_INDEX`	Integer	`0`	Wallet address index used by identity workflows.
`TWIN_TRUST_JWT_TTL_SECONDS`	Integer seconds	None	Leave unset for non-expiring JWT generation.
`TWIN_SYNCHRONISED_STORAGE_ENTITY_UPDATE_INTERVAL_MINUTES`	Integer minutes	`5`	Polling interval for synchronised updates.
`TWIN_SYNCHRONISED_STORAGE_CONSOLIDATION_INTERVAL_MINUTES`	Integer minutes	`60`	Trusted-node consolidation interval.
`TWIN_SYNCHRONISED_STORAGE_CONSOLIDATION_BATCH_SIZE`	Integer	`1000`	Trusted-node consolidation batch size.
`TWIN_SYNCHRONISED_STORAGE_MAX_CONSOLIDATIONS`	Integer	`5`	Number of consolidations retained.
`TWIN_DATASPACE_RETAIN_ACTIVITY_LOGS_FOR`	Integer minutes, `-1`	`10`	Dataspace activity retention period.
`TWIN_DATASPACE_ACTIVITY_LOGS_CLEAN_UP_INTERVAL`	Integer minutes	`60`	Dataspace clean-up interval.

Server and API Variables

Variable	Possible Values	Default	Notes
`TWIN_PORT`	Integer	`3000` (web server fallback)	API server port.
`TWIN_HOST`	Host name or IP	`localhost` (web server fallback)	API server host.
`TWIN_PUBLIC_ORIGIN`	URL	None	Public API origin, for example `https://api.example.com:443`.
`TWIN_CORS_ORIGINS`	Comma-separated origins	`*` (if not set by runtime config)	CORS allow list.
`TWIN_HTTP_METHODS`	Comma-separated HTTP methods	`GET,POST,PUT,DELETE,OPTIONS`	CORS methods.
`TWIN_HTTP_ALLOWED_HEADERS`	Comma-separated headers	Runtime dependent	CORS allowed headers.
`TWIN_HTTP_EXPOSED_HEADERS`	Comma-separated headers	Runtime dependent	CORS exposed headers.
`TWIN_AUTH_ADMIN_PROCESSOR_TYPE`	`entity-storage`	None	Authentication admin processor type.
`TWIN_AUTH_PROCESSOR_TYPE`	`entity-storage`	None	Authentication processor type.
`TWIN_AUTH_SIGNING_KEY_ID`	Vault key identifier	`auth-signing`	Key used for auth signing operations.
`TWIN_MIME_TYPE_PROCESSORS`	Comma-separated processor types	None	Additional MIME processor registrations.
`TWIN_ROUTE_LOGGING_INCLUDE_BODY`	`true`, `false`	Uses debug value	Includes body in route logging.
`TWIN_ROUTE_LOGGING_FULL_BASE64`	`true`, `false`	`false`	Includes full base64 payloads in route logging.
`TWIN_ROUTE_LOGGING_OBFUSCATE_PROPERTIES`	Comma-separated property names	None	Properties to obfuscate in route logs.

Extension Module Loading Variables

Variable	Possible Values	Default	Notes
`TWIN_EXTENSIONS_MAX_SIZE_MB`	Integer MB	`10`	Maximum HTTPS extension download size.
`TWIN_EXTENSIONS_CLEAR_CACHE`	`true`, `false`	`false`	Clears extension cache on startup.
`TWIN_EXTENSIONS_CACHE_DIRECTORY`	Relative or absolute path	`.tmp`	Root cache directory for extension modules.
`TWIN_EXTENSIONS_CACHE_TTL_HOURS`	Integer hours	`24`	HTTPS extension cache TTL.
`TWIN_EXTENSIONS_FORCE_REFRESH`	`true`, `false`	`false`	Forces extension cache refresh.

Provider and Backend Variables

Variable	Possible Values	Default	Notes
`TWIN_ENTITY_STORAGE_TABLE_PREFIX`	String	None	Prefix for entity-storage tables.
`TWIN_BLOB_STORAGE_PREFIX`	String	None	Prefix for blob paths/keys.
`TWIN_BLOB_STORAGE_ENCRYPTION_KEY_ID`	Vault key identifier	`blob-encryption`	Blob encryption key identifier.
`TWIN_VAULT_PREFIX`	String	None	Prefix prepended to vault entries.
`TWIN_HASHICORP_VAULT_TOKEN`	Token string	None	HashiCorp Vault token.
`TWIN_HASHICORP_VAULT_ENDPOINT`	URL	None	HashiCorp Vault endpoint.
`TWIN_AWS_DYNAMODB_AUTH_MODE`	`credentials`, `pod`	None	DynamoDB auth mode.
`TWIN_AWS_DYNAMODB_ACCESS_KEY_ID`	String	None	DynamoDB access key id.
`TWIN_AWS_DYNAMODB_SECRET_ACCESS_KEY`	String	None	DynamoDB secret key.
`TWIN_AWS_DYNAMODB_REGION`	Region string	None	DynamoDB region.
`TWIN_AWS_DYNAMODB_ENDPOINT`	URL	None	DynamoDB endpoint.
`TWIN_AWS_DYNAMODB_CONNECTION_TIMEOUT_MS`	Integer ms	None	DynamoDB timeout.
`TWIN_AZURE_COSMOSDB_ENDPOINT`	URL	None	Cosmos DB endpoint.
`TWIN_AZURE_COSMOSDB_KEY`	String	None	Cosmos DB key.
`TWIN_AZURE_COSMOSDB_DATABASE_ID`	String	None	Cosmos DB database id.
`TWIN_AZURE_COSMOSDB_CONTAINER_ID`	String	None	Cosmos DB container id.
`TWIN_GCP_FIRESTORE_PROJECT_ID`	String	None	Firestore project id.
`TWIN_GCP_FIRESTORE_CREDENTIALS`	String or `@json:` file expansion	None	Firestore credentials.
`TWIN_GCP_FIRESTORE_DATABASE_ID`	String	None	Firestore database id.
`TWIN_GCP_FIRESTORE_COLLECTION_NAME`	String	None	Firestore collection name.
`TWIN_GCP_FIRESTORE_API_ENDPOINT`	URL	None	Firestore API endpoint.
`TWIN_SCYLLADB_HOSTS`	Comma-separated hosts	None	Scylla hosts list.
`TWIN_SCYLLADB_LOCAL_DATA_CENTER`	String	None	Scylla local data centre.
`TWIN_SCYLLADB_KEYSPACE`	String	None	Scylla keyspace.
`TWIN_SCYLLADB_PORT`	Integer	None	Scylla port.
`TWIN_MY_SQL_HOST`	String	None	MySQL host.
`TWIN_MY_SQL_PORT`	Integer	None	MySQL port.
`TWIN_MY_SQL_USER`	String	None	MySQL user.
`TWIN_MY_SQL_PASSWORD`	String	None	MySQL password.
`TWIN_MY_SQL_DATABASE`	String	None	MySQL database.
`TWIN_MONGO_DB_HOST`	String	None	MongoDB host.
`TWIN_MONGO_DB_PORT`	Integer	None	MongoDB port.
`TWIN_MONGO_DB_USER`	String	None	MongoDB user.
`TWIN_MONGO_DB_PASSWORD`	String	None	MongoDB password.
`TWIN_MONGO_DB_DATABASE`	String	None	MongoDB database.
`TWIN_POSTGRE_SQL_HOST`	String	None	PostgreSQL host.
`TWIN_POSTGRE_SQL_PORT`	Integer	None	PostgreSQL port.
`TWIN_POSTGRE_SQL_USER`	String	None	PostgreSQL user.
`TWIN_POSTGRE_SQL_PASSWORD`	String	None	PostgreSQL password.
`TWIN_POSTGRE_SQL_DATABASE`	String	None	PostgreSQL database.
`TWIN_IPFS_API_URL`	URL	None	IPFS API URL.
`TWIN_IPFS_BEARER_TOKEN`	String	None	IPFS bearer token.
`TWIN_AWS_S3_AUTH_MODE`	`credentials`, `pod`	`credentials`	AWS S3 auth mode.
`TWIN_AWS_S3_ACCESS_KEY_ID`	String	None	AWS S3 access key id.
`TWIN_AWS_S3_SECRET_ACCESS_KEY`	String	None	AWS S3 secret key.
`TWIN_AWS_S3_REGION`	Region string	None	AWS S3 region.
`TWIN_AWS_S3_BUCKET_NAME`	String	None	AWS S3 bucket name.
`TWIN_AWS_S3_ENDPOINT`	URL	None	AWS S3 endpoint.
`TWIN_AZURE_STORAGE_ACCOUNT_NAME`	String	None	Azure Storage account name.
`TWIN_AZURE_STORAGE_ACCOUNT_KEY`	String	None	Azure Storage account key.
`TWIN_AZURE_STORAGE_CONTAINER_NAME`	String	None	Azure Storage container name.
`TWIN_AZURE_STORAGE_ENDPOINT`	URL	None	Azure Storage endpoint.
`TWIN_GCP_STORAGE_PROJECT_ID`	String	None	GCP Storage project id.
`TWIN_GCP_STORAGE_CREDENTIALS`	String or `@json:` file expansion	None	GCP Storage credentials.
`TWIN_GCP_STORAGE_BUCKET_NAME`	String	None	GCP Storage bucket name.
`TWIN_GCP_STORAGE_ENDPOINT`	URL	None	GCP Storage endpoint.
`TWIN_AWS_SES_AUTH_MODE`	`credentials`, `pod`	`credentials`	AWS SES auth mode.
`TWIN_AWS_SES_ACCESS_KEY_ID`	String	None	AWS SES access key id.
`TWIN_AWS_SES_SECRET_ACCESS_KEY`	String	None	AWS SES secret key.
`TWIN_AWS_SES_REGION`	Region string	None	AWS SES region.
`TWIN_AWS_SES_ENDPOINT`	URL	None	AWS SES endpoint.
`TWIN_AWS_MESSAGING_PUSH_NOTIFICATION_APPLICATIONS`	JSON string or `@json:` file expansion	None	Push notification application definitions.
`TWIN_IOTA_NODE_ENDPOINT`	URL	None	IOTA node endpoint.
`TWIN_IOTA_FAUCET_ENDPOINT`	URL	None	IOTA faucet endpoint.
`TWIN_IOTA_NETWORK`	Network name	None	IOTA network identifier.
`TWIN_IOTA_COIN_TYPE`	Integer	None	IOTA coin type.
`TWIN_IOTA_EXPLORER_ENDPOINT`	URL	None	IOTA explorer endpoint.
`TWIN_IOTA_GAS_STATION_ENDPOINT`	URL	None	IOTA gas station endpoint.
`TWIN_IOTA_GAS_STATION_AUTH_TOKEN`	String	None	IOTA gas station auth token.
`TWIN_UNIVERSAL_RESOLVER_ENDPOINT`	URL	None	Universal resolver endpoint.
`TWIN_ATTESTATION_VERIFICATION_METHOD_ID`	Method id string	`attestation-assertion`	Default injected by node defaults.
`TWIN_IMMUTABLE_PROOF_VERIFICATION_METHOD_ID`	Method id string	`immutable-proof-assertion`	Default injected by node defaults.
`TWIN_TRUST_VERIFICATION_METHOD_ID`	Method id string	`trust-assertion`	Default injected by node defaults.
`TWIN_DATASPACE_DATA_PLANE_PATH`	Path	None	Dataspace PULL transfer path (path only).
`TWIN_FEDERATED_CATALOGUE_FILTERS`	Comma-separated filters	None	Federated catalogue filters.
`TWIN_TRUST_GENERATORS`	Comma-separated generator types	None	Trust generator registrations.
`TWIN_TRUST_VERIFIERS`	Comma-separated verifier types	None	Trust verifier registrations.
`TWIN_RIGHTS_MANAGEMENT_CALLBACK_PATH`	Path	None	Callback path used by rights management.
`TWIN_RIGHTS_MANAGEMENT_POLICY_INFORMATION_SOURCES`	Comma-separated types	None	Rights policy information source registrations.
`TWIN_RIGHTS_MANAGEMENT_POLICY_NEGOTIATORS`	Comma-separated types	None	Rights policy negotiator registrations.
`TWIN_RIGHTS_MANAGEMENT_POLICY_REQUESTERS`	Comma-separated types	None	Rights policy requester registrations.
`TWIN_RIGHTS_MANAGEMENT_POLICY_EXECUTION_ACTIONS`	Comma-separated types	None	Rights policy execution action registrations.
`TWIN_RIGHTS_MANAGEMENT_POLICY_ENFORCEMENT_PROCESSORS`	Comma-separated types	None	Rights policy enforcement processor registrations.
`TWIN_RIGHTS_MANAGEMENT_POLICY_ARBITERS`	Comma-separated types	None	Rights policy arbiter registrations.
`TWIN_RIGHTS_MANAGEMENT_POLICY_OBLIGATION_ENFORCERS`	Comma-separated types	None	Rights policy obligation enforcer registrations.
`TWIN_SYNCHRONISED_STORAGE_TRUSTED_URL`	URL	None	Trusted synchronised storage node URL.
`TWIN_SYNCHRONISED_STORAGE_VERIFIABLE_STORAGE_KEY_ID`	String	None	Key id for synchronised verifiable storage pointers.
`TWIN_SYNCHRONISED_STORAGE_BLOB_STORAGE_ENCRYPTION_KEY_ID`	Vault key identifier	`synchronised-storage-blob-encryption`	Encryption key id for synchronised blobs.
`TWIN_SYNCHRONISED_STORAGE_BLOB_STORAGE_KEY`	Base64 key value	None	Symmetric key used for synchronised blob encryption.

Prefix Configuration​

Core Runtime Variables​

Connector and Component Selection Variables​

Feature Toggle and Behaviour Variables​

Server and API Variables​

Extension Module Loading Variables​

Provider and Backend Variables​