Skip to main content
MeshAgent Rooms provide real-time collaborative workspaces for agents and participants. Each room dynamically manages participant lists, tracks presence, and enables information sharing. Rooms are automatically provisioned when participants join, ensuring effortless integration and minimizing synchronization complexity.

​
Room APIs

Rooms also expose a set of room-scoped APIs through the room client:
  • Agents API AgentsClient: Manages agent interactions.
  • Containers API ContainersClient: Interact with containers on demand in a room.
  • Database API DatabaseClient: Provides a simple relational-like API for data storage and retrieval through tables.
  • Memory API MemoryClient: Manage room-scoped knowledge memories and recall context.
  • Developer API DeveloperClient: Send structured logs to the Developer Console and stream developer log events.
  • Messaging API MessagingClient: Enables real-time chat messaging among participants.
  • Queues API QueuesClient: Facilitates reliable data/message exchange with other agents or participants.
  • Secrets API SecretsClient: Create and manage oauth tokens and user secrets.
  • Storage API StorageClient: Manages file storage and retrieval.
  • Sync API SyncClient: Offers document synchronization capabilities, listing remote participants, allowing participants to collaborate on shared documents.
  • ServicesClient (Python/TypeScript/Dart): List and restart room services. For deployment patterns, see Services & Containers.

​
Using the Room APIs with the MeshAgent CLI

The Room APIs are accessible from both the MeshAgent CLI and SDKs. You can explore the CLI for each Room API by running:
CLI
meshagent room agent --help
meshagent room container --help
meshagent room database --help
meshagent room developer --help
meshagent room memory --help
meshagent room messaging --help
meshagent room queue --help
meshagent room secret --help
meshagent room service --help
meshagent room storage --help
meshagent room sync --help

​
Using Room APIs in Deployed Services

If you deploy a MeshAgent service and want that service to use the Room APIs, you must grant the service the appropriate Room API access through its participant token api scope. Deployment alone does not automatically give a service access to storage, database, secrets, containers, or the other Room APIs. The relevant places to configure that are:
  • Service tokens injected through container.environment[].token: set the token’s api scope in the service manifest.
  • MeshAgent endpoints in a service manifest: set the endpoint api scope for the participant identity that joins the room.
Useful defaults:
  • ApiScope.agent_default() enables Agents, Queues, Messaging, Database, Sync, Storage, Containers, and Developer access.
  • ApiScope.full() adds Secrets, Admin, and Tunnels access on top of agent_default().
Many Room APIs can also be narrowed further inside the scope:
  • Storage / Sync: path-based grants
  • Database: table-level grants
  • Queues: send/receive/list controls
  • Messaging: broadcast/list/send controls
  • Containers: pull/run/log controls
For the full scope model and manifest fields, see API Scopes, Participant Tokens, and Packaging and Deploying Services. For information on how to create and manage rooms and their permissions in a project check out the REST API documentation.

​
Getting Started from the CLI

If you want to start using the Room APIs quickly, the simplest path is:
bash
meshagent setup
meshagent rooms create --name myroom --if-not-exists
After that you can:
  • use the Room APIs from the CLI with --room myroom
  • connect to myroom from any SDK using the examples in Getting Started
  • deploy room-scoped services into myroom
If you are building your own application and minting participant tokens yourself, make sure the participant has both:
  • a room grant allowing it to join the room
  • an api scope granting access to the Room APIs it needs
See REST API overview, Participant Tokens, and API Scopes.

​
Room Class Overview

Core Room behavior is consistent across SDKs, but available sub-clients vary by language. Use the section below that matches your client library.

​
Python

from meshagent.api import RoomClient
  • Connect with async with RoomClient(protocol=...) as room:; the async context manager starts and stops the connection for you.
  • Issue requests with await room.send_request(...); session metadata is available via room.session_id, room.room_url, and room.room_name.
  • Register event handlers with room.on("room.status", handler); use room.emit(...) to publish custom events.
  • Access sub-clients through snake_case attributes such as room.agents, room.containers, room.database, room.developer, room.livekit, room.memory, room.messaging, room.queues, room.secrets, room.services, room.storage, and room.sync.

​
TypeScript / JavaScript

RoomClient in @meshagent/meshagent
  • Instantiate the client with { protocol } and call await room.start({ onDone, onError }) to wait for room_ready.
  • Clean up with room.dispose() when you are finished.
  • Send RPCs with await room.sendRequest(type, payload, data?); readiness is exposed via await room.ready.
  • Emit events with room.emit(event) and consume them using for await (const evt of room.listen()).
  • Sub-clients are camelCase properties: room.agents, room.containers, room.database, room.developer, room.memory, room.messaging, room.queues, room.secrets, room.services, room.storage, and room.sync.

​
Dart / Flutter

RoomClient in package:meshagent/room_server_client.dart
  • Call await room.start(onDone: ..., onError: ...) after constructing the client; room.ready completes when the server sends room_ready.
  • Dispose resources with room.dispose(); use await room.exec(...) for container execution helpers.
  • Send requests with await room.sendRequest(type, payload, data: ...).
  • Observe room activity with room.events.listen(handler) or by keeping the StreamSubscription returned from room.listen(...).
  • Access sub-clients via camelCase getters: room.agents, room.containers, room.database, room.developer, room.memory, room.messaging, room.queues, room.secrets, room.services, room.storage, and room.sync.

​
.NET

Meshagent.RoomClient
  • Construct var room = new RoomClient(protocol); and call await room.ConnectAsync(); to wait for readiness.
  • Dispose with await room.DisposeAsync(); or await using var room = new RoomClient(protocol);.
  • Send RPCs using await room.SendRequest(type, payload, data);; session metadata is available via room.SessionId, room.RoomUrl, and room.RoomName.
  • Register handlers with room.On("room.status", handler) and raise custom events through room.Emit(name, data).
  • Sub-clients are exposed as PascalCase properties: room.Agents, room.Database, room.Developer, room.Livekit, room.Messaging, room.Queues, room.Secrets, room.Storage, and room.Sync.