Configuration

Configure the io.sign Virtual Signer Broker, MPC Core, policies, and persistent storage

The Virtual Signer runs a Broker and a Multi-Party Computation (MPC) Core service. Configure each container separately. All settings start with IOSIGN_SIGNER_. Don't reuse VS_* settings from older deployments.

Use the image versions and deployment configuration supplied for your environment. The image includes default service URLs for io.finnet's environments. Set the service URLs explicitly for your own environment, so the signer doesn't connect to an 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

VariableUse
IOSIGN_SIGNER_ENVSelects the image's bundled environment configuration. Use a value supported by the supplied image.
IOSIGN_SIGNER_LOG_LEVELLog level, for example info or debug.
IOSIGN_SIGNER_MQTT_LOG_LEVELMQTT log level; default error.
IOSIGN_SIGNER_BINDING_NETWORK_NAMEListener interface, for example 0.0.0.0 inside an isolated container network.
IOSIGN_SIGNER_MQTT_URLEnvironment's MQTT URL. Must use wss://, including the correct port and path.
IOSIGN_SIGNER_MQTT_CA_CERT_FILEOptional PEM certificate-authority file for MQTT trust.

Broker identity and connectivity

VariableUse
IOSIGN_SIGNER_BROKER_PORTBroker HTTP port; deployment examples use 8182.
IOSIGN_SIGNER_BROKER_AUTH_CLIENT_IDThe client ID io.finnet support issued for this Virtual Signer. Required.
IOSIGN_SIGNER_BROKER_AUTH_CLIENT_SECRETThe matching client secret. Required. Store it as a secret.
IOSIGN_SIGNER_BROKER_ORG_IDOrganisation in which the signer registers. Required.
IOSIGN_SIGNER_BROKER_INITIAL_DEVICEDevice name for initial registration. Required. Persist the resulting identity across restarts.
IOSIGN_SIGNER_BROKER_PLATFORM_AUTH_URLAuthentication 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_URLio.sign signing-stream service URL, usually the TLS HTTP/2 endpoint on port 50051. Required.
IOSIGN_SIGNER_BROKER_SIGNING_SERVICE_CA_CERT_HEXOptional hex-encoded CA certificate for the signing service.
IOSIGN_SIGNER_BROKER_MPC_CORE_URLInternal MPC Core HTTPS URL, for example https://vs-core:8181.
IOSIGN_SIGNER_BROKER_MPC_CORE_TLS_CERT_FILEBroker client certificate for mutual TLS (mTLS). Required when TLS is enabled.
IOSIGN_SIGNER_BROKER_MPC_CORE_TLS_KEY_FILEMatching Broker private key. Required when TLS is enabled.
IOSIGN_SIGNER_BROKER_MPC_CORE_TLS_SERVER_PIN_CERT_FILEPinned MPC Core server certificate. Required when TLS is enabled.

Approval policy

Choose the policy before first registration. See Approval policies.

VariableUse
IOSIGN_SIGNER_BROKER_APPROVAL_MODEapi-approval for OPA or a custom policy server. manual-api for manual approval of every request. always-approve is for disposable development signers only. Immutable after registration.
IOSIGN_SIGNER_BROKER_APPROVAL_EXTERNAL_POLICY_BASE_URLRequired with api-approval. HTTPS base URL; the Broker appends /sign, /keygen, or /reshare. Immutable after registration.
IOSIGN_SIGNER_BROKER_APPROVAL_EXTERNAL_POLICY_TIMEOUTPer-attempt timeout in seconds. Set a finite positive value such as 5 for production. Don't use 0 in production: it turns the timeout off, so a stalled policy call can delay retries and rejection.
IOSIGN_SIGNER_BROKER_APPROVAL_SLEEP_DURATIONPositive interval in seconds used by the approval loop. The supplied production configuration uses 5.
IOSIGN_SIGNER_BROKER_APPROVAL_POLICY_CA_CERT_FILEOptional PEM CA certificate added to policy-service trust.
IOSIGN_SIGNER_BROKER_APPROVAL_TLS_CLIENT_CERT_FILEOptional mTLS client certificate; configure with the client key.
IOSIGN_SIGNER_BROKER_APPROVAL_TLS_CLIENT_KEY_FILEOptional mTLS private key; configure with the client certificate.
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_ENABLEDtrue turns on manual approval for requests the policy defers, with api-approval. Default false. Can be changed after registration.
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_PORTPort of the manual approval API. Required with manual approval; must differ from the Broker and metrics ports.
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_TLS_CERT_FILEPEM server certificate of the manual approval API, with an ML-DSA-65 or ML-DSA-87 key. Required with manual approval.
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_TLS_KEY_FILEPEM private key of that certificate. Required with manual approval.
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_CLIENT_CA_CERT_FILEPEM CA certificates, with ML-DSA keys, that issue your approver systems' ML-DSA client certificates. Required with manual approval.
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_APPROVER_KEYS_DIRDirectory of approver public keys, one <key_id>.pem per key, ML-DSA-65 or ML-DSA-87. Required with manual approval. Any other file stops the Broker from starting.
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_DECISION_MAX_AGESeconds a signed decision is accepted after its issued_at, 1 to 3600. Default 300.
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_DECISION_TIMEOUTSeconds an approve or reject may take before the API answers 504, 1 to 300. Default 30.
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_MIN_REMAININGSeconds that must be left before a request expires for an approve to be accepted, 0 to 3600. Default 300.
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_NOTIFICATION_URLOptional HTTPS URL that receives a webhook when a request becomes pending. Uses the policy-service TLS settings above.

