Containers

Overview

The ContainersClient lets you run temporary containers inside a room. Use it for one-off jobs, debugging, image management, or testing code in the same room environment that deployed services use.

CLI commands

Start with the CLI help, then use a few common commands:

bash

meshagent room container --help
meshagent room container image list --room myroom
meshagent room container image pull --room myroom --tag meshagent/cli:default
meshagent room container run --room myroom --image meshagent/cli:default
meshagent room container list --room myroom

Why use the Containers API?

Pull and manage images without leaving the room context.
Run short-lived workloads or exploratory commands on demand.
Inspect logs or open an interactive terminal in a running container.

How it works

Containers are room-scoped workloads. You can pull images, run a container, stream logs, exec into it, stop it, and delete its metadata when you are done. Deployed Room Services and Project Services rely on the same underlying container infrastructure, but the Containers API gives you direct, on-demand control.

Permissions and grants

The Containers API is controlled by the containers grant on the participant token. In practice:

use_containers is the main switch for container operations
pull and run can be narrowed to specific image names or prefixes
logs controls access to container log streaming

See API Scopes and Service YAML.

API reference

Use the methods below to manage room images, start and inspect containers, and clean up container state. The SDKs also expose image-transfer helpers such as push_image, load / load_image, save_image, build helpers such as build, list_builds, cancel_build, delete_build, and get_build_logs, and service helpers such as run_service.

`list_images()`

Description: List images currently available to the room (built or pulled previously).
Parameters: None.
Returns: list[Image] summary records including id, preferred_ref, references, labels, created_at, updated_at, and target_media_type.

meshagent room container image list \
  --room myroom

images = await room.containers.list_images()
for image in images:
    print(image.preferred_ref, image.id)

`inspect_image(image_id)`

Description: Inspect a room image by ID and return detailed content metadata from the container runtime.
Parameters:
- image_id: Image ID from list_images().
Returns: ImageInspection including the image summary, target descriptor, selected manifest, manifests, config descriptor, layers, and content_size.

meshagent room container image inspect \
  --room myroom \
  --image-id sha256:abc123

inspection = await room.containers.inspect_image(image_id="sha256:abc123")
print(inspection.image.preferred_ref, inspection.content_size)
for layer in inspection.layers:
    print(layer.digest, layer.size)

`delete_image(image)`

Description: Delete an unused image from the room.
Parameters:
- image: Tag or digest string to delete.
Returns: None.

meshagent room container image delete \
  --room myroom \
  --image chatbot:old

await room.containers.delete_image(image="chatbot:old")

`pull_image(tag, credentials=None)`

Description: Pull an image into the room. Supports passing registry credentials when needed.
Parameters:
- tag: Image reference (e.g. myrepo/app:latest).
- credentials: Optional list of DockerSecret credentials for private registries.
Returns: None once the pull completes.

meshagent room container image pull \
  --room myroom \
  --tag registry.example.com/agents/chatbot:0.2

await room.containers.pull_image(tag="registry.example.com/agents/chatbot:0.2")

`run(image, ...)`

Description: Start a container in the room.
Parameters (all optional except image):
- image: Container image to run.
- command: Override the default command (str).
- working_dir: Working directory for the container process.
- env: Environment variables injected as dict[str, str].
- mount_path, mount_subpath: Mount configuration when using storage.
- mounts: Structured container mount configuration for advanced mount layouts.
- role, participant_name: Launch on behalf of a specific room identity.
- ports: Port mappings {container_port: host_port}.
- credentials: Registry secrets for the image.
- name: Friendly name for the container.
- template: Runtime defaults to apply. "none" (default) applies no template defaults; "agent" mounts room storage at /data and injects MeshAgent/OpenAI/Anthropic/SMTP proxy environment variables using a token for the container name with role agent.
- writable_root_fs: Override whether the container root filesystem is writable.
- private: Request private container placement where supported.
Returns: Container ID string.

meshagent room container run \
  --room myroom \
  --image registry.example.com/agents/chatbot:0.2 \
  --env SYSTEM_PROMPT="Always respond with a fun fact." \
  --container-name chatbot-demo

container_id = await room.containers.run(
    image="registry.example.com/agents/chatbot:0.2",
    env={"SYSTEM_PROMPT": "Always respond with a fun fact."},
    name="chatbot-demo",
)
print(f"Container launched: {container_id}")

`exec(container_id, ...)`

Description: Attach an interactive command to an existing container and stream its output.
Parameters:
- container_id: Target container.
- command: Optional command list; defaults to the container’s shell.
- tty: Request a TTY session (True for interactive).
Returns: An exec-session object (ExecSession in Python) exposing helpers to read output, send input, resize the terminal, and await completion.

meshagent room container exec \
  --room myroom \
  --container-id "$CONTAINER_ID" \
  --command "bash"

session = await room.containers.exec(
    container_id=container_id,
    command=["bash"],
    tty=True,
)

