Shared folders

Overview

Shared folders let you create a named volume and mount it into multiple OpenClaw instances at the same path. Any file written by one instance is immediately visible to every other instance that shares the folder. This is useful for shared datasets, collaborative workspaces, or common configuration files.

Shared folders are available to all authenticated users. Admins can see and manage all shared folders; regular users see only folders they created and can only map them to instances they have access to.

Creating a shared folder

1. Open Shared Folders in the sidebar.
2. Click New Folder.
3. Enter a name (for example, “Research Data”) and a mount path (for example, /shared/research).
4. Click Create.

The folder is created immediately but is not mounted to any instance yet. Add instances in the next step.

Mount path restrictions

The mount path must start with / and cannot overlap with these reserved paths:

• /home/claworc (instance home directory)
• /home/linuxbrew (Homebrew installation)
• /dev/shm (shared memory)

Recommended mount paths: /shared/<name> or /data/<name>.

Note

Each shared folder must have a unique mount path. Two folders cannot share the same path, even if they are mapped to different instances. This prevents mount conflicts when multiple folders are later assigned to the same instance.

Mapping instances

1. Open the shared folder by clicking Edit in the table row.
2. Use the instance selector to add or remove instances.
3. Click Save.

Caution

Changing instance mappings or the mount path automatically restarts all affected running instances. Stopped instances pick up the change on their next start.

Host-backed folders

By default, a shared folder is backed by a Claworc-managed volume. You can instead back a folder with a real directory on the host machine — a Docker bind mount, or a Kubernetes hostPath volume. Use this to connect an instance to an existing local workflow, for example mounting an Obsidian or Syncthing vault into the instance so the agent reads and writes the same files you do.

Enabling host-backed folders

Host-backed folders are disabled by default and must be enabled by an operator. They are gated by the CLAWORC_ALLOWED_HOST_MOUNTS environment variable, which lists the host path prefixes that may back a folder. See Environment variables.

When CLAWORC_ALLOWED_HOST_MOUNTS is empty, the Mount to Host option is hidden in the dashboard and any host path is rejected. When it is set, you can back a folder with any host directory that resolves to a location within one of the allowed prefixes.

Creating a host-backed folder

1. Open Shared Folders in the sidebar and click New Folder.
2. Enter a name and a mount path as usual.
3. Expand the Mount to Host region.
4. Enter a Host Path. The dashboard shows the permitted prefixes and validates your entry inline. The path must resolve to a location within one of the allowed prefixes.
5. Pick an Access Mode. Read-only is the default; choose Read-write only if the instance must write back to the host directory.
6. Click Create.

If the host directory does not exist, Claworc creates it automatically (including parent directories), as long as it is within an allowed prefix.

The host path is fixed once the folder is created. You can change the access mode later, which restarts mapped running instances like any other shared-folder change.

Caution

Host bind mounts give an instance direct access to files on the host. Keep these precautions in mind:

• Prefer Read-only unless the instance must write back to the host.
• Allowed prefixes should be scoped narrowly to a dedicated shared directory, not broad roots like / or /home.
• The Docker socket and the Claworc data directory (CLAWORC_DATA_PATH) are always blocked, even if an allowed prefix would otherwise permit them.
• Paths are normalized and symlink-resolved. Paths using .. traversal or symlinks that escape an allowed prefix are rejected.

Note

On Kubernetes, a host-backed folder becomes a hostPath volume bound to the node the instance’s pod runs on. This is intended for single-node clusters. On multi-node clusters, the directory must exist with the same contents on every node the pod might run on, and symlink checks run on the control plane only — they cannot inspect node filesystems.

Deleting a shared folder

Click the delete icon on the folder row and confirm. This removes the database record and restarts any mapped running instances to unmount the volume.

The underlying storage volume is not automatically deleted as a safety measure. To reclaim storage, remove orphaned volumes manually:

• Docker: docker volume ls --filter label=type=shared-folder
• Kubernetes: kubectl get pvc -l type=shared-folder -n claworc

Kubernetes considerations

Shared folder volumes use the ReadWriteMany (RWX) access mode, which requires a storage class that supports it (for example, NFS, CephFS, or AWS EFS). If your cluster only provides ReadWriteOnce storage, two instances cannot mount the same folder simultaneously.