All Products
Search

This Product

    PolarDB:PolarDB Agent LakeBase Directory Clone

    Document Center

    PolarDB:PolarDB Agent LakeBase Directory Clone

    Last Updated:Jul 13, 2026

    The clone feature of PolarDB Agent LakeBase uses copy-on-write (COW) to create an independent copy of an existing directory or file in the volume within seconds. Only metadata is copied; the underlying data blocks are shared with the source through reference counting and consume no additional storage. The copy is independent, complete, and writable, and changes to the source and the copy do not affect each other. Clone fits use cases such as workspace versioning, state rollback, and fast initialization from templates. PolarDB Agent LakeBase provides two ways to clone: OpenAPI and the command-line tool lakebase-client.

    Features

    Clone is the second-level directory snapshot capability of PolarDB Agent LakeBase. It has the following features:

    • Fast: Only metadata is copied; data blocks are not duplicated. The time to clone depends on the number of files and subdirectories, not on the data volume. A directory of typical size can be cloned within seconds, much faster than byte-by-byte copy such as cp.

    • Zero additional storage: The underlying data blocks of the copy are shared with the source through reference counting. Common data is stored only once and is not duplicated by clone.

    • Independent and writable, copy-on-write: The copy is a complete, independent, and writable directory tree. When the source or any copy is written, only the new or modified blocks are persisted; the unchanged blocks remain shared. The source and each copy do not affect each other.

    Prerequisites

    • You have Create a PolarDB Agent LakeBase.

    • The source path (the file or directory to be cloned) already exists in the volume.

    • If you use OpenAPI, you have obtained the MetaURL from the basic information page of your PolarDB Agent LakeBase instance. If you use the command-line tool, you have mounted PolarDB Agent LakeBase.

    Usage

    Use OpenAPI to clone

    OpenAPI does not require mounting. You can clone by specifying the source path and the target path directly. This is suitable for server-side scenarios such as Agent orchestration and automation pipelines.

    Clone: ClonePolarFsBasicSnapshot.

    Use the command-line tool to clone

    Prepare

    Download the lakebase-client tool and mount PolarDB Agent LakeBase.

    curl -o lakebase-client https://lakebase-client.oss-cn-beijing.aliyuncs.com/lakebase-client-latest
chmod +x lakebase-client

    Clone

    Inside a mounted directory, clone the source path to the target path:

    lakebase-client clone <SRC> <DST>

    For example, clone a template project as an independent, writable copy:

    lakebase-client clone /mnt/pfs/templates/project-base /mnt/pfs/project-x

    Parameters

    Parameter

    Description

    SRC

    The source path to be cloned. It must be an existing file or directory inside the mount point. The user that runs clone must have read permission on this path.

    DST

    The target path of the copy. It must be in the same mount point as SRC. Its parent directory must already exist, the target itself must not exist, and it must not be under SRC. If DST ends with /, it is treated as a directory and the name of SRC is appended automatically.

    --preserve, -p

    Preserve the uid, gid, and mode of the source. If not specified, the copy is owned by the user who runs the command, and the mode follows the current umask.

    Typical use cases

    Version management and state rollback

    An Agent that continuously modifies the workspace across many turns needs to save rollback points at key milestones. Clone creates per-second snapshots of the workspace directory, so you can return to any historical version after a mistake or for comparison. Because clone only copies metadata and consumes no additional storage, you can keep low-cost snapshots for every important milestone.

    # Snapshot the workspace at a milestone
lakebase-client clone /mnt/pfs/agents/agent-x/workspace /mnt/pfs/agents/agent-x/snapshots/v1

    Fast workspace initialization (clone from a template)

    When a new Agent comes online, it needs to set up a working environment quickly, such as the project template, skill files, and preinstalled dependencies. Cloning a prebuilt template directory to the new Agent finishes initialization within seconds. Only metadata is copied and no actual data is duplicated, which greatly reduces startup latency and storage overhead.

    # Initialize the new Agent workspace from a template within seconds
lakebase-client clone /mnt/pfs/templates/agent-base /mnt/pfs/agents/agent-x

    Shared dependencies plus runtime extra installs

    There is a common set of dependencies (such as node_modules), but each Agent must still install extra packages at runtime, and the changes must be isolated from each other. In this case, use clone: clone an independent copy from the template project so that the common dependencies are shared with the base and consume no extra storage. When each Agent installs incremental packages on its copy, only the new or modified blocks are persisted to new data blocks, and the Agents do not affect each other.

    Note

    This case corresponds to Share npm dependencies in the Shared Directories topic. If dependencies are fixed and Agents only consume them read-only, use shared directories (read-only bind). If each Agent installs extra packages at runtime and must remain isolated, use clone as described in this section.

    Procedure:

    1. The administrator builds the template project (a one-time operation).

      lakebase-client mount <META_URL> <MOUNT_POINT>
mkdir -p <MOUNT_POINT>/shared/npm-template/v1
cd <MOUNT_POINT>/shared/npm-template/v1 && npm install next ...
lakebase-client umount <MOUNT_POINT>

    2. An Agent mounts with --subdir and then clones the template project. Because the Agent mounts with --subdir, it cannot see the template directory outside subdir. There are two ways to clone:

      1. Option 1: Use OpenAPI

        Call ClonePolarFsBasicSnapshot directly with the source and target paths.

      2. Option 2: Bind first, then clone locally

        lakebase-client mount <META_URL> <MOUNT_POINT> --subdir /agents/agent-x \
    --bind /shared/npm-template/v1:/agents/agent-x/.npm-template
lakebase-client clone <MOUNT_POINT>/.npm-template <MOUNT_POINT>/project-x
        Note

        Clone the entire template project directory rather than only node_modules. Otherwise, the subsequent npm install has no manifest to work with.

    3. The Agent installs extra dependencies on the cloned copy.

      cd <MOUNT_POINT>/project-x && npm install <extra-packages>

    Notes

    • SRC and DST must be in the same mount point. The parent directory of DST must already exist, the target itself must not exist, and it must not be under SRC.

    • Clone only copies metadata and shares data blocks with the source, so clone itself does not consume additional storage. The new data blocks generated by subsequent writes on the copy consume storage based on the actual write volume.

    • When mounted with --subdir, the command-line clone cannot see directories outside subdir. You must first map the source in through --bind, or use OpenAPI to clone.