Environment Variables

Configuration environment variables use the SYNAPS3_ prefix and map underscores to config paths. They override file values and are a good place for deployment secrets and host-specific settings.

Common Overrides

Environment variable	Config path
SYNAPS3_SERVER_PORT	server.port
SYNAPS3_SERVER_MAX_CONNECTIONS	server.max_connections
SYNAPS3_SERVER_MAX_REQUESTS	server.max_requests
SYNAPS3_SERVER_TLS_ENABLED	server.tls.enabled
SYNAPS3_SERVER_TLS_CERT_FILE	server.tls.cert_file
SYNAPS3_SERVER_TLS_KEY_FILE	server.tls.key_file
SYNAPS3_S3_REGION	s3.region
SYNAPS3_FILECOIN_NETWORK	filecoin.network
SYNAPS3_FILECOIN_RPC_URL	filecoin.rpc_url
SYNAPS3_FILECOIN_PRIVATE_KEY	filecoin.private_key
SYNAPS3_FILECOIN_WITH_CDN	filecoin.with_cdn
SYNAPS3_FILECOIN_ALLOW_PRIVATE_NETWORKS	filecoin.allow_private_networks
SYNAPS3_FILECOIN_DEFAULT_COPIES	filecoin.default_copies
SYNAPS3_FILECOIN_OBSERVABILITY_INTERVAL	filecoin.observability.interval
SYNAPS3_FILECOIN_OBSERVABILITY_TIMEOUT	filecoin.observability.timeout
SYNAPS3_FILECOIN_OBSERVABILITY_CONCURRENCY	filecoin.observability.concurrency
SYNAPS3_DATABASE_DRIVER	database.driver
SYNAPS3_DATABASE_DSN	database.dsn
SYNAPS3_DATABASE_MAX_OPEN_CONNS	database.max_open_conns
SYNAPS3_DATABASE_MAX_IDLE_CONNS	database.max_idle_conns
SYNAPS3_CACHE_DIR	cache.dir
SYNAPS3_CACHE_MAX_SIZE_GB	cache.max_size_gb
SYNAPS3_CACHE_EVICTION_POLICY	cache.eviction_policy
SYNAPS3_WORKER_UPLOAD_CONCURRENCY	worker.upload.concurrency
SYNAPS3_WORKER_UPLOAD_POLL_INTERVAL	worker.upload.poll_interval
SYNAPS3_WORKER_UPLOAD_MAX_RETRIES	worker.upload.max_retries
SYNAPS3_WORKER_EVICTOR_CONCURRENCY	worker.evictor.concurrency
SYNAPS3_WORKER_EVICTOR_POLL_INTERVAL	worker.evictor.poll_interval
SYNAPS3_WORKER_EVICTOR_MAX_RETRIES	worker.evictor.max_retries
SYNAPS3_WORKER_STORAGE_CLEANUP_CONCURRENCY	worker.storage_cleanup.concurrency
SYNAPS3_WORKER_STORAGE_CLEANUP_POLL_INTERVAL	worker.storage_cleanup.poll_interval
SYNAPS3_WORKER_STORAGE_CLEANUP_MAX_RETRIES	worker.storage_cleanup.max_retries
SYNAPS3_LOGGING_LEVEL	logging.level
SYNAPS3_LOGGING_FORMAT	logging.format
SYNAPS3_LOGGING_S3_ACCESS_ENABLED	logging.s3_access.enabled
SYNAPS3_LOGGING_S3_ACCESS_LEVEL	logging.s3_access.level
SYNAPS3_ADMIN_ADDR	admin.addr
SYNAPS3_ADMIN_TRUSTED_PROXIES	admin.trusted_proxies
SYNAPS3_ADMIN_AUTH_ENABLED	admin.auth.enabled
SYNAPS3_ADMIN_AUTH_USERNAME	admin.auth.username
SYNAPS3_ADMIN_AUTH_SESSION_SECRET	admin.auth.session_secret
SYNAPS3_ADMIN_AUTH_SESSION_TTL	admin.auth.session_ttl

SYNAPS3_ADMIN_TRUSTED_PROXIES is a comma-separated list of IP or CIDR entries.

Advanced Generated Fields

Environment variable	Config path
SYNAPS3_ADMIN_AUTH_PASSWORD_HASH	admin.auth.password_hash

admin.auth.password_hash is normally generated by synaps3 init or synaps3 admin-auth reset-password. Do not hand-write it unless an external password-hash process owns Admin auth.

CLI and Container Path Variables

These variables do not map to TOML config fields.

Environment variable	Purpose
SYNAPS3_DATA_DIR	Runtime data directory used for automatic synaps3 init; defaults to /var/lib/synaps3.
SYNAPS3_CONFIG	Config file used by CLI commands when --config is not set; the Compose example defaults it to /var/lib/synaps3/config.toml and allows override, and the entrypoint uses $SYNAPS3_DATA_DIR/config.toml when starting serve.
SYNAPS3_ADMIN_PASSWORD	Admin password used only by CLI authentication. Prefer the no-echo terminal prompt or a protected secret source instead of placing it in shell history.

When to Use Environment Variables

Use environment variables for:

• wallet private keys and database DSNs,
• externally managed Admin session secrets,
• container-only paths,
• network-specific RPC URLs,
• deployment-specific logging format,
• temporary overrides during troubleshooting.

Use the TOML config file for stable settings that should survive process restarts and be visible in synaps3 admin settings get. Use SYNAPS3_DATA_DIR only for Docker entrypoint path control; use SYNAPS3_CONFIG when container-local commands should share the same config file.

Security Guidance

WARNING

Keep wallet private keys, database credentials, Admin passwords, and Admin session secrets out of git, container images, and shell history.

• Keep SYNAPS3_FILECOIN_PRIVATE_KEY in a secret manager, .env, or host environment. synaps3 init and synaps3 admin-auth reset-password generate admin.auth.session_secret; use SYNAPS3_ADMIN_AUTH_SESSION_SECRET only when deployment policy manages it outside TOML.
• Treat SYNAPS3_DATABASE_DSN, SYNAPS3_ADMIN_PASSWORD, and SYNAPS3_ADMIN_AUTH_SESSION_SECRET as sensitive values. Use the CLI no-echo prompt for the Admin password whenever practical.
• Keep .env, config.toml, and credential files at permission mode 0600.
• Keep SYNAPS3_ADMIN_TRUSTED_PROXIES empty unless trusted proxies strip untrusted forwarded headers before requests reach SynapS3.
• Do not commit .env, config.toml, local databases, cache data, or wallet material.
• Keep filecoin.allow_private_networks = false unless private provider URLs are explicitly trusted.
• Remember that environment-managed fields override file values; changing the file will not affect them until the environment changes.

Verify Effective Settings

synaps3 admin settings get

The output shows current values and whether settings writes are available.

After changing settings, restart SynapS3, check /healthz, and run this command again to confirm the effective values. Environment variables continue to override file values.