Cosigner Operations

CLI reference, backups, updates and monitoring.

Commands

Global flags: --home (instance directory, default COSIGNER_HOME then current directory) and --docker.

Command Does Flags
up Verify, pair and start a new instance. Same as start once paired. --apex-endpoint --config --profile --image --token-file
start Start. Asks for the password in manual profile.
stop Stop, keep state. Drains sessions for up to 25s.
restart Recreate the container.
status ready, state, participant_id, active_sessions.
logs Container logs. --tail -f
doctor Check host, config and image signature.
info Public key, image, callback fingerprint.
callback add Require callback approval. --url --server-public-key --ca --no-restart
callback remove Stop requiring approval. -y --no-restart
backup Encrypted instance backup. Cosigner must be stopped. --out
restore Restore into an empty directory. --in
export Write .mshare recovery files. Manual profile, stopped. --wallet --out-dir --list
update Verify and install a newer release after a backup. --version --backup-out --dry-run
version CLI version.

Environment variables

Variable Use
COSIGNER_HOME Instance directory
COSIGNER_PASSWORD_FD Read the storage password from a file descriptor
COSIGNER_RECOVERY_PASSWORD_FD Read the backup password from a file descriptor
COSIGNER_NO_UPDATE_CHECK=1 Hide update notices

Profiles

manual unattended
Storage key Password (Argon2id) AWS KMS
Start Password every time Automatic, on boot
Docker restart no on-failure:5
.mshare export Yes No

Set at up. Cannot be changed later.

Backup and restore

backup writes one archive with config, secrets, identity, pairing record, encrypted database and audit log. It is encrypted with a separate recovery password (Argon2id + AES-256-GCM).

cosigner-cli stop
cosigner-cli backup --out /backups/cosigner-2026-10-12.cosrec
cosigner-cli start

Write it outside the instance directory. Instance data is limited to 128 MiB.

cosigner-cli --home /srv/cosigner-restored restore --in /backups/cosigner-2026-10-12.cosrec
cosigner-cli --home /srv/cosigner-restored start

Stop or revoke the old instance first. Never run two copies of the same cosigner.

Test restores on a clean host regularly.

Recovery export

export writes one .mshare per wallet, encrypted with a six-word passphrase printed once. These are the cosigner's input to Fystack Recovery, which rebuilds keys offline from a threshold of shares. One file alone cannot rebuild a key.

cosigner-cli stop
cosigner-cli export --out-dir /secure/recovery
cosigner-cli start

Store passphrases separately from the files.

Updates

cosigner-cli update --dry-run
cosigner-cli update --backup-out /backups/pre-update.cosrec
  1. Picks the newest release (or --version). No downgrades.
  2. Verifies the signature and container contract.
  3. Stops the cosigner and writes a backup.
  4. Pins the new digest and starts.

No automatic rollback. Keep the backup until the new version has signed real transactions.

Monitoring

Health: checked every 10s; stale after 15s. Alert on:

  • ready: false beyond first-boot setup.
  • state: callback_unavailable.
  • Container exit (manual profile never restarts on its own).

Audit log: state/audit.jsonl, signed and hash-chained. Events: session_start, session_end, session_abort, callback_decision, kek_use, identity_sign, backup_created, restore_performed. Ship it off-host; Docker does not rotate it.

Logs: Docker json-file, 10 MB x 5.

Decommissioning

  1. Ask Fystack to revoke the cosigner.
  2. cosigner-cli stop.
  3. Keep a final backup and exports per your retention policy, then delete the instance directory.