Storage and disaster recovery

VariableUse
IOSIGN_SIGNER_BROKER_STORAGE_BASE_PATHPersistent local state directory. Default /var/vsigner; preserve it across container replacement.
IOSIGN_SIGNER_BROKER_STORAGE_BUCKET_URLOptional cloud storage URL, such as s3://bucket-name?region=eu-west-1 or azblob://container-name. When unset, the Broker uses filesystem storage. Supply the cloud identity and permissions required by your deployment.
IOSIGN_SIGNER_BROKER_DR_PK_PEM_FILERequired 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_PATHDestination for the recovery bundles that signerctl share backup writes. 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

VariableUse
IOSIGN_SIGNER_CORE_PORTInternal MPC Core RPC port; deployment examples use 8181.
IOSIGN_SIGNER_CORE_TLS_CERT_FILECore server certificate. Required when TLS is enabled.
IOSIGN_SIGNER_CORE_TLS_KEY_FILEMatching Core server private key. Required when TLS is enabled.
IOSIGN_SIGNER_CORE_TLS_CLIENT_PIN_CERT_FILEPinned Broker client certificate. Required when TLS is enabled.
IOSIGN_SIGNER_CORE_SKR_AKV_URLAzure Key Vault HTTPS URL for Secure Key Release (SKR).
IOSIGN_SIGNER_CORE_SKR_MAA_URLMicrosoft Azure Attestation HTTPS URL.
IOSIGN_SIGNER_CORE_SKR_KEY_IDKey identifier in Azure Key Vault. Set with both URLs to enable SKR.
IOSIGN_SIGNER_CORE_SKR_URLSKR sidecar endpoint; default http://localhost:8080. Use the reachable sidecar hostname when it runs in another container.
IOSIGN_SIGNER_CORE_SKR_ACCESS_TOKENOptional sidecar bearer token when managed identity is unavailable. Secret.
IOSIGN_SIGNER_CORE_ENCRYPTION_KEYDirect 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, 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

VariableDefaultUse
IOSIGN_SIGNER_BROKER_PROMETHEUS_PORT2113Broker metrics listener.
IOSIGN_SIGNER_CORE_PROMETHEUS_PORT2112Core metrics listener.
IOSIGN_SIGNER_CORE_HEALTH_PORT2114Core health HTTP listener, separate from the TLS RPC port.
IOSIGN_SIGNER_BROKER_HEALTH_TIMEOUT2Broker probe timeout in seconds.
IOSIGN_SIGNER_CORE_HEALTH_TIMEOUT2Core probe timeout in seconds.
IOSIGN_SIGNER_BROKER_HEALTH_CACHE_TTL5Broker probe cache in seconds; 0 disables caching, maximum 30.
IOSIGN_SIGNER_CORE_HEALTH_CACHE_TTL5Core probe cache in seconds; 0 disables caching, maximum 30.
IOSIGN_SIGNER_TRACING_ENABLEDtrueBroker tracing switch.
OTEL_EXPORTER_OTLP_ENDPOINTUnsetOpenTelemetry 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 production deployments, including the Deploy self-hosted example. 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.


Did this page help you?