Running Agentrium locally for QA

The hard rule (never violate)

The user runs their real Agentrium client on this machine, all day, with live Claude Code sessions in it. It is production. It is their actual work.

NEVER, under any circumstances, for any reason:

• Kill, stop, close, Stop-Process, CloseMainWindow, taskkill, or otherwise terminate a running claude-terminal.exe / Agentrium process.
• Take, free, or kill whatever is holding port 5173. That is the production client's dev port.
• Ask the user to close their client so your build can launch.
• Run bare npm run tauri dev or npm run dev in this repo. Both default to 5173 and to the production app identifier, which collides.

There is no exception. Not "just this once", not "it's only a dev build", not "the app restores sessions anyway", not if a launch fails and killing it would be the quick fix. If QA seems to require stopping their client, you are using the wrong recipe - use the one below instead.

If something still will not run after following this file, report that and stop. Do not escalate to touching their process.

Why a plain tauri dev cannot work here

Three separate collisions, all of which must be solved at once:

Fixing only one of the first two is what causes the damage. Fix both.

Isolating the database (know this before you QA)

Always export AGENTRIUM_INSTANCE_ID=.qa before launching. Rust reads it through crate::instance_suffix() (src-tauri/src/main.rs) and appends it to:

• the SQLite data dir: ClaudeTerminal.qa\claudeterminal.db instead of the prod ClaudeTerminal\claudeterminal.db (database.rs), so profiles, workspaces, agents and session history start empty and stay separate;
• the keychain service: com.claudeterminal.agentrium.auth.qa (credentials.rs), so signing in or out in QA never touches the prod refresh token.

Without the variable the QA window opens on the user's real database. If you forget it, close the QA window you launched and relaunch with it.

Do NOT use APPDATA / LOCALAPPDATA redirection instead. directories resolves folders through SHGetKnownFolderPath, which ignores those variables, so the redirect silently does nothing.

What is still shared with prod even with the suffix (all low risk, but know it):

• Terminal log files in ClaudeTerminal\logs (commands.rs hard-codes the unsuffixed dir). QA writes new, uniquely named files there and only deletes paths that its own DB points at, so prod logs are not touched.
• error_reporter / feedback queues and the LSP download cache also use the unsuffixed dir.
• Real outside state: git repos, worktrees, files on disk, and Claude Code's own ~/.claude sessions. A QA terminal pointed at a real repo is a real terminal. Use a scratch folder for destructive flows (worktree removal, force push, session purge).

The recipe

Run from agentrium/. Pick a QA port that is not 5173 (5174 is the default choice; step up if it is taken).

QA_PORT=5174
export AGENTRIUM_INSTANCE_ID=.qa

npm run tauri dev -- \
  --features devtools \
  --config "{\"identifier\":\"com.claudeterminal.desktop.qa\",\"productName\":\"Agentrium QA\",\"build\":{\"devUrl\":\"http://localhost:$QA_PORT\",\"beforeDevCommand\":\"npm run dev -- --port $QA_PORT --strictPort\"}}"

Before picking the port, confirm nothing is listening on it: Get-NetTCPConnection -LocalPort 5174 -State Listen -ErrorAction SilentlyContinue returning nothing means it is free. If it is taken, use 5175, 5176, and so on. Never 5173.

What each override buys you:

• AGENTRIUM_INSTANCE_ID=.qa - own SQLite DB and own keychain entry (see "Isolating the database" above).
• identifier -> ...desktop.qa - single-instance no longer hands off, so a second window actually opens beside theirs.
• productName -> Agentrium QA - the window title tells you at a glance which one you are looking at. Always check the title before interacting.
• devUrl + beforeDevCommand --port - both halves must change together, or Tauri loads 5173 and you are driving their app's server. First run recompiles Rust for the changed identifier - budget a few minutes.

Verifying you are on the QA instance, not theirs

Before driving anything, confirm there are now two processes and that you know which is which:

Get-Process claude-terminal | Select-Object Id,MainWindowTitle,StartTime

The QA one is titled Agentrium QA and has the newer StartTime. If only one process exists, the overrides did not take - re-read the recipe, do not kill anything.

Cleaning up

Stop ONLY the background task you started (TaskStop with your own task id), or close the Agentrium QA window. Never target a PID you did not launch, and never Stop-Process -Name claude-terminal - that name matches theirs too.

Driving the update sheet and notification banner

Both are frontend-only, so DevTools (--features devtools is already in the recipe) can drive them without any app source changes. Vite serves the store modules in dev:

const u = (await import('/src/store/updaterStore.ts')).useUpdaterStore;
const { toast, useToastStore } = await import('/src/store/toastStore.ts');

// update sheet: available / downloading / ready / error
u.setState({ status: 'available', notifiedVersion: '2.4.0',
  updateInfo: { version: '2.4.0', date: '2026-09-15', body: 'Release notes' },
  bannerDismissedVersion: null, bannerSnoozedUntil: null, skippedVersion: null });

u.setState({ status: 'downloading', downloadProgress: 61,
  downloadedBytes: 11200000, totalBytes: 18400000, bannerDismissedVersion: null });

u.setState({ status: 'ready', bannerDismissedVersion: null });   // Relaunch really relaunches
u.setState({ status: 'error', error: 'connection closed', bannerDismissedVersion: null });

// notifications - 4 at once crosses the collapse threshold
toast.success('Pushed to origin/master', '14 files changed across 2 commits');
toast.error('Push rejected', 'The remote has commits you do not have locally');
toast.warning('Worktree has uncommitted work', 'Switching branches may stash 6 files');
toast.info('Session restored', '4 terminals reattached');
useToastStore.getState().clearAll();

Do not bother with a plain browser

http://localhost:<port> in an ordinary browser hits the error boundary: useWindowFocused.ts calls getCurrentWindow(), which needs window.__TAURI_INTERNALS__. Stubbing it is not worth the effort - use the real window from the recipe above.