# Havre Silo reference client

This is the technical-pilot client for Silo.havre.cloud. It seals private files on
your device, sends only ciphertext to Havre, and decrypts downloads locally. The
server does not receive your private key.

This bundle includes the command-line reference client and a small desktop
companion. The companion is a transparent Python/Tk shell around the same
trusted client; it does not duplicate encryption or key storage and is not a
signed native installer. Silo checkout is still closed while pricing, account
email, recovery, renewal, and restore evidence are completed. Do not use it for
personal files until Havre invites you to a pilot.

## Install

Use Python 3.11 or newer in the extracted bundle. The bundle includes launchers that create
an isolated `.venv` beside the client and install only the two cryptographic dependency families.

Windows PowerShell:

```text
Set-ExecutionPolicy -Scope Process Bypass
.\run-silo.ps1 --selftest
.\run-silo-desktop.ps1 --selftest
```

macOS or Linux:

```text
./run-silo.sh --selftest
./run-silo-desktop.sh --selftest
```

If you prefer to manage the environment yourself, the equivalent commands are:

```text
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe havre_remote.py --selftest
```

macOS or Linux:

```text
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python havre_remote.py --selftest
```

To open the desktop companion after the smoke test:

```text
.\run-silo-desktop.ps1
./run-silo-desktop.sh
```

The companion needs the Python Tk support shipped with most Windows and macOS
Python distributions. Some Linux distributions package it separately. If Tk
is unavailable, the reference CLI remains the supported fallback.

The smoke test creates temporary local state and verifies the encryption round trip.
It does not contact Havre.

## First Silo pilot flow

1. Create and verify your Havre account in the browser. The Silo account path
   requires email verification and a recovery-capable account before sync.
2. Log in with the client after Havre enables your pilot:

   ```text
   python havre_remote.py login you@example.com
   ```

3. Check the package and server-side gates:

   ```text
   python havre_remote.py silo-catalog
   python havre_remote.py silo-status
   python havre_remote.py silo-device register --name "This computer"
   python havre_remote.py silo-doctor --root ./My-Silo --json
   ```

4. After the doctor is green, sync a selected folder:

   ```text
   python havre_remote.py silo-sync ./My-Silo
   python havre_remote.py silo-watch ./My-Silo --interval-seconds 30
   ```

   To save local space, retain only selected remote folders on this device:

   ```text
   python havre_remote.py silo-sync ./My-Silo --include-prefix Documents --include-prefix Photos/2026
   python havre_remote.py silo-watch ./My-Silo --include-prefix Documents --include-prefix Photos/2026
   ```

   The selection is saved with that local sync root. A later `silo-pull` or `silo-watch`
   reuses it until you pass new prefixes or `--include-all`. Unselected changes still
   advance the tenant-wide cursor without downloading bytes. When you add a prefix, the
   client bootstraps its current metadata and then resumes the ordered feed, so selection
   expansion does not lose files. Narrowing removes only unchanged tracked local copies;
   edited copies are preserved with a visible suffix and remote files are never deleted.

   A tracked local deletion is propagated as a recoverable Silo tombstone only
   after the client confirms there is no newer remote change for that path. The
   foreground watcher retries temporary sync failures with bounded exponential
   backoff; the default is five attempts starting at 15 seconds, and it stops
   visibly after the retry budget is exhausted. A rename is currently a safe
   delete plus a new upload. The desktop companion exposes the same setup check,
   device registration, one-shot sync, and foreground watcher as buttons. It also
   opens the canonical recovery-create or recovery-import command in a separate
   terminal. Enter the recovery password only there; the companion never receives
   it. The companion must remain open while the watcher is running; it is not an
   operating-system background service.

The client stores its local identity and session under `HAVRE_HOME` or
`~/.havre`. Keep that directory private. A recovery bundle is password-wrapped
locally; Havre does not receive the recovery password or private key.

## Bundle contents

- `havre_remote.py`: HTTPS client, local key handling, device commands, doctor, and sync.
- `envelope.py`: client-side sealed-object encryption and integrity checks.
- `sealed_object.py`: the pure-standard-library sealed-object contract validator.
- `requirements.txt`: the two cryptographic runtime dependencies.
- `silo_desktop.py`: a thin Tk desktop companion that delegates every operation
  to `havre_remote.py`.
- `run-silo.ps1`: Windows PowerShell launcher.
- `run-silo.sh`: macOS/Linux launcher.
- `run-silo-desktop.ps1`: Windows PowerShell desktop launcher.
- `run-silo-desktop.sh`: macOS/Linux desktop launcher.
- `SHA256SUMS`: checksums for the downloaded files.