Docs menuCloud sync

Cloud sync

Personal cloud sync lets a Pro account store an encrypted project vault in LPM.dev Registry. The account can restore the vault with LPM CLI.

lpm login
lpm env push
lpm env diff
lpm env pull

Organization vaults use a separate sharing workflow. See Organization sharing.

Personal cloud sync uses three keys:

KeyWhat it does
Device root keyStays on your computer. One device root key protects the project keys of one account.
Project keyA random key for one project. LPM.dev Registry stores it only in encrypted form.
Content keyA new random key for each push. It encrypts the environment payload.

What push does

lpm env push requires a local vault with at least one environment. Before the upload, LPM CLI does these steps:

  1. Reads every named environment from the local vault.
  2. If a cloud copy exists, downloads and decrypts it with its project key. Otherwise, creates a new project key.
  3. Creates a new content key and encrypts the complete environment payload on your computer with AES-256-GCM.
  4. Wraps the content key with the project key, and the project key with the device root key.
  5. Sends the ciphertext, the wrapped keys, and project metadata that is not secret to LPM.dev Registry.

The command asks before it replaces the cloud copy:

lpm env push

To skip the question in automation, add --yes:

lpm env push --yes

Each successful push creates a new LPM.dev Registry version, even when the values did not change. LPM CLI records the version in .lpm/env-sync.json for later conflict detection. Earlier LPM CLI versions stored it in lpm.json > vaultSync, and the next push or pull moves it.

What pull does

lpm env pull downloads the encrypted payload and checks the signature of the LPM.dev Registry response. Then it unwraps the keys and decrypts the vault on your computer.

For a personal vault, a pull replaces the local vault exactly:

  • The cloud environments replace all local environments.
  • LPM CLI removes environments that exist only on your computer.
  • LPM CLI removes keys that exist only on your computer.
  • The cloud values become the local values.

The command asks before it replaces the local vault:

lpm env pull

If a local value changes while the download runs, LPM CLI applies no cloud changes and stops. If this computer has changes that you need, run lpm env diff or export a backup before you pull.

Compare before synchronizing

lpm env diff
lpm env diff staging
lpm env diff staging production

The first form compares the local default environment with the cloud copy. The second form compares the named environment with the cloud copy. The third form compares two local environments and does not contact LPM.dev Registry. The output lists added, removed, and changed keys and counts the unchanged keys. It does not print values.

Metadata validation errors

LPM.dev Registry validates the project metadata that a push sends. If some metadata is not valid, LPM.dev Registry still stores the encrypted values and drops the invalid metadata. It keeps the last valid schema and schema configuration, and the project dashboard shows a warning banner.

LPM CLI 0.81.0 and later show an env_metadata_dropped warning after the push. Earlier versions show only the success message.

If a push reports env_metadata_dropped, follow the schema upgrade steps. These steps explain client updates, public prefixes, secret declarations, and valid environment names.

Version conflicts

Each push sends the last version that this checkout saw. LPM.dev Registry accepts the push only if the cloud vault still has that version. If the cloud vault changed since then, LPM.dev Registry rejects the push:

local project last saw v3
cloud vault is already v4
push is rejected with a version conflict

To recover from a version conflict, do these steps:

  1. Export the local changes that you need to keep.
  2. Pull the latest cloud copy.
  3. Apply your changes again.
  4. Push again.

LPM CLI also has a force overwrite for recovery. It replaces the cloud vault even when the cloud vault is newer than this checkout. It still requires the device root key. Read the LPM CLI environment reference before you use it.

What LPM.dev Registry stores

For personal sync, LPM.dev Registry stores these items:

  • The encrypted environment payload.
  • The wrapped content key.
  • The wrapped project key.
  • The project name that the dashboard shows.
  • Environment schema and configuration metadata from lpm.json.
  • The sync version, owner, and timestamps.

LPM CLI does not encrypt the project name or the schema metadata. The schema metadata can include environment names, schema rules, and key names. LPM CLI encrypts the environment values before the upload.

LPM.dev Registry signs each sync response and binds it to the request. LPM CLI checks the signature before it parses or decrypts the response.

Personal sync and other devices

LPM CLI keeps one device root key for each account on a computer. On macOS, the key is in the Keychain. On other systems, the key is in the system keyring. If the keyring is not available, LPM CLI uses a file that only your user can read.

An LPM CLI installation without that key cannot decrypt or replace an existing personal cloud vault. Signing in is not enough.

Dashboard Pairing gives a browser an encrypted copy of the device root key, so that the browser can open the vault. It does not pair a second LPM CLI installation.

Organization sharing gives access to more than one person in a different way. LPM CLI wraps the content key separately for the public key of each member.

OIDC changes the trust boundary

Normal cloud sync is end-to-end encrypted. LPM.dev Registry stores the encrypted payload, but it does not have the device root key that the decryption needs.

OIDC CI pull is an exception that you turn on for each project. For a personal Pro project, LPM CLI sends the project key of that project only. The device root key stays on your computer. For an organization project, an owner or admin sends only the current content key.

LPM.dev Registry encrypts the key before it stores it. This stored key is the CI escrow. After a workflow proves its identity and matches the policy, LPM.dev Registry does these steps:

  1. Decrypts the vault on the server.
  2. Selects the authorized environment.
  3. Returns that plaintext environment to the CI job over TLS.

Before you turn on CI escrow, read OIDC for CI.

LPM.dev Registry binds personal escrow to the server key version, the project ID, the account ID, and the project key version. It binds organization escrow to the server key version, the project ID, the organization ID, and the content key version.

LPM.dev Registry can rotate the server key. The rotation does not change the encrypted env data or its policies. OIDC pulls continue to work after the rotation.

See also