|
| 1 | +______________________________________________________________________ |
| 2 | + |
| 3 | +## title: Filesystem Session Sync description: View sessions from multiple machines by transporting native agent session directories to one AgentsView instance |
| 4 | + |
| 5 | +AgentsView can label filesystem session roots with the machine that produced |
| 6 | +them. This supports a simple multi-machine topology without PostgreSQL: |
| 7 | + |
| 8 | +1. Each source machine writes its normal agent session files. |
| 9 | +1. Git, rsync, a file-copy job, or a shared filesystem transports those native |
| 10 | + layouts out of band. |
| 11 | +1. One primary AgentsView instance scans the received roots into its local |
| 12 | + SQLite archive. |
| 13 | + |
| 14 | +This is a **primary-viewer topology**. Use [PostgreSQL sync](/pg-sync/) instead |
| 15 | +when several viewers need a shared live database or a read-only database-backed |
| 16 | +endpoint. |
| 17 | + |
| 18 | +## Configure Session Sources |
| 19 | + |
| 20 | +Add one `[[session_sources]]` table per received agent root: |
| 21 | + |
| 22 | +```toml |
| 23 | +[[session_sources]] |
| 24 | +agent = "copilot" |
| 25 | +dir = "/srv/session-archive/buildbox/copilot" |
| 26 | +machine = "buildbox" |
| 27 | + |
| 28 | +[[session_sources]] |
| 29 | +agent = "claude" |
| 30 | +dir = "/srv/session-archive/buildbox/claude/projects" |
| 31 | +machine = "buildbox" |
| 32 | + |
| 33 | +[[session_sources]] |
| 34 | +agent = "codex" |
| 35 | +dir = "/srv/session-archive/laptop/codex/sessions" |
| 36 | +machine = "laptop" |
| 37 | +``` |
| 38 | + |
| 39 | +`agent` must be a supported AgentsView parser name. `dir` must be a filesystem |
| 40 | +root in that agent's native layout. `machine` uses the same machine label shown |
| 41 | +in session filters and configured by `[pg].machine_name`. If `machine` is |
| 42 | +omitted, AgentsView uses the primary viewer's hostname. |
| 43 | + |
| 44 | +Existing per-agent arrays and environment variables remain supported. Structured |
| 45 | +sources are additive: |
| 46 | + |
| 47 | +```toml |
| 48 | +copilot_dirs = ["/home/viewer/.copilot"] |
| 49 | + |
| 50 | +[[session_sources]] |
| 51 | +agent = "copilot" |
| 52 | +dir = "/srv/session-archive/buildbox/copilot" |
| 53 | +machine = "buildbox" |
| 54 | +``` |
| 55 | + |
| 56 | +AgentsView normalizes roots for duplicate comparison. Legacy per-agent settings |
| 57 | +and structured entries retain their original path spelling. When a structured |
| 58 | +source names the same root as a per-agent array, default, or environment |
| 59 | +variable, the structured entry supplies the machine label. |
| 60 | + |
| 61 | +`session_sources` accepts filesystem roots only. Keep using the existing |
| 62 | +Claude/Codex per-agent arrays for `s3://` roots; S3 ingestion has established |
| 63 | +machine-derived ID-prefix behavior that differs from filesystem labeling. Native |
| 64 | +SQLite-backed agent stores are supported when `dir` points at their filesystem |
| 65 | +root. |
| 66 | + |
| 67 | +## Transport Rules |
| 68 | + |
| 69 | +Sync the **source agent's session files and native directory layout**. Never |
| 70 | +copy AgentsView's `sessions.db`, `sessions.db-wal`, `sessions.db-shm`, or |
| 71 | +`vectors.db`. Those files belong to the primary viewer and copying a live SQLite |
| 72 | +database or WAL can corrupt or fork the archive. |
| 73 | + |
| 74 | +For every destination source tree: |
| 75 | + |
| 76 | +- Have one writer. Multiple transport jobs must not update the same tree. |
| 77 | +- Transfer into a staging path, then rename or switch the completed tree into |
| 78 | + place when possible. |
| 79 | +- Preserve filenames, relative paths, and companion metadata files. |
| 80 | +- Avoid exposing partially copied files. AgentsView retries changed files, but |
| 81 | + atomic publication prevents transient parse errors and incomplete sessions. |
| 82 | +- Treat the primary copy as read-only input to AgentsView. |
| 83 | + |
| 84 | +## Transport Examples |
| 85 | + |
| 86 | +The transport is independent of AgentsView. These examples show the directory |
| 87 | +shape; adapt scheduling and authentication to your environment. |
| 88 | + |
| 89 | +### Git |
| 90 | + |
| 91 | +Commit native session trees on the source machine, pull into a staging checkout |
| 92 | +on the primary machine, then atomically replace the published checkout: |
| 93 | + |
| 94 | +```text |
| 95 | +session-archive/ |
| 96 | +├── buildbox/ |
| 97 | +│ ├── claude/projects/... |
| 98 | +│ └── copilot/session-state/... |
| 99 | +└── laptop/ |
| 100 | + └── codex/sessions/... |
| 101 | +``` |
| 102 | + |
| 103 | +Git is most suitable for modest archives where commit history is useful. Avoid |
| 104 | +running AgentsView against a checkout while `git pull` is rewriting it; publish |
| 105 | +a completed checkout or worktree instead. Session files can contain prompts, |
| 106 | +tool output, and source excerpts, so use access controls appropriate for |
| 107 | +sensitive data. |
| 108 | + |
| 109 | +### rsync or File Copy |
| 110 | + |
| 111 | +Copy each machine into its own destination tree. `--delay-updates` reduces the |
| 112 | +window in which completed files appear partially updated: |
| 113 | + |
| 114 | +```bash |
| 115 | +rsync -a --delete --delay-updates \ |
| 116 | + source-host:/home/user/.copilot/ \ |
| 117 | + /srv/session-archive/buildbox/copilot/ |
| 118 | +``` |
| 119 | + |
| 120 | +For transports without delayed updates, copy to a sibling staging directory and |
| 121 | +rename it into place. Do not let two sources use the same destination tree. |
| 122 | + |
| 123 | +### NFS or Shared Mount |
| 124 | + |
| 125 | +Mount each source machine's exported session directory on the primary viewer, |
| 126 | +preferably read-only: |
| 127 | + |
| 128 | +```toml |
| 129 | +[[session_sources]] |
| 130 | +agent = "claude" |
| 131 | +dir = "/mnt/sessions/buildbox/claude/projects" |
| 132 | +machine = "buildbox" |
| 133 | + |
| 134 | +[[session_sources]] |
| 135 | +agent = "copilot" |
| 136 | +dir = "/mnt/sessions/laptop/copilot" |
| 137 | +machine = "laptop" |
| 138 | +``` |
| 139 | + |
| 140 | +Shared mounts remove the copy step, but freshness and watcher behavior depend on |
| 141 | +the filesystem. Some network filesystems do not deliver local filesystem events |
| 142 | +reliably; the periodic sync remains the backstop. |
| 143 | + |
| 144 | +## Identity, Filtering, and Freshness |
| 145 | + |
| 146 | +- The machine label is stored per discovered source root. Filter sessions by |
| 147 | + `machine` in the session browser, API, and analytics views. |
| 148 | +- A session keeps the machine label it received when it was first ingested. |
| 149 | + Editing a source's `machine` value affects newly discovered sessions but does |
| 150 | + not retroactively relabel existing ones, even when their source files later |
| 151 | + change. `agentsview sync --full` also preserves the stored label. Changing |
| 152 | + attribution for existing sessions is not currently supported. |
| 153 | +- Filesystem machine labels do **not** namespace session IDs. If the same native |
| 154 | + session is copied into two configured roots, AgentsView continues to |
| 155 | + deduplicate it by the agent's native session ID. |
| 156 | +- A newly transported or changed file is normally detected by the filesystem |
| 157 | + watcher. AgentsView also performs a full periodic sync every 15 minutes. |
| 158 | +- Roots that cannot be watched fall back to polling, as described under |
| 159 | + [Large Watch Trees](/configuration/#large-watch-trees). |
| 160 | +- A machine label changes attribution, not source identity or conflict |
| 161 | + resolution. Do not intentionally place different sessions with the same native |
| 162 | + ID in separate roots. |
| 163 | +- Deleting a transported source file does not automatically erase the archived |
| 164 | + session. The local SQLite database is a persistent archive; use pruning tools |
| 165 | + when removal is intended. |
| 166 | + |
| 167 | +Filesystem sync is intentionally simple: one primary AgentsView owns the archive |
| 168 | +and UI. PostgreSQL remains the better fit for independently running AgentsView |
| 169 | +instances that must contribute to or read from a shared live store. |
0 commit comments