diff --git a/src/main/java/land/oras/CopyOptions.java b/src/main/java/land/oras/CopyOptions.java
new file mode 100644
index 00000000..1fc93055
--- /dev/null
+++ b/src/main/java/land/oras/CopyOptions.java
@@ -0,0 +1,57 @@
+/*
+ * Copyright The ORAS Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package land.oras;
+
+/**
+ * Options for copy operations.
+ *
+ * @param recursive true to recursively copy artifacts
+ */
+public record CopyOptions(boolean recursive) {
+
+    /**
+     * Creates a new builder for CopyOptions.
+     * @return a new builder
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Builder for CopyOptions.
+     */
+    public static class Builder {
+        private boolean recursive;
+
+        /**
+         * Sets whether to recursively copy artifacts.
+         * @param recursive true to recursively copy
+         * @return this builder
+         */
+        public Builder recursive(boolean recursive) {
+            this.recursive = recursive;
+            return this;
+        }
+
+        /**
+         * Builds the CopyOptions.
+         * @return the CopyOptions
+         */
+        public CopyOptions build() {
+            return new CopyOptions(recursive);
+        }
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/land/oras/CopyUtils.java b/src/main/java/land/oras/CopyUtils.java
index 42f4e3cc..20460649 100644
--- a/src/main/java/land/oras/CopyUtils.java
+++ b/src/main/java/land/oras/CopyUtils.java
@@ -45,12 +45,30 @@ private CopyUtils() {
     }
 
     /**
-     * Copy a container from source to target.
+     * Copy a container from source to target (Old Method - Backward Compatibility).
      * @param source The source OCI
      * @param sourceRef The source reference
      * @param target The target OCI
      * @param targetRef The target reference
      * @param recursive Whether to copy referrers recursively
+     */
+    public static <SourceRefType extends Ref<@NonNull SourceRefType>, TargetRefType extends Ref<@NonNull TargetRefType>>
+            void copy(
+                    OCI<SourceRefType> source,
+                    SourceRefType sourceRef,
+                    OCI<TargetRefType> target,
+                    TargetRefType targetRef,
+                    boolean recursive) {
+        // This converts the old boolean into your new class!
+        copy(source, sourceRef, target, targetRef, new CopyOptions(recursive));
+    }
+    /**
+     * Copy a container from source to target.
+     * @param source The source OCI
+     * @param sourceRef The source reference
+     * @param target The target OCI
+     * @param targetRef The target reference
+     * @param options The copy options
      * @param <SourceRefType> The source reference type
      * @param <TargetRefType> The target reference type
      */
@@ -60,7 +78,7 @@ void copy(
                     SourceRefType sourceRef,
                     OCI<TargetRefType> target,
                     TargetRefType targetRef,
-                    boolean recursive) {
+                    CopyOptions options) {
 
         try {
 
@@ -94,12 +112,12 @@ void copy(
                 // Push the manifest
                 target.pushManifest(targetRef.withDigest(tag), manifest);
 
-                if (recursive) {
+                if (options.isRecursive()) {
                     LOG.debug("Recursively copy referrers");
                     Referrers referrers = source.getReferrers(sourceRef.withDigest(manifestDigest), null);
                     for (ManifestDescriptor referer : referrers.getManifests()) {
                         LOG.info("Copy reference {}", referer.getDigest());
-                        copy(source, sourceRef.withDigest(referer.getDigest()), target, targetRef, recursive);
+                        copy(source, sourceRef.withDigest(referer.getDigest()), target, targetRef, options);
                     }
                 }