---
title: Post-Restore Credential Wizard
---

# Post-Restore Credential Wizard

## What it is

After a Backup Mirror **replace-mode restore** on a different machine, Omniscio auto-detects that some saved credentials can no longer be decrypted and walks you through re-entering them.

When you restore an Omniscio backup onto a new computer, the OS-level encryption key (DPAPI on Windows, Keychain on macOS) changes. Every credential that was encrypted with the old machine's key — API keys, OAuth tokens, MCP server secrets — decrypts to an empty string. The Post-Restore Credential Wizard automatically opens after a restore, shows which credentials are broken, and links you to the right settings screen to fix each one.

## Where to find it

The wizard opens by itself: after a restore that brought credentials over from another machine,
Omniscio detects it at startup and raises the wizard modal. You can also run the credential health
check at any time — not just after a restore:

- **Settings → Backup & Restore → "Run credential check…"** opens the same wizard

## How it behaves

### How it works

1. **Detection**: When Omniscio starts after a restore, the startup sequence detects the consumed restore flag. If the restore came from a different machine (hostname mismatch), it sets `postRestoreWizardPending = true`. Same-machine restores skip the wizard since DPAPI keys survive.
2. **Auto-open**: The `PostRestoreWizardGate` component watches that flag and opens the wizard modal automatically.
3. **Health report**: The wizard probes fourteen categories (returning both healthy and broken items for each):
   - **Omniscio Accounts** — login and API key accounts that failed to decrypt
   - **Provider API Keys** — AI provider keys (OpenAI, Gemini, Groq, DeepSeek, etc.), including each saved GLM (z.ai) multi-account key (those live in a database table, not `config.json`, so they're checked separately)
   - **MCP Server Secrets** — encrypted environment variables and headers for MCP servers
   - **Integration Tokens** — third-party service tokens (Slack, Jira, Ollert, Linear, Notion, etc.)
   - **Google Authentication** — OAuth refresh/ID/access tokens for Google integration
   - **Automation Credentials** — encrypted credentials used by automation rules
   - **Cron Job Secrets** — encrypted environment variables in active cron jobs
   - **Backup Passphrases** — setup backup and mirror backup passphrases
   - **CLI Authentication** — checks `gh`, `gcloud`, `gws`, `gog` auth status (skips tools not installed)
   - **SSH Remotes** — verifies each remote's SSH identity/key file exists on disk, plus the app-managed `known_hosts` host-key pins (a warning when they're missing: your remotes still connect, but the first reconnect re-records each host key instead of verifying it, so confirm the server identity that first time)
   - **Environment** — checks worktree drive path and Claude Code config files (~/.claude/)
   - **Toolchain** — reports tools that are not installed or errored via the toolchain installer
   - **Cloud Infrastructure** — asks the platform vault whether the `gcp-test-runner` GCP service-account key is present (a DPAPI file on Windows, a Keychain item on macOS — never a hardcoded path). Shows healthy when present, broken with a re-mint remedy when absent, and nothing at all when it cannot tell.
   - **Database Encryption** — if the database is encrypted, warns when the OS-keyring key did not survive the move to this machine, so the recovery code is now the only way to open it (the one credential whose loss is irreversible data loss, unlike the re-enterable categories above)
4. **Collapsible sections**: Each category shows as a collapsible section with an "N of M healthy" counter. Categories with broken items expand by default; all-healthy categories collapse.
5. **Fix action buttons**: Each broken item has context-specific action buttons:
   - **Go to Accounts/Settings** — navigates to the relevant settings section
   - **Copy** — copies a CLI command to the clipboard
   - **Open Terminal** — copies the command AND launches a visible terminal window
   - A remedy you must edit before it will run gets **Copy only, no Open Terminal** — `gog auth add <email>` needs your own address substituted, so there is nothing to launch. A button that cannot work is not offered.
   - If a launch is refused or fails, the wizard now says so instead of doing nothing.
