Skip to main content

Cosigner Deployment

Prerequisites​

  • A server meeting the infrastructure requirements
  • Docker and Docker Compose installed
  • Network access to the Carabaas API (outbound)
  • Network access from unseal key holders (inbound, port 3443)
  • TLS certificates for the cosigner's HTTPS interface

Step 1: Set Up Your Server​

Server Requirements​

RequirementMinimumRecommended
vCPU2 vCPU4 vCPU
RAM4 GB8 GB
StorageEncrypted EBS volumeEncrypted, no delete on termination
SoftwareDocker, Docker ComposeDocker, Docker Compose

For production, use an EC2 instance type that supports Nitro Enclaves (e.g., m5.xlarge, c5.xlarge, or newer).

Network Security​

Restrict server access to selected hosts only:

SourcePortPurpose
Administrator22SSH server administration
Unseal key holders3443HTTPS management interface
Carabaas API (outbound)443Coordinator WebSocket + TLS

We recommend the organization to own and control access to the cloud account where the cosigner is deployed.

Step 2: Deploy the Cosigner​

Docker Deployment (Standard)​

Start the cosigner using Docker Compose:

docker-compose up -d

AWS Nitro Enclave Deployment (Production)​

For production environments, deploy the cosigner with AWS Nitro Enclave for hardware isolation:

1. Enable Nitro Enclaves on your EC2 instance:

Ensure the instance is launched with enclave support enabled (--enclave-options 'Enabled=true').

2. Build and run the enclave:

nitro-cli run-enclave \
  --eif-path mpc-cosigner.eif \
  --cpu-count 2 \
  --memory 2048 \
  --enclave-cid 16

3. Start the parent application:

docker-compose -f docker-compose.enclave.yml up -d

The parent process communicates with the enclave over VSOCK — it never sees plaintext secrets.

Step 3: Configure Environment​

Environment Variables​

VariableDefaultDescription
COORDINATOR_URL—WebSocket URL of the Carabaas Coordinator
CUSTODY_URL—Custody platform API URL
TENANT_ID—Your tenant identifier
HTTPS_PORT3443HTTPS port for the cosigner API
DATA_DIR./dataDirectory for persistent state
CERTS_DIR—Directory for TLS certificates
NITRO_ENCLAVEfalseEnable Nitro Enclave mode

TLS Certificates​

The cosigner API runs on HTTPS. Place your TLS certificates in the directory specified by CERTS_DIR:

certs/
├── server.key    # TLS private key
└── server.crt    # TLS certificate (CA-signed for production)

For production, use CA-signed certificates. Self-signed certificates can be used for development.

Step 4: Initialize the Cosigner​

Open the cosigner's management interface at https://COSIGNER_HOST:3443/ and complete the initialization process.

:::warning Critical — Backup Setup Artifacts During initialization, the cosigner generates 3 unseal key pairs and encrypted mnemonic shares. These artifacts are the only way to restore your wallets.

  • Distribute unseal keys to designated key holders
  • Securely store encrypted share files as backup
  • There is no other recovery path if these artifacts are lost :::

Unseal Key Distribution​

Each unseal key holder receives:

  1. A password — a 32-character random string shown once during setup
  2. An encrypted share file — download and securely store as backup

Key holders should:

  • Store the password in a password manager (KeePassXC, 1Password, etc.)
  • Store the encrypted share file separately as backup
  • Never share credentials with other key holders

Step 5: Connect to Your Organization​

  1. Create a Signer client in your organization via the Console or API
  2. Get the invite code for the signer client
  3. Input the invite code on the last page of the initialization process, or use the API:
curl -k https://COSIGNER_HOST:3443/acceptInvite/INVITE_CODE

You should see Connected to coordinator in the cosigner logs. The cosigner is now ready to participate in vault creation and signing.

Health Check​

Verify the cosigner is running:

curl -k https://COSIGNER_HOST:3443/status

The response indicates the current state: sealed, unsealing, ready, or disconnected.

Monitoring​

The cosigner exposes a status HTTP endpoint that reports:

  • Current state (sealed / unsealing / disconnected / ready)
  • Connection status to the Coordinator
  • Active signing operations
tip

Monitor the cosigner's status endpoint and alert on state changes. The cosigner must be in ready state for vault creation and transaction signing.

See Also​