​
Updating

TraseAI is moving fast (pre “1.0”). Treat updates like shipping infra: update → run checks → restart (or use traseai update, which restarts) → verify. From your TraseAI repo checkout: 
cd traseai
git pull
pnpm install
pnpm build
pnpm traseai doctor
pnpm traseai gateway restart
Or use the built-in update command: 
pnpm traseai update
It runs a safe update flow:
  • Requires a clean worktree.
  • Fetches + rebases against the configured upstream.
  • Installs deps, builds, and runs traseai doctor.
  • Restarts the gateway by default (use --no-restart to skip).

​
Before you update

  • Know how your Gateway is running: foreground terminal vs supervised service (launchd/systemd).
  • Snapshot your tailoring:
    • Config: ~/.traseai/traseai.json
    • Credentials: ~/.traseai/credentials/
    • Workspace: ~/.traseai/workspace

​
Update (Control UI / RPC)

The Control UI has Update & Restart (RPC: update.run). It:
  1. Runs the same source-update flow as traseai update (git checkout only).
  2. Writes a restart sentinel with a structured report (stdout/stderr tail).
  3. Restarts the gateway and pings the last active session with the report.
If the rebase fails, the gateway aborts and restarts without applying the update. Notes:
  • pnpm build matters when you run the packaged traseai binary (traseai.mjs) or use Node to run dist/.
  • If you run from a repo checkout without a global install, use pnpm traseai ... for CLI commands.
  • If you run directly from TypeScript (pnpm traseai ...), a rebuild is usually unnecessary, but config migrations still apply → run doctor.
  • Switching between global and git installs is easy: install the other flavor, then run traseai doctor so the gateway service entrypoint is rewritten to the current install.

​
Always Run: traseai doctor

Doctor is the “safe update” command. It’s intentionally boring: repair + migrate + warn. Note: if you’re on a source install (git checkout), traseai doctor will offer to run traseai update first. Typical things it does:
  • Migrate deprecated config keys / legacy config file locations.
  • Audit DM policies and warn on risky “open” settings.
  • Check Gateway health and can offer to restart.
  • Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current TraseAI services.
  • On Linux, ensure systemd user lingering (so the Gateway survives logout).
Details: Doctor

​
Start / stop / restart the Gateway

CLI (works regardless of OS): 
traseai gateway status
traseai gateway stop
traseai gateway restart
traseai gateway --port 18789
traseai logs --follow
If you’re supervised:
  • macOS launchd (app-bundled LaunchAgent): launchctl kickstart -k gui/$UID/bot.molt.gateway (use bot.molt.<profile>; legacy com.traseai.* still works)
  • Linux systemd user service: systemctl --user restart traseai-gateway[-<profile>].service
  • Windows (WSL2): systemctl --user restart traseai-gateway[-<profile>].service
    • launchctl/systemctl only work if the service is installed; otherwise run traseai gateway install.
Runbook + exact service labels: Gateway runbook

​
Rollback / pinning (when something breaks)

​
Pin by date

Pick a commit from a date (example: “state of main as of 2026-01-01”): 
git fetch origin
git checkout “$(git rev-list -n 1 --before=\”2026-01-01\” origin/main)”
Then reinstall deps + restart: 
pnpm install
pnpm build
pnpm traseai gateway restart
If you want to go back to latest later: 
git checkout main
git pull
pnpm install
pnpm build

​
If you’re stuck