async for chunk in session.stdout():
    print(chunk.decode(), end="")

# (Optional) Send input; for example, list files then exit the shell
await session.write(b'ls -la\n')
await session.write(b'exit\n')  # end the interactive session

status = await session.result
print(f"Exec finished with status: {status}")

The CLI streams a non-TTY exec session. Use the SDK directly when you need an explicit TTY session and terminal resize control.

Image transfer helpers

In addition to pulling an image into a room, the CLI can push an image from the room to a registry, load an OCI archive from room storage, or save an image as an OCI archive:

bash

meshagent room container image push \
  --room myroom \
  --tag registry.example.com/agents/chatbot:0.2

meshagent room container image load \
  --room myroom \
  --archive-path /images/chatbot.tar

meshagent room container image save \
  --room myroom \
  --tag registry.example.com/agents/chatbot:0.2 \
  --archive-path /workspace/chatbot.tar \
  --mount-room-path /images:/workspace

The Python SDK exposes these container image, build, service, and lifecycle helpers:

Python

await room.containers.push_image(tag="registry.example.com/agents/chatbot:0.2", credentials=None, private=False)
await room.containers.load(archive_path="/images/chatbot.tar")
await room.containers.load_image(mounts=mounts, archive_path="/workspace/chatbot.tar", private=False)
await room.containers.save_image(tag="registry.example.com/agents/chatbot:0.2", mounts=mounts, archive_path="/workspace/chatbot.tar", private=False)

build_id = await room.containers.build(
    tags=["registry.example.com/agents/chatbot:0.2"],
    mount_path="/workspace",
    context_path=".",
    chunks=chunks,
    dockerfile_path=None,
    optimize_image=True,
    private=False,
    credentials=None,
    builder_name=None,
    size=None,
)
builds = await room.containers.list_builds()
await room.containers.cancel_build(build_id=build_id)
await room.containers.delete_build(build_id=build_id)
logs = room.containers.get_build_logs(build_id=build_id, follow=True)

container_id = await room.containers.run_service(service_id="svc_123", env=None)
exit_code = await room.containers.wait_for_exit(container_id=container_id)
status = await room.containers.wait_for_exit_status(container_id=container_id)

`logs(container_id, follow=False)`

Description: Stream container logs and optionally follow until exit.
Parameters:
- container_id: Target container.
- follow: True to keep streaming until the container exits.
Returns: LogStream[None], which you can iterate for log lines or await for completion.

meshagent room container log \
  --room myroom \
  --id "$CONTAINER_ID" \
  --follow

stream = room.containers.logs(container_id=container_id, follow=True)

async for line in stream.logs():
    print(line)

await stream  # optional: wait for the request to finish

`list(all=None)`

Description: List containers in the room, optionally including exited ones.
Parameters:
- all: True to include stopped containers.
Returns: list[RoomContainer] with name, image, state, status, applicable manifest, and metadata about who started it.

meshagent room container list \
  --room myroom \
  --all \
  --output table

containers = await room.containers.list(all=True)
for container in containers:
    print(container.id, container.state, container.started_by.name)

`stop(container_id, force=False)`

Description: Request a graceful stop (or force stop) of a running container.
Parameters:
- container_id: Target container.
- force: Send a forceful termination signal when True.
Returns: None.

meshagent room container stop \
  --room myroom \
  --id "$CONTAINER_ID"

await room.containers.stop(container_id=container_id, force=False)

`delete(container_id)`

Description: Remove container metadata after it has stopped. Useful for cleaning up history.
Parameters:
- container_id: Container to delete.
Returns: None.

await room.containers.delete(container_id=container_id)

Introduction

Rooms

Agents & Tools

Deploy & Manage

Projects

Product Interfaces

Developer Reference

Overview

CLI commands

Why use the Containers API?

How it works

Permissions and grants

API reference

`list_images()`

`inspect_image(image_id)`

`delete_image(image)`

`pull_image(tag, credentials=None)`

`run(image, ...)`

`exec(container_id, ...)`

Image transfer helpers

`logs(container_id, follow=False)`

`list(all=None)`

`stop(container_id, force=False)`

`delete(container_id)`

​Overview

​CLI commands

​Why use the Containers API?

​How it works

​Permissions and grants

​API reference

​list_images()

​inspect_image(image_id)

​delete_image(image)

​pull_image(tag, credentials=None)

​run(image, ...)

​exec(container_id, ...)

​Image transfer helpers

​logs(container_id, follow=False)

​list(all=None)

​stop(container_id, force=False)

​delete(container_id)

​Related guides

Overview

CLI commands

Why use the Containers API?

How it works

Permissions and grants

API reference

`list_images()`

`inspect_image(image_id)`

`delete_image(image)`

`pull_image(tag, credentials=None)`

`run(image, ...)`

`exec(container_id, ...)`

Image transfer helpers

`logs(container_id, follow=False)`

`list(all=None)`

`stop(container_id, force=False)`

`delete(container_id)`

Related guides