Skip to main content

​
Overview

The ServicesClient is the Room API for inspecting the services that are currently running in a room session. Use it when you want to:
  • see which saved services are actually running in the active room
  • inspect runtime state such as container id, restart count, and last exit code
  • request a restart for a running room service without changing its saved deployment spec
This page is about runtime control inside an active room. If you want to deploy, update, validate, or delete saved services, use Deploy Services with MeshAgent and the project-level meshagent service command instead.

​
CLI commands

Start with the CLI help, then use a few common commands:
bash
meshagent room service --help
meshagent room service list --room myroom
meshagent room service restart --room myroom --name my-service

​
Why use the Services API?

  • check whether a deployed room or project service is actually running in the current session
  • inspect runtime state without leaving the room context
  • restart one managed room service while leaving the saved service definition alone

​
How it works

Saved services are deployed with the meshagent service command or generated through higher-level flows such as meshagent process deploy. Once a room session is active, those saved services become running workloads in the room runtime. The ServicesClient gives you visibility into that runtime layer:
  • list() returns the service specs visible in the room
  • list_with_state() / listWithState() adds runtime state details from the room service controller
  • restart() asks MeshAgent to stop the current container for one service so it can come back up cleanly
This is intentionally separate from service packaging and deployment. Deployment changes the saved configuration through meshagent service. The Room Services API tells you what is running right now.

​
Permissions and grants

Room service inspection and restart use the room services toolkit surfaced by the runtime. In practice, use the normal room connection path for operator tooling and deploy the service with the room/API access it needs. For the broader deployment permission model, see API Scopes, Participant Tokens, and Deploy Services with MeshAgent.

​
API reference

​
list()

  • Description: List the services currently visible in the room runtime.
  • Returns: A list of ServiceSpec values.
meshagent room service list \
  --room myroom

​
list_with_state() / listWithState()

  • Description: List services plus runtime state details from the service controller.
  • Returns: ListServicesResult with:
    • services: the service specs
    • service_states: runtime state keyed by service id
Typical runtime fields include service state, container id, started time, restart count, last exit code, and any scheduled restart time. 
result = await room.services.list_with_state()

for service in result.services:
  state = result.service_states.get(service.id or "")
  print(service.metadata.name, state.state if state is not None else "unknown")

​
restart(service_id) / restart({ serviceId })

  • Description: Request a restart for one running room service.
  • Parameters:
    • service_id / serviceId: the room service id to restart
  • Returns: None
Use this when the saved service spec is already correct and you only want MeshAgent to restart the running workload. 
meshagent room service restart \
  --room myroom \
  --name my-service