scriptling.container

The scriptling.container library provides container lifecycle management for Docker, Podman, and Apple Containers through a unified interface. All operations go through a ContainerClient obtained from Client().

Registration

import "github.com/paularlott/scriptling/extlibs/container"

container.Register(p)

Endpoint Configuration

Docker and Podman endpoints are configured via the --docker-host / --podman-host CLI flags or the DOCKER_HOST / CONTAINER_HOST environment variables. See CLI Basic Usage for details.

Module Functions

ContainerClient Methods

Functions

container.runtimes()

Returns the names of container runtimes that are currently installed and running on this system.

Returns: list of strings — subset of ["docker", "podman", "apple"]

import scriptling.container as container

available = container.runtimes()
print("Available runtimes:", available)

container.Client(driver, **kwargs)

Creates a ContainerClient for the specified runtime.

Parameters:

• driver (string): Runtime to use — "docker", "podman", or "apple"
• socket (string, optional): Override the endpoint. Accepts a Unix socket path, unix:// URI, tcp:// address, or https:// address (docker/podman only). Defaults to DOCKER_SOCK / PODMAN_SOCK env vars, then the built-in defaults.

Returns: ContainerClient

# Local Docker (default socket)
c = container.Client("docker")

# Docker via Lima or custom socket
c = container.Client("docker", socket="unix:///Users/paul/.lima/docker/sock/docker.sock")

# Remote Docker daemon over TCP
c = container.Client("docker", socket="tcp://192.168.1.10:2375")

# Remote Docker over TLS
c = container.Client("docker", socket="https://192.168.1.10:2376")

# Local Podman (default socket)
c = container.Client("podman")

# Podman with user-scoped socket
c = container.Client("podman", socket="unix:///run/user/1000/podman/podman.sock")

# Apple Containers
c = container.Client("apple")

ContainerClient

driver()

Returns the name of the active runtime driver.

Returns: str — "docker", "podman", or "apple"

image_pull(image)

Pulls an image from a registry.

Parameters:

• image (string): Image reference e.g. "ubuntu:24.04"

c.image_pull("ubuntu:24.04")

image_list()

Lists locally available images.

Returns: list of dicts with keys:

• id (str): Image ID (digest for Apple, full ID for Docker/Podman)
• reference (str): Image reference e.g. "ubuntu:24.04"
• digest (str): Content digest e.g. "sha256:abc123..."
• size (int): Manifest/layer size in bytes

for img in c.image_list():
    print(img["reference"], img["digest"])

image_remove(image)

Removes a local image.

Parameters:

• image (string): Image reference e.g. "ubuntu:24.04"

c.image_remove("ubuntu:24.04")

exec(name_or_id, command, **kwargs)

Runs a command inside an already-running container and captures the full output.

Parameters:

• name_or_id (string): Container name or ID
• command (list): Command and arguments e.g. ["/bin/sh", "-c", "echo hi"]
• env (list, optional): Environment variables e.g. ["KEY=value"]
• workdir (string, optional): Working directory inside the container
• user (string, optional): User to run as e.g. "root" or "1000:1000"

Returns: dict with keys:

• stdout (str): Captured standard output
• stderr (str): Captured standard error
• exit_code (int): Process exit code

result = c.exec("app", ["/bin/sh", "-c", "cat /etc/os-release"])
print(result["stdout"])
print("exit:", result["exit_code"])

exec_stream(name_or_id, command, callback, **kwargs)

Runs a command inside an already-running container and calls callback(stream, line) for each line of output as it arrives. stream is "stdout" or "stderr".

Parameters:

• name_or_id (string): Container name or ID
• command (list): Command and arguments
• callback (callable): Function called with (stream, line) for each output line
• env (list, optional): Environment variables e.g. ["KEY=value"]
• workdir (string, optional): Working directory inside the container
• user (string, optional): User to run as

Returns: dict with exit_code (int). stdout and stderr are empty strings — output was delivered to the callback.

def on_line(stream, line):
    print(f"[{stream}] {line}")

result = c.exec_stream("app", ["/bin/sh", "-c", "for i in 1 2 3; do echo $i; done"], on_line)
print("exit:", result["exit_code"])

run(image, **kwargs)

Creates and starts a container.

Parameters:

• image (string): Image reference e.g. "ubuntu:24.04"
• name (string, optional): Container name
• ports (list, optional): Port mappings e.g. ["8080:80"]
• env (list, optional): Environment variables e.g. ["KEY=value"]
• volumes (list, optional): Volume mounts e.g. ["mydata:/data"]
• command (list, optional): Override command e.g. ["/bin/sh", "-c", "echo hi"]
• network (string, optional): Network name
• privileged (bool, optional): Run privileged. Default: False

Returns: str — container ID

id = c.run(
    "ubuntu:24.04",
    name="app",
    ports=["8080:80"],
    env=["DEBUG=1"],
    volumes=["mydata:/data"],
)

stop(name_or_id)

Stops a running container gracefully.

Parameters:

• name_or_id (string): Container name or ID

c.stop("app")

remove(name_or_id)

Removes a stopped container.

Parameters:

• name_or_id (string): Container name or ID

c.remove("app")

inspect(name_or_id)

Returns details about a container.

Parameters:

• name_or_id (string): Container name or ID

Returns: dict with keys:

• id (str): Container ID
• name (str): Container name
• status (str): Current status e.g. "running", "exited"
• image (str): Image reference
• running (bool): True if the container is currently running

info = c.inspect("app")
print(info["status"])
print(info["running"])

list()

Lists all containers (running and stopped).

Returns: list of dicts, each with the same keys as inspect()

for item in c.list():
    print(item["name"], item["status"])

volume_create(name)

Creates a named volume.

Parameters:

• name (string): Volume name

c.volume_create("mydata")

volume_remove(name)

Removes a named volume.

Parameters:

• name (string): Volume name

c.volume_remove("mydata")

volume_list()

Lists all named volumes.

Returns: list of volume name strings

for v in c.volume_list():
    print(v)

Full Example

import scriptling.container as container

c = container.Client("docker")

# Create a volume and run a one-shot ubuntu container
c.volume_create("demo-data")
c.image_pull("ubuntu:24.04")

id = c.run(
    "ubuntu:24.04",
    name="demo",
    volumes=["demo-data:/data"],
    env=["GREETING=hello"],
    command=["/bin/bash", "-c", "echo $GREETING > /data/out.txt"],
)

info = c.inspect("demo")
print(f"Status: {info['status']}")

# Execute a command in the running container
result = c.exec("demo", ["/bin/bash", "-c", "cat /data/out.txt"])
print(result["stdout"])

# Cleanup
c.stop("demo")
c.remove("demo")
c.volume_remove("demo-data")
c.image_remove("ubuntu:24.04")