Skip to main content

​
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.

​
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

If you want a deployed service to use the Containers API, its participant token needs the appropriate Room API grants. See API Scopes and Packaging and Deploying Services.

​
CLI and SDK availability

  • CLI: image and container lifecycle commands are available under meshagent room container ....
  • Python: the page below shows the current helper surface.

​
API Methods

​
list_images

  • Description: List images currently available to the room (built or pulled previously).
  • Parameters: None.
  • Returns: list[Image] including tags, size, labels, and manifest metadata.
meshagent room container image list \
  --room myroom

​
delete_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

​
pull_image

  • 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

​
run

  • Description: Start a container in the room.
  • Parameters (all optional except image):
    • image: Container image to run.
    • command: Override the default command (str).
    • env: Environment variables injected as dict[str, str].
    • mount_path, mount_subpath: Mount configuration when using storage.
    • 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.
  • 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

​
exec

  • 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).
    • detach: Leave the session running in the background (True by default).
  • Returns: A Container object exposing async helpers to read output, send input, resize the terminal, and await completion.
meshagent room container exec \
  --room myroom \
  --container-id "$CONTAINER_ID" \
  --command "bash" \
  --tty

​
logs

  • 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

​
list

  • 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

​
stop

  • 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"

​
delete

  • 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)