Persistence¶

By default, containers are ephemeral — they are removed when shutdown() is called or the context manager exits. Persistence features let you stop, resume, snapshot, and manage containers across sessions.

Persistent Containers¶

Create a container that survives shutdown():

from pocketdock import create_new_container

c = create_new_container(persist=True, name="my-sandbox")
c.run("echo setup done")
c.shutdown()  # Stops the container, but does NOT remove it

Resume¶

Resume a stopped persistent container by name:

from pocketdock import resume_container

c = resume_container("my-sandbox")
result = c.run("echo I'm back")
print(result.stdout)  # "I'm back\n"

The container's filesystem state is preserved from the previous session.

List Containers¶

List all pocketdock managed containers (running and stopped):

from pocketdock import list_containers

containers = list_containers()
for item in containers:
    print(f"{item.name}: {item.status} (persist={item.persist})")

Each item is a ContainerListItem with:

Field	Type	Description
`id`	`str`	Container ID
`name`	`str`	Container name
`status`	`str`	`"running"` or `"exited"`
`image`	`str`	Image tag
`created_at`	`str`	ISO creation timestamp
`persist`	`bool`	Whether the container is persistent
`project`	`str`	Associated project name

Filter by project:

containers = list_containers(project="my-project")

Stop¶

Stop a running container without removing it:

from pocketdock import stop_container

stop_container("my-sandbox")

Destroy¶

Permanently remove a container regardless of its persist setting:

from pocketdock import destroy_container

destroy_container("my-sandbox")

If the container has an associated instance directory (from project management), it is also cleaned up.

Prune¶

Remove all stopped pocketdock managed containers:

from pocketdock import prune

count = prune()
print(f"Removed {count} containers")

Filter by project:

count = prune(project="my-project")

Snapshot¶

Commit the container's current filesystem as a reusable image:

c = create_new_container(persist=True, name="my-sandbox")
c.run("pip install requests")
image_id = c.snapshot("my-sandbox:with-requests")

Create new containers from the snapshot:

c2 = create_new_container(image="my-sandbox:with-requests")

Volumes¶

Mount host directories for data that should persist independently of the container:

c = create_new_container(
    volumes={"/host/data": "/container/data"}
)

Volume changes are written directly to the host filesystem and survive container removal.

Socket Path¶

All persistence functions accept an optional socket_path parameter to target a specific engine:

containers = list_containers(socket_path="/path/to/docker.sock")