Volume Mount

A volume mount is a mechanism that connects a directory on the host system or a managed storage layer to a path inside a container. This allows data to persist beyond the container's lifecycle, surviving restarts, redeployments, and image updates.

Why It Matters

Containers are ephemeral by design. When a container stops, all data written to its internal filesystem is lost. For AI assistant deployments, this is a serious problem. Configuration files, authentication credentials, conversation history, workspace files, and gateway tokens must persist across restarts. Volume mounts provide the bridge between the disposable container and durable storage.

How It Works

There are three common types of volume mounts. Named volumes are managed by the container runtime and stored in a designated area on the host. Bind mounts map a specific host directory into the container. Managed volumes on cloud platforms like Railway provide network-attached persistent storage.

When you define a volume mount, you specify both the source (host path or volume name) and the destination (path inside the container). For example, mounting a volume at /data inside the container means any files written to /data are actually stored on the persistent volume. Subdirectories like /data/.openclaw for configuration and /data/workspace for agent files then survive container replacements.

In Practice

Always mount volumes at consistent paths and reference them via environment variables like OPENCLAW_STATE_DIR and OPENCLAW_WORKSPACE_DIR. Avoid storing secrets directly on volumes when possible; prefer environment variables for sensitive values. When backing up your AI assistant, export the entire volume contents as a compressed archive to capture all state, credentials, and workspace files in a portable format.