6. **Per-item re-check**: After you re-enter a credential, click **Re-check** next to that item. The wizard re-probes just that credential and updates it in-place.
7. **Dismiss**: When all credentials are fixed (or you choose to fix them later), dismiss the wizard. A **confirmation dialog** warns you if broken items remain. The wizard won't reappear until the next restore.

### Inbox integration

When broken credentials are detected after a restore, an inbox alert is raised:

> "X credentials need re-entry after restore"

The alert links to the credential wizard in Settings → Backup & Restore. It deduplicates (only one active alert at a time) and follows standard inbox affordances (snooze, archive, dismiss).

### Secrets Omniscio issues itself

Not everything that becomes unreadable is something you re-enter. Three of the encrypted values
are **machine-issued**: the Real Chrome Bridge pairing token, the CLI control token, and the VAPID
push private key. Your computer was not the only holder of those — a paired browser extension holds
the first, every script and agent holding the CLI token has the second, and every subscribed phone
has the third.

Those three are **kept, never replaced**. If the keyring cannot unlock one, Omniscio leaves the
stored value exactly as it is and the feature that depends on it waits:

| Unreadable secret | What you notice | What fixes it |
| --- | --- | --- |
| Real Chrome Bridge pairing token | My Real Chrome stops connecting — the bridge refuses every connection rather than accepting one it cannot verify | Fix the machine-level keyring, then restart Omniscio. **No re-pairing is needed** — the extension's existing token works again. |
| CLI control token | Agents and external scripts fail to authenticate | Same — and the `~/.amc/cli-token` file is never overwritten with a blank. |
| VAPID push private key | Push notifications stop arriving | Same — and **no device has to re-subscribe**. |

The alternative (generate a fresh secret) would quietly erase the original and force you to re-pair
the extension or re-subscribe every phone to recover from a fault that was temporary. If you would
rather rotate than wait, Settings → CLI Control's Regenerate button still does that deliberately.

When this happens an inbox alert names the affected feature, so an outage is never silent — these
three fields are deliberately outside the fourteen wizard categories above, since there is nothing
for you to re-enter and the wizard's "fix it" actions do not apply.

## For agents

### CLI access

An AI agent can check credential health via the CLI control server:

```
GET /post-restore/health
```

Returns a health report with `accounts`, `providerKeys`, `mcpServers`, `integrationTokens`, `googleAuth`, `automationCredentials`, `cronEnv`, `backupPassphrases`, `cliAuth`, `sshRemotes`, `environment`, `cliTools`, `cloudInfrastructure`, and `dbEncryption` arrays — all **fourteen** categories, each containing entries with `id`, `label`, `status`, `detail`, and `fixAction`. Do not omit `dbEncryption`: it is the Database Encryption category described in §3, the one credential whose loss is irreversible data loss.

### Where things live (for agents with repo access)

- **CLI auth probes**: `src/main/services/post-restore/cli-auth-checks.ts`
- **Environment probes**: `src/main/services/post-restore/environment-checks.ts`
- **Health probe service**: `src/main/services/post-restore/credential-health-service.ts`
- **IPC handlers**: `src/main/ipc/post-restore-handlers.ts`
- **CLI route**: `src/main/services/cli/cli-server-post-restore-routes.ts`
- **Inbox alert**: `src/main/services/post-restore/post-restore-inbox-alert.ts`
- **Wizard UI**: `src/renderer/src/features/post-restore/PostRestoreWizard.tsx`
- **Gate component**: `src/renderer/src/features/post-restore/PostRestoreWizardGate.tsx`
- **Types**: `src/shared/types/post-restore.ts`
- **Settings flag**: `postRestoreWizardPending` in `backupsSettingsSchema`
- **UI anchor**: `settings-data-transfer-post-restore-check`
- **Contract**: `.claude/memory/contracts/post-restore-wizard-contract.md`

## Related

[Backup Mirror](backup-mirror.md) is the backup and restore system that creates the condition this wizard addresses. [Machine Migration](machine-migration.md) is the full migration guide, including the re-authentication checklist a move to a new computer implies. And [Is my data encrypted?](is-my-data-encrypted.md) explains what Omniscio encrypts at rest, which is why the credentials above cannot be decrypted on a new machine.