To keep DeepAgents data after a Docker container is replaced, configure both layers: tell DeepAgents what to save and where, then mount that storage path to a Docker volume or host bind mount. For conversation state, retain the checkpointer and continue with the same thread identifier; for files or cross-thread data, configure the corresponding backend or store as well. A mount alone does not save graph state, and a checkpoint alone does not protect files written elsewhere in the disposable container layer.
Choose what needs to survive
DeepAgents data can have different persistence scopes. Decide which one you need before choosing a backend or Docker mount:
- Conversation state: checkpoints associated with a graph run and thread. To resume that thread, the checkpointer must persist its data and you must keep using the same thread identifier.
- Generated or working files: files managed by a filesystem backend. They need a persistent backend location if they must survive container replacement.
- Cross-thread data: shared or longer-lived information held in a store backend, using an application-specific namespace rather than relying on one conversation’s checkpoint.
These are separate concerns. Persisting a workspace directory does not configure checkpointing, and checkpointing graph state does not automatically persist arbitrary files written to another location.
Configure the DeepAgents persistence layer
The DeepAgents workflow guidance describes StateBackend() as the default backend, associating files with graph state and a conversation thread. It also describes FilesystemBackend for direct filesystem access and StoreBackend with a store for cross-thread persistence. The checkpointer and backend should match the data and scope you intend to retain. See the DeepAgents workflow guidance for the documented options.
#1 Best Overall
When using a filesystem backend, configure its root directory explicitly. There is no universal DeepAgents directory to mount: the correct path is the one your application actually configures. For thread checkpoints or a store, use a persistence implementation appropriate to your installed version and deployment; the workflow page is on the live main branch, so confirm API names and configuration against the version of DeepAgents you run.
Put disk-backed data on persistent Docker storage
A Docker volume preserves mounted data beyond an individual container’s lifecycle. Docker manages the volume, and a replacement container can access the existing files when it mounts the same volume again. A bind mount instead connects a host path to a container path, which is useful when host processes need direct access to those files. Docker explains the distinction in its container data persistence overview and volume documentation.
Rank #2
In either case, the application must write to the mounted path. Data written elsewhere in the container’s writable layer is not preserved merely because a volume exists. Mount the backend’s configured directory—not a guessed path—and ensure the container process can read and write it. Exact ownership, permissions, mount-driver options, and configuration syntax depend on the deployment.
Deployment sequence
- Inventory the data: identify whether you need thread checkpoints, filesystem files, cross-thread store data, or more than one of these.
- Configure DeepAgents: choose the matching backend and checkpointer or store. For filesystem-backed data, set its actual root path inside the container.
- Mount persistent storage: map that container path to a named Docker volume, or to a host directory with a bind mount if host visibility is required.
- Start the agent: verify that it writes the intended files or checkpoint data beneath the configured persistent location.
- Replace and resume: recreate the container with the same mount declaration. For thread-scoped checkpoints, continue with the same thread identifier.
- Test recovery: confirm the expected thread state and files are available after replacement. Back up persistent data separately if recovery from host or storage failure matters.
Understand the trade-offs and failure points
| Choice | What it persists | Storage access | Key consideration |
|---|---|---|---|
StateBackend() with a checkpointer |
Graph-associated files and thread state, subject to the configured checkpoint implementation | Graph state/checkpoint storage | Use the same thread identifier to resume thread-scoped data; this does not preserve arbitrary files elsewhere. |
FilesystemBackend on a mounted path |
Files written under the configured filesystem root | Container path backed by a Docker volume or bind mount | Mount the actual root and check permissions. |
StoreBackend with a store |
Application data intended to be available across threads | The configured store and application-specific namespace | Namespace design and store persistence must be configured; a workspace mount alone is not a substitute. |
| Docker named volume | Files written beneath its mount point beyond the container lifecycle | Docker-managed storage | Reattach the same volume to the replacement container. |
| Host bind mount | Files written beneath its mount point | Host path is directly visible to host processes | Host path and permissions are deployment-specific. |
Common causes of apparent data loss include mounting a different volume on recreation, mounting a directory other than the backend root, writing to an unmounted path, changing the thread identifier when expecting to resume a thread, or configuring filesystem persistence without a checkpointer for graph state. A persistent volume survives container deletion, but it is not by itself a backup against host or storage failure.
Rank #3
Version and deployment qualifications
The cited DeepAgents guide is a live document rather than a release-pinned API reference. Confirm backend and checkpointer syntax for your installed package version. The cited guidance does not establish a universal Compose file, backend directory, UID/GID policy, remote volume driver, or backup schedule; set and test those for your environment.
Quick Recap
Best Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
