Intro to Services and Containers

In MeshAgent, a service is any running program that MeshAgent can call into a room. A service can be anything: a custom AI agent, domain specific tools, external system integrations, or other custom logic. You can run services locally during development, then deploy them with MeshAgent so they’re available in rooms when your app (or your users) need them. At a high level, you have three ways to run things:

• Project Services: Deployed to your project, always-available in every room and managed by MeshAgent.
• Room Services: Saved to a specific room. MeshAgent keeps the service in sync if it changes during the room’s session.
• Containers API: Launch on-demand containers inside specific rooms. Great for running ad-hoc jobs or testing a service before deployment.

Which one should I use? Use Project Services for shared functionality that should always be available. Use Room Services when the service should always be available but is unique per room or users need to choose what runs in their room. Use the Containers API when you need to spin something up temporarily without saving it.

​

What counts as a “service”?

A service can be almost anything. MeshAgent supports both native services and generic programs:

• MeshAgent native: Built using our ServiceHost and APIs for deep integration with rooms
• Generic programs: Any existing web service that can respond to HTTP calls

Under the hood, a service can be:

• Container-backed: MeshAgent runs your image in the room (powered by the Containers API)
• External: MeshAgent routes calls to your service which you host elsewhere

This lets you start with code you already have or build deeply integrated services using MeshAgent’s libraries.

​

Service Lifecycle & Runtime

When the first participant connects to the room, MeshAgent initializes the room and starts all configured services for that room. Services remain running as long as there is at least one active connection. When the last participant disconnects, MeshAgent gracefully shuts down services, freeing resources until the next session. All services, whether project-wide or room-specific, benefit from MeshAgent’s runtime environment:

• Isolation & security: Each service runs in its own sandbox with scoped secrets.
• Room API integration: Send/receive messages, subscribe to events, interact with storage.
• Networking: Localhost networking for low-latency communication between services.
• Storage: Optional room storage mounts for read/write access.
• Tool exposure: Services using MCP SSE can become native tools in the room.
• Health checks: Define liveness/readiness probes to ensure reliable startup.

​

Deployment Options

​

Project Services

Project wide services provide shared functionality across every room in a MeshAgent project. Characteristics:

• Scope: Project wide; automatically available in every room
• Lifecycle: Managed by MeshAgent. Changes to a project service require the room to be restarted for the change to take effect.
• Who Deploys: Project members with permissions (end-users of your app cannot make global changes)
• Great for: Common capabilities (e.g., a global transcription agent, shared toolkits)

Example: A transcription agent that records every meeting automatically and should be available in every room.

​

Room Services

Room services are scoped to a single room. If a room has saved services, they auto-start when the session begins. You can also let your app’s users create, update, or remove them on demand. If the saved configuration changes mid-session, MeshAgent automatically reconciles the running service to match. In short, room services are how users customize what runs in their room. Characteristics:

• Scope: Per-room, each room can have its own unique configuration
• Lifecycle:: Auto-start when saved or can be created on demand (manged by MeshAgent once created)
• Who Deploys: Project members with permissions, your app, or authorized users for their room
• Great for: Personalized agents, room-specific integrations

Example: A research agent a user adds to their room with a custom system prompt. Each user can configure their own version and save it to their room if wanted while other rooms remain unaffected.

​

On-demand Containers (Containers API)

Use the Containers API to run a container temporarily in a room. This is perfect for ad-hoc jobs when you don’t need the container to be persisted throughout the duration of a room’s session. Containers are launched dynamically when requested and run only as long as needed. They can be stopped, restarted, or reconfigured at any time. When a room session ends, any active containers are terminated. Characteristics:

• Scope: Per-room, but not saved
• Lifecycle:: Explicitly start/stop; ephemeral
• Who Launches: Your backend/app automations or project members
• Great for: One-off tasks, batch jobs, trials before saving as a Project or Room Service

Example: Kick off a one time data import in a particular room.

​

Choosing the Right Path

​

Real-World Examples

Here are some ways developers use services in MeshAgent. Depending on your needs, any of these could be deployed as a project service or a room service.

• AI Agent Orchestration: Deploy an agent from your framework of choice that processes user queries and writes responses directly to the room.
• Voice Agents: Run a long-lived transcription and synthesis agent for real-time audio interaction.
• Custom Business Logic: Spin up an MCP server to handle domain-specific workflows (e.g. data validation, report generation), automatically surfaced as tools in the room.
• Data Processing Pipelines: Mount room storage into a service that ingests, transforms, and outputs data files, posting progress back to the room.
• Secure Integrations: Use secrets and environment variables to connect to third-party APIs (e.g. CRM systems, analytics platforms) entirely within the room sandbox.

Some of these make more sense as project services (e.g. transcription, compliance), while others are often room services (e.g. research agents, experimental tools). The right choice depends on whether you want the functionality to be always-on or user-selectable.

​

Next Steps

• Run your code locally to build and test with ServiceHost.
• Manage secrets and registry access to inject credentials securely.
• Packaging services and Deploying Services when you’re ready to deploy across every room.