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
| 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 | The client ID io.finnet support issued for this Virtual Signer. Required. |
IOSIGN_SIGNER_BROKER_AUTH_CLIENT_SECRET | The matching client secret. Required. Store it 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. 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_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. 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_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. |
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_ENABLED | true 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_PORT | Port 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_FILE | PEM 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_FILE | PEM private key of that certificate. Required with manual approval. |
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_CLIENT_CA_CERT_FILE | PEM 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_DIR | Directory 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_AGE | Seconds a signed decision is accepted after its issued_at, 1 to 3600. Default 300. |
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_DECISION_TIMEOUT | Seconds an approve or reject may take before the API answers 504, 1 to 300. Default 30. |
IOSIGN_SIGNER_BROKER_APPROVAL_MANUAL_API_MIN_REMAINING | Seconds 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_URL | Optional HTTPS URL that receives a webhook when a request becomes pending. Uses the policy-service TLS settings above. |
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, the Broker uses filesystem storage. 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 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
| 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, 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 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.
Updated 9 days ago