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:
| Key | What it does |
|---|---|
| Device root key | Stays on your computer. One device root key protects the project keys of one account. |
| Project key | A random key for one project. LPM.dev Registry stores it only in encrypted form. |
| Content key | A 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:
- Reads every named environment from the local vault.
- If a cloud copy exists, downloads and decrypts it with its project key. Otherwise, creates a new project key.
- Creates a new content key and encrypts the complete environment payload on your computer with AES-256-GCM.
- Wraps the content key with the project key, and the project key with the device root key.
- 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:
- Export the local changes that you need to keep.
- Pull the latest cloud copy.
- Apply your changes again.
- 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:
- Decrypts the vault on the server.
- Selects the authorized environment.
- 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
- Local secrets explains how to manage the local vault.
- Per-environment scoping explains the full environment map that syncs.
- Dashboard Pairing explains how to open synced vaults in a browser.
- Organization sharing explains how LPM CLI wraps access separately for each organization member.
- The LPM CLI vault architecture page explains the encryption formats and implementation details.