update odysseusbackupgit pull

Update Odysseus Safely

Backup data/, pull the curated branch, then rebuild. Unofficial guide — always verify commands against the official GitHub repo.

30-second checklist

Copy data/ (and .env if you use one)
git checkout main → git pull
Docker: docker compose up -d --build; Mac: ./start-macos.sh; Windows: re-run launch-windows.ps1

Official tip: clone -b main for the curated branch. Bare git clone defaults to dev (newest, less stable).

1. Backup data/ (required)

Conversations, documents, settings, and auth live here. Updating without a backup is the most common way to lose work.

terminal

# From your odysseus project folder — back up BEFORE updating.

# Copy the whole data directory (chats, settings, auth, uploads):
# Mac / Linux:
cp -a data data-backup-$(date +%Y%m%d)

# Windows PowerShell:
Copy-Item -Recurse data "data-backup-$(Get-Date -Format yyyyMMdd)"

# Optional: also keep .env (never commit secrets)
Copy-Item .env ".env.backup"

2. Docker update

terminal

# 1. Backup data/ first (see above)

# 2. Stay on the curated branch if you installed with -b main:
git fetch origin
git checkout main
git pull origin main

# 3. Rebuild and recreate containers:
docker compose down
docker compose up -d --build

# 4. Confirm healthy + find password only if you reset auth:
docker compose ps
docker compose logs --tail=80 odysseus

Using an NVIDIA GPU overlay? Keep your COMPOSE_FILE line in .env — see Docker install.

3. Native Windows update

terminal

# Native Windows (launch-windows.ps1 path)

# 1. Backup data\ folder
# 2. In PowerShell inside the repo:
git fetch origin
git checkout main
git pull origin main

# 3. Re-run the launcher (safe to re-run — recreates venv/deps as needed):
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

# Open http://localhost:7000

4. Native macOS update

terminal

# Native macOS (start-macos.sh path)

# 1. Backup data/ folder
# 2. In Terminal inside the repo:
git fetch origin
git checkout main
git pull origin main

# 3. Re-run the official script:
./start-macos.sh

# Open http://127.0.0.1:7860

Stuck on unstable dev?

Bare git clone defaults to dev. Switch to main for fewer surprises.

terminal

# If you cloned bare (default = unstable dev) and want curated main:

git fetch origin
git checkout main
git pull origin main

# Then rebuild (Docker) or re-run your launcher / start-macos.sh

Restore a backup

Stop Odysseus (Docker down, or close the native process)
Rename current data/ aside (e.g. data-broken)
Copy your data-backup-* folder back to data/
Start Odysseus again and verify login + chats

First-week checklist

Troubleshooting

Security checklist

FAQ

Common questions