Skip to main content

​
Overview

Rooms are the runtime and collaboration boundary in MeshAgent. A room is where humans, agents, tools, services, files, queues, and shared documents come together around the same live context. Projects can contain many rooms, and each room can have its own participants, room-scoped services, and persisted state. The Room APIs are how you interact with that runtime. They give you the built-in primitives for messaging, storage, queues, documents, containers, secrets, and the other capabilities that make a room useful as an execution environment.

​
CLI commands

Use meshagent rooms ... to create and manage rooms in a project:
bash
meshagent rooms --help
meshagent setup
meshagent rooms create --name myroom --if-not-exists
meshagent rooms list
meshagent rooms get --name myroom
Use meshagent room <api> ... to work inside a specific room through the Room APIs. Start with meshagent room --help, then drill into the API you need:
bash
meshagent room --help
meshagent room agent --help
meshagent room secret --help
meshagent room queue --help
meshagent room messaging --help
meshagent room storage --help
meshagent room database --help
meshagent room memory --help
meshagent room developer --help
meshagent room container --help
meshagent room sync --help
meshagent room service --help
Use meshagent room service ... when you want to inspect or restart services that are already running in a room session. Use the project-level meshagent service ... command when you want to deploy, update, validate, or delete saved services. See Deploy Services with MeshAgent.

​
How rooms fit into MeshAgent

  • A project groups many rooms.
  • A room is the live workspace for one stream of collaboration or execution.
  • A session is one active run of that room.
When a room becomes active, MeshAgent starts a session for that room and starts any services that should run there. From that point on, participants can use the Room APIs and work over the same shared context.

​
Room APIs

Rooms expose a set of room-scoped APIs through the RoomClient:
  • Agents API AgentsClient: Call agents, invoke toolkits, and work with agent participants in the room.
  • Containers API ContainersClient: Run containers and inspect container activity in the room runtime.
  • Database API DatabaseClient: Store and query structured room data in tables.
  • Memory API MemoryClient: Store and recall room-scoped memories for agents and workflows.
  • Developer API DeveloperClient: Send logs and inspect developer events for the room.
  • Messaging API MessagingClient: Send and receive real-time messages between room participants.
  • Queues API QueuesClient: Send and receive queued work inside the room.
  • Secrets API SecretsClient: Create and use room-scoped secrets, OAuth tokens, and related credentials.
  • Services API ServicesClient: List running services in the room and request a restart for one service.
  • Storage API StorageClient: Read and write files in room storage.
  • Sync API SyncClient: Work with shared documents and synchronized room state.

​
Room lifecycle and sessions

Rooms are durable named workspaces, but runtime activity happens in sessions.
  • A room session starts when the room becomes active.
  • During that session, participants connect, services run, and room activity is recorded.
  • When activity stops, the room shuts down automatically so compute is not kept running unnecessarily. Persisted data written through storage, database, or sync remains available according to that API’s behavior.
See Sessions for the runtime implications.

​
Using Room APIs in Deployed Services

If you deploy a MeshAgent service and want that service to use the Room APIs, you must grant that access through the participant token api scope. Deployment alone does not automatically give a service access to storage, database, secrets, containers, or the other Room APIs. In practice, that means:
  • set the token api scope on service tokens injected through container.environment[].token
  • or set the endpoint api scope for the participant identity that joins through a MeshAgent endpoint
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. 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.

​
Using RoomClient from SDKs

All of the main SDKs expose a RoomClient with the same overall shape:
  • connect to a room
  • wait for readiness
  • use sub-clients such as agents, messaging, storage, database, queues, secrets, and sync
  • dispose the client when you are done
The exact method names and property casing vary by language, but the underlying room model is the same. Use the SDK and language guides for the concrete examples:
  • Python: RoomClient in meshagent.api
  • TypeScript / JavaScript: RoomClient in @meshagent/meshagent
  • Dart / Flutter: RoomClient in package:meshagent/room_server_client.dart
  • .NET: Meshagent.RoomClient