ContainerClientMixin

Mixin providing container management endpoints for Docker container lifecycle operations.

Overview

The ContainerClientMixin provides methods for managing Docker containers on agents. It supports creating, listing, and removing containers that run plugin releases.

Methods

list_docker_containers

List all Docker containers on the host.

from synapse_sdk.clients.agent import AgentClient

client = AgentClient(base_url="https://agent.example.com")

containers = client.list_docker_containers()
for container in containers:
    print(f"Container: {container['id']} - {container['status']}")

Returns: list[dict] - List of container information dictionaries.

---

get_docker_container

Get a specific Docker container by ID.

container = client.get_docker_container("abc123def456")
print(f"Status: {container['status']}")

Parameters:

Parameter	Type	Description
container_id	str	Docker container ID

Returns: dict - Container details.

---

create_docker_container

Build and run a Docker container for a plugin release.

from synapse_sdk.clients.agent import AgentClient

client = AgentClient(base_url="https://agent.example.com")

container = client.create_docker_container(
    plugin_release="[email protected]",
    params={"input": "data"},
    envs={"DEBUG": "true"},
    metadata={"created_by": "automation"},
    labels=["production", "ml-model"]
)

print(f"Container ID: {container['id']}")

Parameters:

Parameter	Type	Required	Description
plugin_release	str	Yes	Plugin identifier (e.g., plugin_code@version)
params	dict	No	Parameters forwarded to the plugin
envs	dict	No	Environment variables for the container
metadata	dict	No	Additional metadata stored with the record
labels	list[str]	No	Container labels for display/filtering
kind	str	No	Container kind forwarded to the agent (plugin_runtime or code_server); agent defaults to plugin_runtime when omitted
backend_container_id	int	No	Backend SSOT Container row id, forwarded so the agent can back-reference the originating record

Returns: dict - Created container information.

---

delete_docker_container

Stop and remove a Docker container.

client.delete_docker_container("abc123def456")

Parameters:

Parameter	Type	Description
container_id	str	Docker container ID

---

Database Container Records

In addition to Docker operations, this mixin provides methods for managing container records in the database.

list_containers

List tracked containers from the database.

containers, total = client.list_containers(
    params={"status": "running"},
    list_all=True
)

Parameters:

Parameter	Type	Description
params	dict	Filter parameters
list_all	bool	Fetch all pages automatically

Returns: dict or tuple[list, int] - Container list (with total count if list_all=True).

---

get_container

Get a tracked container by database ID.

container = client.get_container(42)

Parameters:

Parameter	Type	Description
container_id	int	Database container ID

Returns: dict - Container details.

---

update_container

Update a tracked container's status.

updated = client.update_container(42, status="stopped")

Parameters:

Parameter	Type	Description
container_id	int	Database container ID
status	str	New status value

Returns: dict - Updated container details.

---

delete_container

Delete a tracked container (also stops the Docker container).

client.delete_container(42)

Parameters:

Parameter	Type	Description
container_id	int	Database container ID

---

Usage with AgentClient

The ContainerClientMixin is used by AgentClient:

from synapse_sdk.clients.agent import AgentClient

client = AgentClient(
    base_url="https://agent.example.com",
    access_token="your-token"
)

# Create a container for a plugin
container = client.create_docker_container(
    plugin_release="[email protected]",
    params={"format": "pdf"},
    envs={"WORKERS": "4"}
)

# Monitor the container
status = client.get_docker_container(container["docker_id"])
print(f"Running: {status['running']}")

# Clean up
client.delete_docker_container(container["docker_id"])

---

See Also

• PluginClientMixin - Plugin release management
• AgentClient - Agent client overview