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.

What’s new in 6.21.0

• SocialHub - M.A.V.E.N’s own publishing app. Telegram and Mastodon connect now; posts for unconnected platforms go to a test channel. Agent posts wait for approval unless the platform is marked autonomous; there are daily limits and a stop switch. See SocialHub.
• Content factory and Brands - the second floor of PLAYGROUND: 14 AI roles, no people in the chain, brand profiles that Claude reads from your files and website. See Content factory & Brands.
• S-Forge video - the content factory makes videos as films through S-Forge, with a hard credit cap.
• Sidebar - nine apps (Ad-, D-, G-, M-, N-, P-, R-, T- and X-Forge) showed a raw key instead of their subtitle; fixed in EN, UK and RU.
• PLAYGROUND engine fixes - retrying a stopping run is refused until its step finishes (it used to be silently ignored); a file a step only reads is no longer mistaken for its output; reviewers may run ffmpeg/ffprobe to look inside a video.
• Also since 6.18.5: PLAYGROUND real runs (6.19.0), the Course Studio build and narration fix (6.20.1), Hermes “default” profile fixes, and one-way settings backup to GitHub. There was no 6.20.0 release.

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.