Shared Directories - PolarDB - Alibaba Cloud Documentation Center

Feature overview

In large-scale AI agent deployments, each agent mounts an isolated subdirectory with --subdir for data isolation. However, multiple agents often need to access the same resources, such as shared skill libraries, knowledge bases, or common dependencies. Traditional approaches come with significant trade-offs:

Traditional approach	Problem
Copy resources into each agent at startup	Creates N redundant copies of data. Updates require redistribution to every agent, causing version drift. Copying large directories slows down startup.
Mount a separate mount point for shared resources	Each agent requires an additional FUSE process and a set of metadata database connections, leading to significant resource waste at scale.

Shared directories solve these problems with the --bind parameter, providing the following capabilities:

Zero data copying: The shared directory is stored only once at the storage layer. All mount points see the same data.
Real-time consistency: Updates to the source directory are immediately visible to all consumers, subject to client cache configuration.
Access control: Full POSIX permission management for flexible read/write control across agents.
Automatic lifecycle management: Bindings are created at mount time and automatically cleaned up at unmount.

Scope

You have Create a PolarDB Agent LakeBase.
The source path (the directory to share) already exists in the volume.
The target path (the mapping destination) does not yet exist in the volume, and it is located under the directory specified by --subdir.

Usage

Use the --bind parameter during mount to map shared directories to target paths:

lakebase-client mount <META_URL> <MOUNT_POINT> --subdir <SUB_DIR> \
    --bind <SOURCE_PATH>:<TARGET_PATH>[,<SOURCE_PATH>:<TARGET_PATH>...]

Parameter	Description
Source path	The absolute path of an existing directory in the volume.
Target path	The absolute path for the mapping destination. This directory must not yet exist in the volume and must be located under the directory specified by `--subdir`.

Access control

Use POSIX permissions to control read/write access to shared directories:

Read-only access: Set the shared directory owner to an admin user with permissions 0755 (owner has read/write access; all other users have read-only access).
Read/write access: Make the shared directory group-writable and add the agent to that group.

Important

Read-only protection requires the agent to run as a non-root user. The root user (uid 0) bypasses permission checks.

Common scenarios

Share skills and knowledge bases

Multiple agents run in isolation using --subdir, but need to access a common set of global skills and a shared knowledge base maintained by an administrator. Agents consume these resources in read-only mode.

Procedure:

The administrator creates shared content and sets it to read-only.

lakebase-client mount <META_URL> <MOUNT_POINT>
mkdir -p <MOUNT_POINT>/shared/skills <MOUNT_POINT>/shared/knowledge-base
cp -r /path/to/skills/* <MOUNT_POINT>/shared/skills/
cp -r /path/to/knowledge/* <MOUNT_POINT>/shared/knowledge-base/
chown -R admin:admin <MOUNT_POINT>/shared
chmod -R 755 <MOUNT_POINT>/shared
lakebase-client umount <MOUNT_POINT>

Each agent mounts its isolated subdirectory and binds the shared directories.

lakebase-client mount <META_URL> <MOUNT_POINT> --subdir /agents/agent-x \
    --bind /shared/skills:/agents/agent-x/skills,/shared/knowledge-base:/agents/agent-x/knowledge-base

The agent sees the following directory structure:

<MOUNT_POINT>/
├── skills/            ← Shared read-only, from /shared/skills
├── knowledge-base/    ← Shared read-only, from /shared/knowledge-base
└── workspace/         ← Agent's private writable workspace

Share npm dependencies

Each agent runs npm install to install a large set of dependencies into node_modules at startup, even though most dependencies are identical across agents. A typical node_modules directory contains tens to hundreds of thousands of small files. Each file write incurs a fixed overhead at the underlying object storage layer, and this overhead scales linearly with the number of files. Sharing a single set of common dependencies across agents significantly reduces redundant installations and shortens agent startup times.

Note

The following examples use npm, but the same approach applies to other package managers.

The right approach depends on a key question: Does the agent need to write to node_modules at runtime?

No (dependencies are fixed, maintained by an administrator, and consumed by agents): Use shared directories (read-only).
Yes (each agent installs additional packages at runtime and requires isolation): Use Clone (copy-on-write).

Option 1: Read-only common dependencies (shared directories)

When to use:

Dependencies are determined before agent startup and do not change at runtime.
An administrator or CI pipeline generates and maintains them.
Multiple agents use the same set (or a small number of fixed sets) of dependencies.

How it works: Common dependencies are materialized once. Multiple agents bind the same copy in read-only mode, completely skipping npm install. This eliminates the overhead of each agent materializing tens of thousands of small files, enabling instant startup with zero installation.

Procedure:

The administrator builds the common dependencies (one-time operation).

lakebase-client mount <META_URL> <MOUNT_POINT>
mkdir -p <MOUNT_POINT>/shared/npm-base/v1
cd <MOUNT_POINT>/shared/npm-base/v1 && npm install next ...
chown -R admin:admin <MOUNT_POINT>/shared/npm-base
chmod -R 755 <MOUNT_POINT>/shared/npm-base
lakebase-client umount <MOUNT_POINT>

Each agent binds the read-only common dependencies.

lakebase-client mount <META_URL> <MOUNT_POINT> --subdir /agents/agent-x \
    --bind /shared/npm-base/v1/node_modules:/agents/agent-x/node_modules

The agent sees the following directory structure:

<MOUNT_POINT>/
├── node_modules/      ← Shared read-only common dependencies, from /shared/npm-base/v1
└── workspace/         ← Agent's private writable workspace

Option 2: Common dependencies with runtime additions (Clone)

When to use: A common set of dependencies exists, but each agent also installs additional packages at runtime, and the changes made by each agent must remain isolated from other agents.

In this case, use Clone (copy-on-write): Each agent clones an independent, writable copy from the template project. Common dependencies are shared with the base and do not incur additional storage. When each agent installs incremental packages on its own copy, only the new or modified portions write new data blocks, so agents do not interfere with each other. For detailed principles and procedures (including the two methods when mounting with --subdir: "Bind first, then clone locally" and "Clone through the OpenAPI"), see Clone Directories - Shared dependencies plus runtime extra installs.

Notes

The source path must be an existing directory in the volume. The target path must not yet exist, and it must be located under the directory specified by --subdir.
Shared directories are established at mount time and automatically cleaned up at unmount. They must be re-specified with --bind on each mount.
All consumers see the same underlying data. Modifications to the source directory are visible to consumers. The freshness of updates depends on the client cache configuration.
Read-only protection relies on POSIX permissions and requires the agent to run as a non-root user. The root user (uid 0) bypasses permission checks.
A shared directory is protected during binding. As long as any mount session still binds the directory through --bind, the directory cannot be deleted (rmdir) or renamed (rename) from either the source path or the bind target path. Such operations return an EBUSY error. You can delete or rename the directory only after all mounts that bind it have been unmounted.