> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Vault

> Encrypted off-machine storage and cross-machine resume for agent conversations

# Session Vault

Session Vault saves your agents' conversations, encrypted, into a git remote you own, and
lets another machine pick a conversation up where it left off. Overdeck never sees the
contents: everything is encrypted on your machine with a key only you hold, and
`pan vault` commands send no telemetry.

It also works without the dashboard: `npm install -g @overdeck/core`, then `pan vault` on any
machine.

## Set up the first machine

1. Create an empty private repository anywhere you trust (GitHub, GitLab, a NAS, your own
   server). Overdeck never provides or defaults a backend.

2. Run:

   ```bash theme={null}
   pan vault setup git@github.com:you/session-vault.git
   ```

3. Write down the 24-word recovery phrase it prints. It is shown only once.

<Warning>
  The recovery phrase is the vault key. Anyone with these words can read your vault. Losing every device and these words loses the vault: there is no recovery on any server.
</Warning>

Add `--hooks` to register a Claude Code `Stop` hook that saves after every turn:

```bash theme={null}
pan vault setup git@github.com:you/session-vault.git --hooks
```

## Join from a second machine

```bash theme={null}
pan vault join git@github.com:you/session-vault.git
```

Enter the 24 words when prompted (or pass `--phrase-file <path>`). A wrong phrase prints
`The recovery phrase does not match this vault.` and writes nothing.

## Save and sync

```bash theme={null}
pan vault save --all              # every transcript on this machine
pan vault save <session-id>       # one conversation
pan vault sync                    # push what grew, pull what others saved
pan vault status                  # backend, this machine, last sync, machines
```

If a new line contains something that looks like a credential, the save is blocked and the
output names the line number and pattern, never the value. Rotate the secret if it is real,
then run `pan vault allow-secret <id> <line>` or `pan vault exclude --session <id>`.

## Continue on another machine

```bash theme={null}
pan vault list                    # what is saved, and which machine owns each conversation
pan vault show <id>               # read it first
pan vault resume <id>             # take it over here and launch the harness
pan vault resume <id>@3           # fork at version 3 instead
```

`resume` compares the target directory's git state with the state saved with the
conversation. If the branch, commit or dirty state differs, it asks whether to continue,
continue with a short note as the first message, or cancel. Use `--on-drift continue|note|cancel`
in scripts and `--no-launch` to print the command instead of running it.

Claude Code and Codex resume natively. Other harnesses receive a markdown digest of the
conversation in the target directory to paste into a new session.

## Exclude what should never leave the machine

```bash theme={null}
pan vault exclude /work/client-x                       # everything under a path
pan vault exclude --origin git@github.com:acme/private.git
pan vault exclude --session <id>                       # one conversation; its saved copy becomes a tombstone
pan vault include /work/client-x                       # undo
```

## Free local disk space (optional)

Transcripts can grow to tens of gigabytes. Eviction is off by default and never deletes
anything on its own. To use it:

1. Set `"evict": true` in `~/.overdeck/vault/config.json`.
2. Run `pan vault evict`. It lists every transcript whose contents are fully in the vault
   and verified by reading them back, with a fingerprint of that list. Nothing is deleted.
3. Run `pan vault evict --confirm <fingerprint>` to delete exactly those files. Anything that
   changed since the review is skipped, and a changed list is refused with a new fingerprint.
4. `pan vault restore <id>` rebuilds any evicted transcript byte for byte.

`pan vault evict --decline <id>` keeps a transcript out of future lists; `--clear` empties the
list without deleting anything.

## Where things live

| Path | Contents |
| - | - |
| `~/.overdeck/vault/key` | Your vault key (mode 0600). Back it up as the recovery phrase. |
| `~/.overdeck/vault/config.json` | Backend URL, exclusions, `evict`, `liveQuietMinutes`. |
| `~/.overdeck/vault/git/` | Local clone of your vault remote. |
| `~/.overdeck/vault/index.json` | This machine's saved-transcript index and list cache. Never uploaded. |

The developer reference, including the wire format and the module map, is
[docs/SESSION-VAULT.md](https://github.com/eltmon/overdeck/blob/main/docs/SESSION-VAULT.md).