Data layout

This page documents the on-disk layout AgentMux uses to isolate state across builds and to make log files discoverable from any context. For the user-facing perspective (“how do I run multiple versions side-by-side?”) see Running multiple instances. For the SQLite stores themselves, see Persistence.

The on-disk layout is keyed by channel (per SPEC_DATA_CHANNELS_2026_05_24.md), not by version — every version within a channel reads and writes the same data dir, so My Agents / conversations / identity bundles persist across patch and minor bumps. Across channels (stable, beta, dev-portable, dev-<branch>) state is fully isolated.

Channels: what they replace

Earlier builds isolated by version — each new build got a fresh, empty ~/.agentmux/versions/<version>/. That cost was real: every task package bump reset My Agents and discarded conversation history. Channels collapse the per-version dirs back into one per-channel dir, so the only thing that changes across patch/minor bumps is whichever schema migrations run on launch.

Runtime modes, channels, and data directories

Runtime mode	Default channel	Data directory
Installed (production install)	`stable`	`~/.agentmux/channels/stable/`
Portable (downloaded released ZIP)	`stable`	`~/.agentmux/channels/stable/` (same as installed — both bind to the same channel)
Portable (local `task package` build)	`dev-portable`	`~/.agentmux/channels/dev-portable/`
Dev (`task dev`)	`dev-<branch>`	`~/.agentmux/channels/dev-<branch>/`

The mode is detected at startup by agentmux-common’s runtime-mode probe (agentmux-common/src/runtime_mode.rs). The channel is derived from the mode, with an override:

AGENTMUX_CHANNEL=<name> — pin the channel explicitly. Useful for parallel-channel testing (AGENTMUX_CHANNEL=beta agentmux.exe) or for letting a dev build share state with a portable.

Resolution is centralized in agentmux-common::DataPaths. The launcher resolves once at startup and exports AGENTMUX_DATA_DIR, AGENTMUX_CONFIG_DIR, AGENTMUX_LOG_DIR, etc. as env vars; host and sidecar read them from env. All three processes always agree on paths.

Schema safety lock + snapshots

Migrations are forward-only. When a newer binary opens a channel whose schema is older, it runs the migrations on launch. When an older binary tries to open a channel whose schema is newer than it knows about, it refuses to open — protecting against downgrade corruption. Snapshots auto-save before any migration runs and the last 5 are kept; you can roll back manually if a migration produces bad state.

Per-channel contents

Inside each data dir (shared by every version of the same channel at runtime):

Path	Owns
`<data-dir>/data/`	SQLite stores (`db/objects.db`, `db/filestore.db`, `db/sagas.db`, `db/launcher-sagas.db`) and the launcher’s JSONL event log (`launcher-events.log`)
`<data-dir>/logs/`	Host + sidecar logs (rotated daily, 7-day retention)
`<data-dir>/cef-cache/`	Chromium cookies, local storage, IndexedDB, service workers, cached JS
`<data-dir>/agents/`	Per-agent working dirs created by the agent system
`<data-dir>/config/`	Settings (`settings.json`) plus per-provider auth-config-dir homes (`config/auth/claude/`, `config/auth/codex/`, etc. — see Auth flows)
`<data-dir>/runtime/`	Runtime IPC artifacts (lock files, named-pipe sockets) used by the launcher’s single-instance / IPC machinery

See Persistence for what each SQLite file holds and which process writes it.

Account-wide (shared) contents

A single tree at ~/.agentmux/, independent of channel:

Path	Purpose	Owner
`~/.agentmux/shared/`	Account-wide state (cookies, dictionary downloads) — shared across channels	All hosts
`~/.agentmux/logs/current-host-v<version>.path`	Pointer file resolving to the running host’s log path	Host (write-through)
`~/.agentmux/logs/current-srv-v<version>.path`	Pointer file resolving to the running sidecar’s log path	Sidecar (write-through)
`~/.agentmux/logs/agentmux-launcher.log`	The launcher’s own startup-phase log (single file, no rotation)	Launcher
`~/.agentmux/config.toml`	Account-wide launcher config (saga retention, etc.)	Launcher

The durable launcher reducer event log (launcher-events.log) lives at <data-dir>/data/launcher-events.log. With multiple instances of the same channel running, all of their launchers append to this single file.

Log discovery via pointer files

The host writes its own logs to <data-dir>/logs/. To make those discoverable from any context (e.g. a muxlog shell helper running in an unrelated terminal), the host also writes a pointer file under the shared ~/.agentmux/logs/ directory:

~/.agentmux/logs/current-host-v<version>.path

The pointer file’s contents are the absolute path to the current log file:

C:\Users\area54\.agentmux\channels\stable\logs\agentmux-host-v0.38.4.log.2026-05-25

So the canonical “find the running host’s log” recipe is:

LOG="$(cat ~/.agentmux/logs/current-host-v<version>.path)"
tail -F "$LOG"

Same convention applies to the sidecar (current-srv-v<version>.path).

`muxlog` helper

The shell-integration scripts shipped to AgentMux’s own terminals expose a muxlog helper that wraps the pointer-file dance:

muxlog host          # tail the current host log
muxlog srv           # tail the sidecar log
muxlog host '\[fe\]' # filter the host log to frontend [fe] lines
muxlog host cat      # full file contents (instead of tailing)

The helper detects whether the pointer holds a basename (legacy) or an absolute path (newer versions), so the same command works against any version.

In-memory ring + disk overflow

The launcher’s reducer event log is backed by an in-memory ring buffer (4096 entries). Recent events are queryable from a running instance without touching disk; older events spill to <data-dir>/data/launcher-events.log for durability.

This is the canonical forensic source when something feels off at the OS level: a window vanished, a pane drifted, a monitor disconnect lost focus. Search recipes:

# Windows / Git Bash / muxlog-style
grep -E "HiddenSinceOpen|HwndWithoutBrowser|WRR-DRIFT|wfr:gate|wfr:runner|pending=" \
    "$AGENTMUX_DATA_DIR/launcher-events.log"

See Window Reality Reconciliation for what the WRR drift records mean.

Backup + portability

Each per-version file is independently restorable:

Cold-copy the whole <data-dir>/data/ directory while AgentMux is closed — that’s the simplest, most reliable backup.
Hot copy of an individual SQLite file while AgentMux is open is supported because the writer holds short transactions; use sqlite3 .backup. The JSONL event log is append-only and safe to copy at any time.

Re-importing into a fresh install: stop AgentMux, place the files at <data-dir>/data/db/ (and the JSONL log at <data-dir>/data/), and launch. Bootstrap reads them.