Configuration

The Virtual Signer runs a Broker and a Multi-Party Computation (MPC) Core service. Configure each container separately. The launch configuration uses IOSIGN_SIGNER_* names; do not copy legacy VS_* runtime settings into a new deployment.

Use the image versions and deployment configuration supplied for your environment. Some defaults come from the image's environment configuration file rather than the environment-variable loader. Explicitly override service URLs for customer-operated environments so the signer does not connect to a bundled io.finnet environment by mistake.

Inject credentials and private keys through your deployment's secret-management mechanism. File paths below are paths inside the container; mount the corresponding files read-only. A .env file supplies Compose substitutions, but a variable reaches a container only through environment or env_file.

Shared settings

Variable	Use
`IOSIGN_SIGNER_ENV`	Selects the image's bundled environment configuration. Use a value supported by the supplied image.
`IOSIGN_SIGNER_LOG_LEVEL`	Log level, for example `info` or `debug`.
`IOSIGN_SIGNER_MQTT_LOG_LEVEL`	MQTT log level; default `error`.
`IOSIGN_SIGNER_BINDING_NETWORK_NAME`	Listener interface, for example `0.0.0.0` inside an isolated container network.
`IOSIGN_SIGNER_MQTT_URL`	Environment's MQTT URL. Must use `wss://`, including the correct port and path.
`IOSIGN_SIGNER_MQTT_CA_CERT_FILE`	Optional PEM certificate-authority file for MQTT trust.

Broker identity and connectivity

Variable	Use
`IOSIGN_SIGNER_BROKER_PORT`	Broker HTTP port; deployment examples use `8182`.
`IOSIGN_SIGNER_BROKER_AUTH_CLIENT_ID`	Machine-client ID issued for this environment. Required.
`IOSIGN_SIGNER_BROKER_AUTH_CLIENT_SECRET`	Matching machine-client secret. Required; store as a secret.
`IOSIGN_SIGNER_BROKER_ORG_ID`	Organisation in which the signer registers. Required.
`IOSIGN_SIGNER_BROKER_INITIAL_DEVICE`	Device name for initial registration. Required. Persist the resulting identity across restarts.
`IOSIGN_SIGNER_BROKER_PLATFORM_AUTH_URL`	Authentication URL template supplied by your administrator. Must include literal `:auth_method`; it is not the identity provider's arbitrary token URL.
`IOSIGN_SIGNER_BROKER_SIGNING_SERVICE_URL`	io.sign signing-stream service URL, usually the TLS HTTP/2 endpoint on port `50051`. Required.
`IOSIGN_SIGNER_BROKER_SIGNING_SERVICE_CA_CERT_HEX`	Optional hex-encoded CA certificate for the signing service.
`IOSIGN_SIGNER_BROKER_MPC_CORE_URL`	Internal MPC Core HTTPS URL, for example `https://vs-core:8181`.
`IOSIGN_SIGNER_BROKER_MPC_CORE_TLS_CERT_FILE`	Broker client certificate for mutual TLS (mTLS). Required when TLS is enabled.
`IOSIGN_SIGNER_BROKER_MPC_CORE_TLS_KEY_FILE`	Matching Broker private key. Required when TLS is enabled.
`IOSIGN_SIGNER_BROKER_MPC_CORE_TLS_SERVER_PIN_CERT_FILE`	Pinned MPC Core server certificate. Required when TLS is enabled.

Approval policy

Choose the policy before first registration. See Approval policies.

Variable	Use
`IOSIGN_SIGNER_BROKER_APPROVAL_MODE`	`api-approval` for OPA or a custom policy server. `always-approve` is for disposable development signers only. Immutable after registration.
`IOSIGN_SIGNER_BROKER_APPROVAL_EXTERNAL_POLICY_BASE_URL`	Required with `api-approval`. HTTPS base URL; the Broker appends `/sign`, `/keygen`, or `/reshare`. Immutable after registration.
`IOSIGN_SIGNER_BROKER_APPROVAL_EXTERNAL_POLICY_TIMEOUT`	Per-attempt timeout in seconds. Set a finite positive value such as `5` for production. The implementation accepts `0`, which disables the Broker per-attempt context deadline; do not use `0` in production because a stalled policy call can delay retries and rejection.
`IOSIGN_SIGNER_BROKER_APPROVAL_SLEEP_DURATION`	Positive interval in seconds used by the approval loop. The supplied production configuration uses `5`.
`IOSIGN_SIGNER_BROKER_APPROVAL_POLICY_CA_CERT_FILE`	Optional PEM CA certificate added to policy-service trust.
`IOSIGN_SIGNER_BROKER_APPROVAL_TLS_CLIENT_CERT_FILE`	Optional mTLS client certificate; configure with the client key.
`IOSIGN_SIGNER_BROKER_APPROVAL_TLS_CLIENT_KEY_FILE`	Optional mTLS private key; configure with the client certificate.

Storage and disaster recovery

