Updating

Moving an existing install to a newer version happens in place - no fresh setup. Your secrets (.env.local), your config (agents.config.json), your data (~/.maven, the Obsidian vault), your CLI logins (claude / codex / hermes / …) and the local engines (~/wm-engine, ~/openseo) stay exactly where they are. Only the app source is swapped.

The in-app updater

When a newer version is available an update banner appears. It shows the version and what changed. The version is the authority: the banner only offers an update when the remote version is genuinely newer, so it never offers a downgrade.

Click Update. M.A.V.E.N pulls the announced commit, installs dependencies with npm ci --ignore-scripts, builds, and restarts. Progress shows in an overlay; when it finishes the page reloads onto the new version. A build that fails rolls back to the previous working build.

Scheduled checks run twice a day - 09:00 and 21:00 local time by default, both hours configurable in Settings → Updates. A check only surfaces the banner. Automatic updates are off by default; when enabled, an update applies at most once per UTC day and only when the remote version is newer.

For a private repository the updater needs a token with read access in .env.local: it reads GITHUB_MAVEN_UPDATE first, then GITHUB_TOKEN, then GH_TOKEN. The token is handed to git through GIT_CONFIG_*, never on the command line, so it cannot leak into logs.

Manual node scripts/self-update.mjs needs a preceding Check now (or --expect-sha= / --allow-unverified) - the updater only applies the exact commit it announced.

Zip installs

An install without a git repository cannot pull; it updates by unpacking the new zip, and the banner says so. The procedure, from your install folder:

# 1) Stop the running app - pick the line for YOUR OS.
systemctl --user stop maven                                        # Linux (systemd)
# launchctl unload -w ~/Library/LaunchAgents/com.maven.app.plist   # macOS (launchd)
# Stop-ScheduledTask -TaskName MAVEN                               # Windows (PowerShell)
#   … no autostart? just stop your `npm run dev` / `npm start` process.

# 2) Back up your secrets.
cd ~/maven && cp .env.local ~/maven-env-$(date +%Y%m%d).bak 2>/dev/null || true

# 3) Swap in the new source. --delete removes files REMOVED in the new version
#    (renamed apps); the --exclude list protects your local-only files.
unzip -oq ~/maven-<VERSION>.zip -d /tmp/maven-new
rsync -a --delete \
  --exclude='.env.local' --exclude='.env.*' --exclude='agents.config.json' \
  --exclude='node_modules' --exclude='.next' --exclude='.git' \
  --exclude='.claude' --exclude='generated' --exclude='*.tsbuildinfo' \
  /tmp/maven-new/maven-<VERSION>/ ~/maven/
rm -rf /tmp/maven-new

# 4) Refresh deps and restart.
cd ~/maven && npm install
systemctl --user restart maven                                     # Linux
# launchctl load -w ~/Library/LaunchAgents/com.maven.app.plist     # macOS
# Start-ScheduledTask -TaskName MAVEN                              # Windows

No rsync? unzip -o ~/maven-<VERSION>.zip -d /tmp/mv && cp -a /tmp/mv/maven-<VERSION>/. ~/maven/ updates and adds files but leaves deleted ones behind (usually harmless). On Windows use Git Bash or WSL for the shell commands.

After restart, open http://localhost:3000; if anything looks off, read the logs - journalctl --user -u maven -f (Linux), ~/.maven/maven.err.log (macOS), or the Scheduled-Task history (Windows).

Upgrading from ≤ 6.15.x - the security release (read once)

Using M.A.V.E.N only on this machine (127.0.0.1 / localhost)? You have nothing to do. No PIN, no new screen, no setting to change.

The update runs by itself and nothing breaks on the machine itself. post-update does the one-time migration: .env.local and credential copies become 0600, 3D-Forge bots get their hook secret, and the report names where the remote PIN lives. What you may notice:

You had…	After the update
M.A.V.E.N only on this machine	Nothing changes. A remote-host PIN now exists (~/.maven/access-pin, also in Settings → Security) for the day you want it.
M.A.V.E.N open over Tailscale / LAN without a PIN	That host asks for a PIN the first time: enter the one from Settings → Security → Reveal (or cat ~/.maven/access-pin). The host is remembered; the session lasts 30 days.
MAVEN_ACCESS_PIN=… set, already unlocked in the browser	Your unlock cookie is accepted once and re-issued; the host is remembered. Your PIN still applies everywhere (loopback too) - switch modes in Settings → Security if you want loopback open.
MAVEN_ACCESS_PIN=… set, cookie expired / new device	The unlock screen on that host; your PIN works; host remembered.
A PIN shorter than 8 characters	Still works; the log warns once. Change it in Settings → Security.
OpenCode console with auto-approve	It now asks for permissions. MAVEN_CHAT_PERMISSION_MODE=bypass restores the old default. Autonomous apps (OpenMontage, Hermes goals, Loop, Pipeline) are unchanged.
Heavy generation days	A 25 USD/day ceiling across paid engines; raise it in Settings → Security or MAVEN_DAILY_SPEND_USD.
VC-Forge projects outside your home folders	Existing projects keep working; new ones go under the vault / ~/Projects / ~/Documents / ~/Desktop / ~/Obsidian (or MAVEN_VCFORGE_DIR).
R-Forge / N-Forge fed a localhost or LAN URL	Refused now; MAVEN_ALLOW_PRIVATE_FETCH=1 if that was intentional.
3D-Forge Telegram bots	Re-provisioned automatically. If a bot answers “hook refused”, run node scripts/gforge/setup-swarm-3d.mjs --all.
npm run dev -- -H 0.0.0.0	Don’t. Use Tailscale / a tunnel + Settings → Security → Allowed hosts.

Full reference: Security & remote access.

Older version notes

Crossing several versions at once? Run the general procedure once to the target, then read the intervening notes in UPDATE.md in the repo. The ones that still bite:

• 6.12.5-6.12.7 → newer - the old updater tripped on .next/cache during the rename. Break the loop once: cd ~/maven && rm -rf .next/cache && node scripts/self-update.mjs, or git pull && npm install && npm run build by hand.
• ≤ 6.5 → newer - Course Gen and Maven-Slides became P-Forge; /coursegen and /slides redirect. /vibecoding redirects to VC-Forge, /mineru to D-Forge → MinerU, /seo to SEO-Forge.
• ≤ 6.13 → newer - the per-model console pages became one Chat; Music, Thumbnails, OpenMontage and the Video Editor are tabs of M-Forge.

Your files are preserved

An update reverts tracked files to the release but leaves your own alone: agents.config.json (three-way merged if the release changed it too), .env.local, everything under ~/.maven, the vault and the CLI logins.