fn_registry/functions/infra/docker_container_list.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path, params, output

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path	params	output
docker_container_list	function	go	infra	1.0.0	impure	func DockerContainerList(opts DockerContainerListOpts) ([]DockerContainerInfo, error)	Lista containers Docker del host via engine API (unix socket o TCP). Sin SDK pesado — net/http directo. Soporta filtros, All=true para exited. Usado por device_agent como capability docker.container.list.	docker docker-agent container list infra		error_go_core docker_container_info_go_infra	docker_container_info_go_infra	false	error_go_core	context encoding/json fmt io net net/http net/url strings time	true	lista solo running All=true incluye exited filter label aplica	functions/infra/docker_container_list_test.go	functions/infra/docker_container_list.go	name desc opts DockerContainerListOpts — All (incluir exited), Filters (expresiones label=k=v / status=running), DockerHost (unix socket o tcp://host:port)	Slice de DockerContainerInfo con id, names, image, state, ports, networks para cada container.

Ejemplo

// Listar solo containers corriendo con un label específico
containers, err := DockerContainerList(infra.DockerContainerListOpts{
    Filters:    []string{"label=app=agents_and_robots"},
    DockerHost: "unix:///var/run/docker.sock",
})
if err != nil {
    log.Fatal(err)
}
for _, c := range containers {
    fmt.Printf("%s  %-20s  %s  %s\n", c.ID, c.Names[0], c.State, c.Status)
}

// Todos los containers (incluye exited) en host remoto
all, err := DockerContainerList(infra.DockerContainerListOpts{
    All:        true,
    DockerHost: "tcp://192.168.1.10:2375",
})

Cuando usarla

Cuando necesites listar containers Docker desde un agente o servicio sin depender del CLI docker instalado en el host — por ejemplo, al implementar la capability docker.container.list en un device_agent que recibe comandos desde Element/Matrix. También útil en tests y en entornos donde el binario docker no está en el PATH pero el socket sí es accesible.

Gotchas

• Requiere acceso al docker socket. El proceso debe correr como root o en el grupo docker. En WSL2, el socket está en /var/run/docker.sock si Docker Desktop está activo.
• Ports puede estar vacío para containers en host network mode (--network host) — el engine no reporta port bindings en ese caso.
• Para acceso remoto sin TLS (tcp://), el daemon Docker debe tener -H tcp://0.0.0.0:2375 habilitado explícitamente (deshabilitado por defecto por seguridad). Usar SSH tunnel o TLS para producción.
• DockerHost acepta unix:// y tcp:// solamente. Esquemas https:// o ssh:// retornan error.
• El campo Names incluye el slash inicial: ["/my-container"]. Al mostrar al usuario, usar strings.TrimPrefix(name, "/").
• Filters del tipo label=k=v incluyen el segundo = en el valor (el split es en el primer =). Para filtrar por presencia de label sin valor: "label=app".

Notas

Implementa la misma semántica que GET /containers/json del Docker Engine API v1.41+. No requiere el SDK github.com/docker/docker (evita ~50 MB de dependencias transitivas). El helper dockerListHTTPClient maneja la dialección unix socket requerida por net/http.