---
title: "Instalación del Cosigner"
description: "Instala cosigner-cli, verifica el runtime firmado, empareja con Fystack e inicia el cosigner."
url: https://docs.fystack.io/es/cosigner/installation
last_updated: 2026-11-13
---

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

# Instalación del Cosigner

Modo regular en Linux con Docker. El soporte para [Nitro Enclave](https://docs.fystack.io/cosigner/nitro-enclave.md) llegará pronto.

_Diagram: Instalar, verificar, emparejar, conectar_

## Requisitos previos

- **Host**: Linux `amd64` o `arm64` para producción. macOS o WSL 2 para desarrollo.
- **Docker**: Engine 20.10+ con Compose v2.
- **cosign**: v3+. El instalador lo agrega si no está presente.
- **De Fystack**: un token de emparejamiento (`cps_...`). Consulta el [Paso 1](#step-1-get-a-pairing-token).
- **Servidor de callback**: obligatorio en producción. Consulta [Approval Callback](https://docs.fystack.io/cosigner/approval-callback.md).

**Red:** sin puertos de entrada. HTTPS saliente hacia Apex, el Fystack Gateway, `ghcr.io`, tu callback y (en el perfil unattended) AWS KMS.

---

## Paso 1: obtén un token de emparejamiento

En el dashboard de Fystack, abre la pestaña **Cosigner**, haz clic en **Register Cosigner**, elige **Server** y haz clic en **Continue**.

_Diagram: Diálogo Register Cosigner con la opción Server seleccionada_

Ingresa un nombre para el cosigner. El diálogo muestra los comandos de instalación y un token de emparejamiento (`cps_...`). Copia el token: es de un solo uso, expira en 60 minutos y se muestra una sola vez.

Mantén el diálogo abierto mientras completas los pasos siguientes. Muestra **Waiting for your cosigner to connect** y se actualiza cuando el cosigner se empareja.

_Diagram: Diálogo Register Cosigner con los comandos de instalación, el token de emparejamiento y un estado de espera de conexión_

## Paso 2: instala cosigner-cli

```bash
curl -sSL https://cosigner.fystack.io/install.sh | sh
```

Comprueba el SHA-256 y la firma de Sigstore del binario y luego lo instala en `/usr/local/bin` (o `~/.local/bin`).

| Opción | Variable de entorno | Efecto |
| --- | --- | --- |
| `--version vX.Y.Z` | `COSIGNER_VERSION` | Instala una versión específica |
| `--dir DIR` | `COSIGNER_INSTALL_DIR` | Ubicación de instalación |
| `--skip-docker-check` |  | Omite las comprobaciones de Docker |

> **Note:** Para verificar el instalador antes de ejecutarlo, consulta [Verificación de la cadena de suministro](https://docs.fystack.io/cosigner/security.md#supply-chain-verification).

## Paso 3: crea el directorio de la instancia

Crea un directorio nuevo y vacío para este cosigner en la ubicación que mejor se adapte a tu host, y ejecuta los comandos restantes desde dentro de él. `cosigner-cli` guarda allí toda la configuración, los secretos y el estado de la instancia.

## Paso 4: comprueba el host

```bash
cosigner-cli doctor
```

Comprueba Docker, cosign y la configuración. Informa `unconfigured`, `configured but unpaired` o `paired`.

## Paso 5: empareja e inicia

```bash
cosigner-cli up
```

Luego, `up`:

1. **Solicita** el endpoint de Fystack. Presiona Enter para mantener el valor predeterminado.
2. **Verifica** la versión más reciente de `ghcr.io/fystack/cosigner` con cosign y fija su digest, antes de solicitar cualquier secreto.
3. **Escribe** un `config.yaml` predeterminado (perfil manual, callback desactivado).
4. **Pide** una contraseña de almacenamiento y el token de emparejamiento del Paso 1.
5. **Empareja**: genera una identidad Ed25519, la registra en Apex y guarda `state/pairing.yaml`.
6. **Inicia** el contenedor, lo desbloquea y se conecta al Gateway.

_Diagram: Salida de cosigner-cli up: imagen verificada y fijada, almacenamiento desbloqueado, emparejado con Apex, cosigner en ejecución_

La configuración predeterminada usa el perfil **`manual`**: la clave de almacenamiento se envuelve con tu contraseña, que ingresas en cada inicio, y no hay reinicio automático. Para iniciar al arrancar el sistema con AWS KMS, consulta [Perfil unattended](#unattended-profile).

## Paso 6: activa la aprobación por callback

La configuración generada tiene `require_callback: false`, por lo que se firma cualquier solicitud que envíe Fystack. Activa la aprobación antes de crear billeteras:

```bash
cosigner-cli callback add https://YOUR-CALLBACK-HOST \
  --server-public-key server-public.pem
```

Esto edita `config.yaml` en el mismo lugar, genera la clave de callback del cosigner en `secrets/`, escribe `cosigner-public.pem` y reinicia el cosigner. Copia `cosigner-public.pem` a tu servidor de callback. Consulta [Approval Callback](https://docs.fystack.io/cosigner/approval-callback.md).

Ahora la configuración se ve así:

```yaml
storage:
  backend: sqlite
  sqlite:
    path: data/cosigner.db
  encryption:
    kek:
      type: password_envelope
      config:
        path: /run/secrets/storage-kek.enc
approval:
  require_callback: true
audit:
  type: file
  config:
    path: /var/lib/cosigner/audit.jsonl
callback:
  timeout: 30s
  retry_count: 1
  url: https://YOUR-CALLBACK-HOST/cosigner/approve
  private_key:
    type: file
    config:
      path: /run/secrets/cosigner-private.der.hex
  response_public_key_path: /run/secrets/server-public.pem
```

Para ajustar otras opciones, como `timeout` o `retry_count`, edita el archivo y ejecuta `cosigner-cli restart`.

- Dentro del contenedor, `/var/lib/cosigner` es el directorio `state/` de la instancia y `/run/secrets` es su directorio `secrets/` (solo lectura).
- Mantén `storage` y `audit` tal como se generaron: `cosigner-cli` requiere SQLite en `data/cosigner.db` y registro de auditoría en archivo.

## Paso 7: verifica

```bash
cosigner-cli status
cosigner-cli info
cosigner-cli logs -f
```

Cuando `status` muestre ready, el cosigner estará en línea y podrá participar en keygen.

## Perfil unattended

La configuración predeterminada solo admite el perfil manual. Con **`unattended`**, la clave de almacenamiento se envuelve con tu clave de AWS KMS y el cosigner se inicia al arrancar el sistema. Escribe tú mismo la configuración antes del Paso 5 y guárdala fuera del directorio de la instancia (`up` la copia dentro):

```yaml
storage:
  backend: sqlite
  sqlite:
    path: data/cosigner.db
  encryption:
    kek:
      type: kms
      config:
        provider: aws
        region: YOUR-AWS-REGION
        key_id: YOUR-KMS-KEY-ARN
        ciphertext_blob_path: /run/secrets/storage-kek.kms
approval:
  require_callback: false
audit:
  type: file
  config:
    path: /var/lib/cosigner/audit.jsonl
```

Cifra una clave aleatoria de 32 bytes con tu clave de KMS y guarda el texto cifrado en base64 como `secrets/storage-kek.kms` en el directorio de la instancia. El contenedor necesita `kms:Decrypt` mediante un rol de IAM. Luego ejecuta:

```bash
cosigner-cli up \
  --profile unattended \
  --config /secure/config.yaml
```

Continúa con el [Paso 6](#step-6-turn-on-callback-approval) para activar la aprobación por callback.

## Estructura de la instancia

| Ruta | Contenido |
| --- | --- |
| `cosigner-cli.yaml` | Endpoint de Apex, digest de imagen fijado, perfil |
| `config.yaml` | Configuración de runtime (solo lectura) |
| `docker-compose.yaml` | Archivo Compose generado y reforzado |
| `secrets/` | Clave de almacenamiento envuelta y claves de callback |
| `state/pairing.yaml` | Registro de emparejamiento de Apex |
| `state/cosigner.key` | Clave de identidad Ed25519 |
| `state/data/cosigner.db` | Fragmentos de clave cifrados y estado de sesión |
| `state/audit.jsonl` | Registro de auditoría firmado |

## Ejecutar al arrancar

Solo para el perfil unattended. Adapta la unidad de systemd incluida:

```ini
[Unit]
Description=Fystack Cosigner (KMS unattended profile)
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
User=cosigner
Group=cosigner
SupplementaryGroups=docker
ExecStart=/usr/local/bin/cosigner-cli --home /var/lib/fystack-cosigner start
ExecStop=/usr/local/bin/cosigner-cli --home /var/lib/fystack-cosigner stop
TimeoutStartSec=360
TimeoutStopSec=60
UMask=0077

[Install]
WantedBy=multi-user.target
```

Para el perfil manual, pasa la contraseña mediante un descriptor de archivo:

```bash
COSIGNER_PASSWORD_FD=3 cosigner-cli start 3< /run/secrets/cosigner-pw
```

Esto es menos seguro que escribir la contraseña a mano. Consulta [Automatizar el reinicio](https://docs.fystack.io/cosigner/operations.md#automate-restart).

## Solución de problemas

| Síntoma | Solución |
| --- | --- |
| Falló la verificación de la firma de la imagen | No la omitas. Revisa la referencia de la imagen y contacta a security@fystack.io. |
| identity already registered | Restaura los datos de emparejamiento originales desde un backup en lugar de volver a emparejar. |
| Se cierra justo después de iniciar | Falló el ping de callback al iniciar. Comprueba que el callback sea accesible y que confíe en `cosigner-public.pem`. |
| AlreadyExists | Hay otra instancia conectada con esta identidad. Detenla. |
| PermissionDenied | El cosigner fue revocado. No volverá a conectarse. |
| No está listo tras el primer inicio | Está generando los preparámetros ECDSA. Espera hasta 5 minutos. |