---
title: "Cosigner Operations"
description: "cosigner-cli reference, backups, recovery exports, updates and monitoring."
url: https://docs.fystack.io/cosigner/operations
last_updated: 2026-10-14
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.fystack.io/llms.txt
> Use it to discover all available pages before exploring further.

# 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).

```bash
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.

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

> **Note:** 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.

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

Store passphrases separately from the files.

## Updates

```bash
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.