# Deploy a cold bridge

Use this page when deploying cold vault operations. The cold bridge is required only for cold storage deployments.

## What the cold bridge does

The cold bridge runs on the air-gapped workstation and provides:

- A local UI for cold vault operations.
- A local API for uploading, decoding, and downloading operation payloads.
- Optional payload encryption and decryption for `.dat` files.
- A local endpoint that the vault component polls for signing work.


The cold bridge is stateless and uses in-memory storage for workloads. It does not require a database or persistent volume.

For workstation requirements, see [Cold vault workstation planning](/products/custody/v1.36/deployment/planning/cold-vault-workstation).

## Deployment flow


```mermaid
flowchart TD
    Plan["Plan air-gapped workstation"]
    Install["Install cold bridge and vault stack"]
    Configure["Configure cold bridge and vault"]
    Register["Register cold vault"]
    Handshake["Complete first-time handshake"]
    Test["Test export, sign, import"]

    Plan --> Install --> Configure --> Register --> Handshake --> Test
```

## Step 1: Prepare the air-gapped workstation

Before installing the cold bridge:

1. Build the workstation according to [Cold vault workstation planning](/products/custody/v1.36/deployment/planning/cold-vault-workstation).
2. Verify that network connectivity is disabled.
3. Install the hardened operating system from verified media.
4. Install KMS or HSM drivers, if applicable.
5. Prepare approved transfer media for moving `.dat` files.


## Step 2: Install cold bridge and vault components

Transfer the cold bridge software, vault stack components, and configuration files to the air-gapped workstation using approved physical media.

Install the components using the deployment method agreed for your environment. The cold bridge and vault are deployed together so the vault can poll the local cold bridge endpoint for signing work.

## Step 3: Configure payload encryption, if used

If your deployment enables cold bridge payload encryption, configure the same passphrase on:

- The cold bridge.
- The online system configuration used to process cold bridge payloads.


If the passphrase differs between the air-gapped workstation and the online system, operation payloads cannot be decrypted.

## Step 4: Verify the cold bridge

After startup, call the status endpoint from the air-gapped workstation:


```sh
curl -X GET "{ColdBridgeURL}/v1/feed/status"
```

Expected response shape:


```json
{
  "accountToSign": 0,
  "accountSigned": 0,
  "transactionToSign": 0,
  "transactionSigned": 0,
  "manifestToSign": 0,
  "manifestSigned": 0
}
```

## Step 5: Register the cold vault

Register the cold vault with the standard vault registration process:

- [Register a vault in the UI](/products/custody/v1.36/identity-and-access/vault-management/manage-vaults#register-a-vault-in-the-ui)
- [Register a vault with the API](/products/custody/v1.36/identity-and-access/vault-management/manage-vaults#register-a-vault-with-the-api)


After registration, the vault can appear as `Pending` because the cold vault cannot automatically connect to the online deployment.

## Step 6: Complete the vault handshake

Complete the manual handshake by transferring the initial vault payload from the cold bridge to the online system:

1. On the air-gapped workstation, download the payload from the cold bridge.
2. Transfer the `.dat` file to the online environment.
3. Import the `.dat` file into Ripple Custody.
4. Verify that the vault status is `Completed`.


For exact UI and API steps, see:

- [Complete the first-time vault handshake in the UI](/products/custody/v1.36/identity-and-access/vault-management/cold-vault-setup-ui#complete-the-first-time-vault-handshake)
- [Complete the first-time vault handshake with the API](/products/custody/v1.36/identity-and-access/vault-management/cold-vault-setup-api#complete-the-first-time-vault-handshake)


## Step 7: Test cold vault operations

Before using the cold vault for production operations:

1. Create a test account using the cold vault.
2. Export pending operations from the online environment.
3. Transfer the `.dat` file to the air-gapped workstation.
4. Upload the file to the cold bridge.
5. Confirm that the operation appears in the signing queue.
6. Download the signed `.dat` file.
7. Transfer the signed file back to the online environment.
8. Import the signed operations and verify the result.


## Cold bridge API reference

| Endpoint | Method | Purpose |
|  --- | --- | --- |
| `/v1/feed/status` | `GET` | Get signing status counters. |
| `/v1/feed/upload` | `POST` | Upload operations to be signed. |
| `/v1/feed/download` | `GET` | Download signed operations or handshake payloads. |
| `/v1/feed/decode` | `POST` | Decode a payload for inspection before signing. |


For day-to-day operation steps, see [Process cold vault operations with the API](/products/custody/v1.36/identity-and-access/vault-management/cold-vault-setup-api).