Variable	Use
`IOSIGN_SIGNER_BROKER_STORAGE_BASE_PATH`	Persistent local state directory. Default `/var/vsigner`; preserve it across container replacement.
`IOSIGN_SIGNER_BROKER_STORAGE_BUCKET_URL`	Optional cloud storage URL, such as `s3://bucket-name?region=eu-west-1` or `azblob://container-name`. When unset, filesystem storage is used. Supply the cloud identity and permissions required by your deployment.
`IOSIGN_SIGNER_BROKER_DR_PK_PEM_FILE`	Required ML-KEM-768 public key PEM file for disaster recovery. Immutable after registration. Never mount the corresponding private key on the signer.
`IOSIGN_SIGNER_BROKER_BACKUP_BASE_PATH`	Destination for `signerctl share backup` bundle ZIPs. Used by that command, not the Broker runtime. Mount a persistent backup directory.

The Broker seals the approval mode, policy base URL, recovery public-key contents, and whether its MPC Core channel is secure. Changing a sealed value causes IMMUTABLE_CONFIG_MISMATCH. Decide these values before registration. Do not delete state or weaken the channel to bypass this error; follow an approved signer replacement procedure.

A volume backup and an offline disaster recovery bundle serve different purposes. Follow Virtual Signer disaster recovery after key generation and each reshare.

MPC Core and encryption

Variable	Use
`IOSIGN_SIGNER_CORE_PORT`	Internal MPC Core RPC port; deployment examples use `8181`.
`IOSIGN_SIGNER_CORE_TLS_CERT_FILE`	Core server certificate. Required when TLS is enabled.
`IOSIGN_SIGNER_CORE_TLS_KEY_FILE`	Matching Core server private key. Required when TLS is enabled.
`IOSIGN_SIGNER_CORE_TLS_CLIENT_PIN_CERT_FILE`	Pinned Broker client certificate. Required when TLS is enabled.
`IOSIGN_SIGNER_CORE_SKR_AKV_URL`	Azure Key Vault HTTPS URL for Secure Key Release (SKR).
`IOSIGN_SIGNER_CORE_SKR_MAA_URL`	Microsoft Azure Attestation HTTPS URL.
`IOSIGN_SIGNER_CORE_SKR_KEY_ID`	Key identifier in Azure Key Vault. Set with both URLs to enable SKR.
`IOSIGN_SIGNER_CORE_SKR_URL`	SKR sidecar endpoint; default `http://localhost:8080`. Use the reachable sidecar hostname when it runs in another container.
`IOSIGN_SIGNER_CORE_SKR_ACCESS_TOKEN`	Optional sidecar bearer token when managed identity is unavailable. Secret.
`IOSIGN_SIGNER_CORE_ENCRYPTION_KEY`	Direct encryption-key fallback: a 32-byte key encoded as hex or base64. Secret. Prefer the hardware-attested key-management integration for production.

When SKR is fully configured it takes precedence over the direct key. Configure one deliberate key-management path and retain the recovery access it requires. Without SKR or a direct key, the current Core refuses to start outside simulated development mode. This setting does not replace the host's confidential-computing requirements or encrypted storage controls.

Health and monitoring

Variable	Default	Use
`IOSIGN_SIGNER_BROKER_PROMETHEUS_PORT`	`2113`	Broker metrics listener.
`IOSIGN_SIGNER_CORE_PROMETHEUS_PORT`	`2112`	Core metrics listener.
`IOSIGN_SIGNER_CORE_HEALTH_PORT`	`2114`	Core health HTTP listener, separate from the TLS RPC port.
`IOSIGN_SIGNER_BROKER_HEALTH_TIMEOUT`	`2`	Broker probe timeout in seconds.
`IOSIGN_SIGNER_CORE_HEALTH_TIMEOUT`	`2`	Core probe timeout in seconds.
`IOSIGN_SIGNER_BROKER_HEALTH_CACHE_TTL`	`5`	Broker probe cache in seconds; `0` disables caching, maximum `30`.
`IOSIGN_SIGNER_CORE_HEALTH_CACHE_TTL`	`5`	Core probe cache in seconds; `0` disables caching, maximum `30`.
`IOSIGN_SIGNER_TRACING_ENABLED`	`true`	Broker tracing switch.
`OTEL_EXPORTER_OTLP_ENDPOINT`	Unset	OpenTelemetry collector endpoint; export requires an endpoint.

Keep health and metrics listeners on the management network. Use Testing the deployment to distinguish process health from a successful signing ceremony.

Development-only switches

IOSIGN_SIGNER_CORE_ONLY_DEV_RISKY_FALLBACK_SIMULATED_CRYPTOGRAPHY=true enables simulated cryptography for development hardware. Never use it for production keys.

IOSIGN_SIGNER_CORE_INSECURE_DISABLE_TLS=true and IOSIGN_SIGNER_BROKER_INSECURE_MPC_CORE_HTTP=true opt into an unencrypted Broker–Core channel. Leave both unset or false for the deployment below. A private network alone does not configure mTLS.

Continue to Deploy self-hosted for an example that keeps the RPC listener private and uses explicit certificate mounts.