diff --git a/README.md b/README.md
index 25e4895f..a06fc651 100644
--- a/README.md
+++ b/README.md
@@ -478,3 +478,4 @@ yq ".a.b[0].c = \"value\"" file.yaml
 - "yes", "no" were dropped as boolean values in the yaml 1.2 standard - which is the standard yq assumes.
 
 See [tips and tricks](https://mikefarah.gitbook.io/yq/usage/tips-and-tricks) for more common problems and solutions.
+
diff --git a/action.yml b/action.yml
index 3ff32f57..bca3a606 100644
--- a/action.yml
+++ b/action.yml
@@ -1,17 +1,105 @@
-name: 'yq - portable yaml processor'
-description: 'create, read, update, delete, merge, validate and do more with yaml'
+name: "yq - portable yaml processor"
+description: "create, read, update, delete, merge, validate and do more with yaml"
 branding:
   icon: command
   color: gray-dark
 inputs:
+  image:
+    description: 'Container image to run. Example: "mikefarah/yq:4-githubaction" or fully qualified "artifacts.example.com/repo/mikefarah/yq:4-githubaction".'
+    required: false
+    default: "mikefarah/yq:4-githubaction"
+  registry:
+    description: "Optional artifact repository hostname to prefix the `image`. Leave empty if your `image` already includes a registry."
+    required: false
+    default: ""
+  registry_username:
+    description: "Optional registry username for `docker login` (use with `registry_password`)."
+    required: false
+    default: ""
+  registry_password:
+    description: "Optional registry password for `docker login` (use with `registry_username`). Pass secrets via workflow `with:` from secrets."
+    required: false
+    default: ""
   cmd:
-    description: 'The Command which should be run'
+    description: "The Command which should be run"
     required: true
+runs:
+  using: "composite"
+  steps:
+    - id: pull-with-credentials
+      name: Pull image using provided credentials
+      if: ${{ inputs.registry_username && inputs.registry_password && inputs.registry }}
+      shell: bash
+      env:
+        IMAGE_INPUT: ${{ inputs.image }}
+        REGISTRY: ${{ inputs.registry }}
+        REG_USER: ${{ inputs.registry_username }}
+        REG_PASS: ${{ inputs.registry_password }}
+      run: |
+        set -euo pipefail
+        IMAGE="$IMAGE_INPUT"
+        if [ -n "$REGISTRY" ]; then
+          REG="${REGISTRY%/}"
+          IMAGE="$REG/$IMAGE"
+        fi
+        echo "Using image: $IMAGE"
+        echo "Credentials provided; attempting docker login to $REGISTRY"
+        if [ -n "$REG_PASS" ]; then
+          echo "::add-mask::$REG_PASS"
+        fi
+        echo "$REG_PASS" | docker login "$REGISTRY" --username "$REG_USER" --password-stdin
+        if docker pull "$IMAGE" >/dev/null 2>&1; then
+          echo "Image pulled successfully after login."
+        else
+          echo "Failed to pull image after login; proceeding to run (docker run may fail)."
+        fi
+
+    - id: pull-anonymous
+      name: Pull image anonymously
+      if: ${{ !(inputs.registry_username && inputs.registry_password && inputs.registry) }}
+      shell: bash
+      env:
+        IMAGE_INPUT: ${{ inputs.image }}
+        REGISTRY: ${{ inputs.registry }}
+      run: |
+        set -euo pipefail
+        IMAGE="$IMAGE_INPUT"
+        if [ -n "$REGISTRY" ]; then
+          REG="${REGISTRY%/}"
+          IMAGE="$REG/$IMAGE"
+        fi
+        echo "Using image: $IMAGE"
+        echo "No credentials provided (or registry not set); attempting anonymous pull"
+        if docker pull "$IMAGE" >/dev/null 2>&1; then
+          echo "Anonymous pull succeeded."
+        else
+          echo "Anonymous pull failed; proceeding to run (docker run may fail if auth required)."
+        fi
+
+    - id: run
+      name: Run yq container
+      shell: bash
+      env:
+        IMAGE_INPUT: ${{ inputs.image }}
+        REGISTRY: ${{ inputs.registry }}
+        CMD_INPUT: ${{ inputs.cmd }}
+      run: |
+        set -euo pipefail
+        IMAGE="$IMAGE_INPUT"
+        if [ -n "$REGISTRY" ]; then
+          REG="${REGISTRY%/}"
+          IMAGE="$REG/$IMAGE"
+        fi
+        echo "Using image: $IMAGE"
+        RC=0
+        OUTPUT=$(docker run --rm -v "$GITHUB_WORKSPACE":/work -w /work "$IMAGE" sh -lc "$CMD_INPUT" 2>&1) || RC=$?
+        echo "result<<EOF" >> $GITHUB_OUTPUT
+        echo "$OUTPUT" >> $GITHUB_OUTPUT
+        echo "EOF" >> $GITHUB_OUTPUT
+        if [ "$RC" -ne 0 ]; then
+          exit "$RC"
+        fi
 outputs:
   result:
     description: "The complete result from the yq command being run"
-runs:
-  using: 'docker'
-  image: 'docker://mikefarah/yq:4-githubaction'
-  args:
-    - ${{ inputs.cmd }}
+    value: ${{ steps.run.outputs.result }}