Docker — image/remove

Stopped containers: Removing an image used by a stopped (but not removed) container returns a CONFLICT error. The workflow must remove those containers with container/remove first, or use a container/list + filter step to confirm no containers reference the image.

When to Use

Post-deployment cleanup: After confirming the new application version is healthy, remove the previous image tag from the host to reclaim disk space.
Dangling image cleanup: Run a weekly workflow that calls image/list, filters for images with empty RepoTags, and removes each dangling image.
Storage quota enforcement: Remove images that have not been used in the last 30 days based on creation timestamp, as part of a capacity management workflow.
CI/CD teardown: Remove build images after a CI pipeline completes to prevent unbounded image accumulation on shared build agents.
Security remediation: Immediately remove images flagged with critical CVEs by a vulnerability scanning workflow.

Configuration

Connection

Field	Type	Default	Description
`dockerHost`	string	`unix:///var/run/docker.sock`	Docker daemon socket path or TCP endpoint.
`connectionType`	string	`unixsocket`	One of: `unixsocket`, `tcp`, `tcptls`.
`tlsCertPath`	string	—	TLS certificate directory. Required for `tcptls`. optional
`timeoutSeconds`	int	30	Operation timeout in seconds. optional

Operation Fields

Field	Type	Badge	Description
`Repository`	string	required	Image name with tag or full image ID to remove (e.g., `nginx:1.24`, `sha256:a3562aa…`).

Sample Configuration

{
  "resource": "image",
  "operation": "remove",
  "connection": {
    "dockerHost": "unix:///var/run/docker.sock",
    "connectionType": "unixsocket"
  },
  "Repository": "myapp:v1.9.0"
}

Validation Errors

Error Code	Condition	Resolution
`MISSING_INPUT`	`Repository` field is empty.	Provide the image name, tag, or ID to remove.
`NOT_FOUND`	The specified image does not exist on the host.	Verify the image name. Use `image/list` to confirm it is present.
`CONFLICT`	The image is referenced by one or more containers (running or stopped).	Remove or force-remove dependent containers with `container/remove` first.
`CONFIG_ERROR`	Connection settings malformed.	Check `dockerHost` and `connectionType`.
`DOCKER_API_ERROR`	Unexpected daemon error.	Check Docker daemon logs on the host.

Output

Success Port

Field	Type	Description
`status`	string	`"ok"` when the image is removed successfully.
`resource`	string	`"image"`
`operation`	string	`"remove"`
`repository`	string	The image reference that was removed.

Error Port

Fires when removal fails. Output contains status: "error", errorCode (commonly CONFLICT or NOT_FOUND), and errorMessage.

Sample Output

{
  "status": "ok",
  "resource": "image",
  "operation": "remove",
  "repository": "myapp:v1.9.0"
}

Expression Reference

Expression	Returns
`{{ $output.status }}`	`"ok"` — use to confirm removal before logging cleanup audit event.
`{{ $output.repository }}`	The removed image reference — include in audit log or notification.
`{{ $output.errorCode }}`	`"CONFLICT"` or `"NOT_FOUND"` — route the error port based on this value.

Node Policies & GuardRails

Policy	Enforcement
Never expose Docker daemon TCP without TLS	Use `tcptls` for remote connections. Plain `tcp` is blocked in production GuardRail profiles.
Store TLS certificates in Credentials Manager	Reference `tlsCertPath` via `{{ $credentials.dockerTlsCertPath }}`.
Stop and remove containers before removing images	Always call `container/stop` and `container/remove` for any container using the image before calling `image/remove`.
Never interpolate user input into the Repository field	Image references must come from trusted variables, not user-supplied input.
Always handle the error port	Wire the error port to an alerting node — CONFLICT errors indicate live containers are still dependent on the image.
Restrict container/exec to approved commands	Arbitrary exec access is root-equivalent. GuardRail exec policies restrict allowed command prefixes.

Examples

Example 1 — Post-Deployment Old Image Removal

After a deployment workflow completes and the new container is healthy, remove the previous versioned image to free disk space.

// After container/start and health check pass:
{
  "resource": "image",
  "operation": "remove",
  "Repository": "{{ $vars.previousImageTag }}"
}
// e.g., previousImageTag = "myapp:v2.2.0"

Example 2 — Dangling Image Cleanup Workflow

List all images, filter for dangling ones (empty RepoTags), then loop through and remove each.

// Step 1 — image/list (no fields needed)
// Step 2 — Filter node: keep items where RepoTags.length === 0
// Step 3 — Loop: for each dangling image, call image/remove
{
  "resource": "image",
  "operation": "remove",
  "Repository": "{{ $loopItem.Id }}"
}

Example 3 — Security Remediation: Remove CVE-Flagged Image

A vulnerability scan workflow emits the image ID of a critically-affected image. Immediately remove it from all hosts before any new containers can be started from it.

{
  "resource": "image",
  "operation": "remove",
  "Repository": "{{ $trigger.affectedImageId }}"
}
// On success: post alert to Slack "Image {{ $output.repository }} removed from host"
// On error (CONFLICT): escalate — running container still uses the vulnerable image