Persistence
Understand the shared writable directory, write durability, and VM recovery.
Each session has an ordinary writable filesystem mounted at /workspace on its retained Assemble VM. The file API, managed commands, SSH processes, and provided Pi tools all access that same directory.
One primary VM
The session has one primary VM with exclusive access to its mounted project storage. Several processes inside that VM can use its files normally. A second VM cannot mount the same project storage as another writer.
The API coordinates managed writers. SSH processes run outside that coordination, so stop or coordinate them before another harness changes the same files. See Lifecycle.
What is retained
| State | Stored in | Retained with the same VM | Available after VM replacement |
|---|---|---|---|
Flushed project files in /workspace | Persistent session storage | Yes | After mounting the retained session filesystem |
| Dirty writes awaiting a flush | Filesystem buffers in the VM | Pending until flushed | Can be lost if the old VM is lost before flushing |
Packages and changes outside /workspace | VM disk | With the retained disk | Requires an image, setup recipe, or restore |
| Home directory and local shell configuration | VM disk | With the retained disk | Requires a restore or setup recipe |
| Running process and memory | VM runtime | Depends on the lifecycle operation | Requires a process restart |
| Your harness's conversation | Wherever your harness stores it | Depends on your harness | Depends on your harness |
File durability
The session filesystem can buffer writes inside the VM before sending them to persistent storage. An application can make those bytes visible to other processes using the same mount while they are still dirty. A successful fsync, or a completed background flush, makes pending data durable. A healthy mount and a successful read do not by themselves prove that newly written bytes are durable.
Applications writing through Bash or SSH should flush their own language-level buffers and use fsync when they need an explicit durability boundary. A command's zero exit code reports process success; it does not add an automatic transaction or durability barrier to every file the command touched.
The file API flushes its write buffer, calls fsync on the new file, replaces the destination, and calls fsync on its containing directory before returning success. That explicit write path has different behavior from an arbitrary command that simply exits after writing.
The service verifies the mount before accepting session operations. Without that mount, a plain /workspace directory would store files only on the VM disk.
Retaining session files also requires keeping the backing project storage. session.pause() keeps it. session.delete() deletes both the VM and its session filesystem permanently.
Clean shutdown and replacement
Coordinate VM shutdown or replacement with the service operator when you need to retain project files. Stop writers and flush application buffers first. The operator must then complete the storage system's clean-unmount procedure, which waits for outstanding writes. An abrupt shutdown or forced unmount can lose pending data.
The pause route keeps the mount attached while pausing the VM. It does not perform a clean unmount or flush application buffers. Reading a file after resume alone does not verify that dirty bytes reached persistent storage before the pause.
Command records and rollback
The execution service records output and completion status for managed commands. Version 1 performs ordinary filesystem mutations without an overlay transaction for each command. Failed or cancelled commands can leave partial changes. There is no automatic per-command rollback, file-version ledger, or restore endpoint for API, SSH, or provided-harness writes.
Use your project's own version control or backup process when you need to recover earlier content.
Environment recovery
Record the software your agent depends on in an image recipe, lockfile, or repeatable setup script. Keep project outputs in the session. Decide separately how your application supplies credentials and restores its conversation state.
The public API does not expose an automatic VM-replacement operation.
Your application still needs a reproducible setup for VM-local dependencies and its own conversation state. Recovery after abrupt loss of unflushed data has the limitations described above.