Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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

​
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

​
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

​
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

​
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).
    • 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(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).
    • detach: Leave the session running in the background (True by default).
  • 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"
The CLI streams a non-TTY exec session. Use the SDK directly when you need an explicit TTY session and terminal resize control.

​
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

​
list(all=False)

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

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