Docker — container/remove

When to Use

Post-job cleanup: Remove completed job containers after log collection to prevent container sprawl on the host.
Blue-green finalization: Remove the old (green) container after the new (blue) container has been verified healthy and traffic has been switched.
CI/CD teardown: Clean up test containers at the end of a CI pipeline run to keep the test host clean.
Failed deployment rollback: Remove a failed new container after stopping it so the name can be reused in the next attempt.
Ephemeral worker teardown: Remove single-use worker containers created for background tasks after their output has been collected.

This operation is irreversible. Removing a container permanently deletes it and any data written to its writable layer. Named volumes attached to the container are not removed — only the container itself and its overlay filesystem layer. Ensure all required output (logs, files) has been collected before removing.

Configuration

Connection Fields

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

Operation Fields

Field	Type	Required	Description
`resource`	string	required	Must be `container`
`operation`	string	required	Must be `remove`
`ContainerId`	string	required	Container ID (full or short) or container name

Sample Configuration

{
  "resource": "container",
  "operation": "remove",
  "ContainerId": "api-service-green",
  "connection": {
    "dockerHost": "unix:///var/run/docker.sock",
    "connectionType": "unixsocket"
  }
}

Validation Errors

Error Code	Trigger	Resolution
`MISSING_INPUT`	`ContainerId` is empty	Provide the container name or ID.
`NOT_FOUND`	Container does not exist	Container was already removed or never created. Handle as non-fatal in idempotent cleanup workflows.
`CONFLICT`	Container is still running	Call `container/stop` before `container/remove`. Running containers cannot be removed without a force flag, which is not exposed by default.
`DOCKER_API_ERROR`	Daemon error during removal	Check daemon logs. Can occur if the container is in a paused or restarting state.

Output

Success Port

Field	Type	Description
`containerId`	string	ID of the removed container
`status`	string	`success`
`resource`	string	`container`
`operation`	string	`remove`

Error Port

On failure, the error port receives errorCode, message, resource, and operation. Handle NOT_FOUND as a non-fatal condition (container already removed). Handle CONFLICT by routing to container/stop and retrying.

Sample Output

{
  "containerId": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890",
  "status": "success",
  "resource": "container",
  "operation": "remove"
}

Expression Reference

Expression	Returns
`{{ $output.containerId }}`	ID of the removed container — useful for audit log entries
`{{ $output.status }}`	`success` when removal completed

Node Policies & GuardRails

Policy	Detail
Always stop before removing	`container/remove` on a running container returns `CONFLICT`. GuardRail workflow linting warns when remove is not preceded by stop in the same workflow path.
Collect logs before removing	Use `container/logs` upstream to capture all output before removal. Post-removal log retrieval is impossible.
Volumes are not removed	Named volumes attached to the container survive removal. Use `volume/remove` explicitly if volume cleanup is also required.
Handle NOT_FOUND as non-fatal	Cleanup workflows must treat `NOT_FOUND` as success — the desired state (container absent) has already been achieved.
No remote TCP without TLS	Use `tcptls` for remote Docker hosts.

Examples

Example 1: Full cleanup sequence — logs then remove

// Node 1: container/logs — collect output before deletion
{ "resource": "container", "operation": "logs", "ContainerId": "batch-job-20240101" }

// Node 2: Store logs (e.g. S3 node or database insert)

// Node 3: container/remove
{ "resource": "container", "operation": "remove", "ContainerId": "batch-job-20240101" }

Example 2: Blue-green finalization

// After blue container verified healthy and traffic switched:
// Node 1: container/stop green
{ "resource": "container", "operation": "stop", "ContainerId": "api-service-green" }

// Node 2: container/remove green
{ "resource": "container", "operation": "remove", "ContainerId": "api-service-green" }

// Node 3: Log audit event
{ "action": "removed", "container": "api-service-green", "deployId": "{{ $trigger.deployId }}" }

Example 3: CI cleanup — remove all test containers by name prefix

// Node 1: container/list — get all containers
// Node 2: Function node — filter test containers
const testContainers = $input.listContainers.filter(
  c => c.Names.some(n => n.startsWith('/test-')) && c.State === 'exited'
);
return { containers: testContainers };

// Node 3: Loop over testContainers, for each:
{ "resource": "container", "operation": "remove", "ContainerId": "{{ $loopItem.Id }}" }