Skip to main content
After you’ve packaged your service, you’re ready to deploy it. MeshAgent services can be deployed as a project service (available in every room in the project) or as a room service (scoped to a specific room). Both service types start and stop with the room’s lifecycle. The main difference is how updates behave: room services update automatically during an active session when you change them, while project services require a room restart for the change to take effect. Project services are best for static, shared functionality. Room services are best when customization is needed or only certain teams need access to them. To learn more about when to use each, see Introduction to Services and Containers.

​
Deployment Options

  • MeshAgent CLI: Automate deployments and integrate with CI/CD workflows. The CLI accepts both kind: Service and kind: ServiceTemplate manifests. Use meshagent service validate-template to validate templates and meshagent service create-template / update-template to deploy them with values.
  • MeshAgent Studio: Deploy and manage services through the web UI at studio.meshagent.com
  • Powerboards Install Links: Install services directly into Powerboards (room services only).

​
Before you deploy

For common agents (like chatbots and voicebots) you can use the CLI to deploy the agent in one step (e.g. meshagent chatbot deploy...) For custom services, you can deploy from the MeshAgent Studio UI, or you’ll need to create a service configuration file (meshagent.yaml) that specifies either:
  • Containerized services: Container image, commands, and applicable environment variables or secrets.
  • External services: URL where your service is already running.
If you’re using a ServiceTemplate, provide values at deploy time using --values-file or --value. You can also validate the template first with meshagent service validate-template. For kind: Service manifests, validate locally with meshagent service validate before deploying.

​
Example: Deploy a Custom ChatBot

​
Step 1: Create the agent file

Let’s create a simple chatbot that can be deployed as a project or room service. We’ll add the container image and meshagent.yaml next.
  • main.py: A MeshAgent-native chatbot service using ServiceHost
main.py 
import asyncio
from meshagent.otel import otel_config
from meshagent.api.services import ServiceHost
from meshagent.agents.chat import ChatBot
from meshagent.openai import OpenAIResponsesAdapter

# Enable OpenTelemetry logging and tracing for the agent
otel_config(service_name="simple-chatbot")

# Create a service host
service = ServiceHost()  # optional to pass a port, MeshAgent automatically assigns an available one if none provideds

# Register an agent at a specific path
@service.path(path="/agent", identity="simple-chatbot")
class SimpleChatbot(ChatBot):
    def __init__(self):
        super().__init__(
            name="chatbot",
            title="Simple Chatbot",
            description="A helpful chatbot for room participants",
            rules=[
                "Always respond to the user first then include a fun fact at the end of your response."
            ],
            llm_adapter=OpenAIResponsesAdapter(),
        )

# Start the service
asyncio.run(service.run())

​
Step 2: Choose a container layout

You can package the service in two ways. The example YAML below uses the runtime image + code image mount layout. Option A: Runtime image + code image mount (matches the sample YAML) Build a code-only image that just ships your source to /src:
Dockerfile
FROM scratch
COPY . /src
In this layout, container.image points to a runtime image (for example meshagent/python-sdk-slim), and container.storage.images mounts the code-only image into the container. The command runs from the mounted path. This approach is the recommended path because it allows you to use existing optimized MeshAgent base images with small code-only images that can be pulled and run quickly. Option B: Single image (self-contained) Build a single image that includes the runtime and your code:
Dockerfile
FROM meshagent/python-sdk-slim:latest

COPY . /src

WORKDIR /src

ENTRYPOINT [ "python3", "main.py" ]
If you build your own image, we recommend optimizing it with eStargz. This approach is the best fit when your runtime needs custom system packages.

​
Step 3: Build and push the container image(s)

Build and push the Docker image(s) to your registry. Make sure $IMAGE and $TAG are set for your repo. You can skip this step and still run the example by using the public docs example image in the meshagent.yaml file below. 
docker buildx build . \
  -t "$IMAGE:$TAG" \
  --platform linux/amd64 \
  --push
Note: We recommend docker buildx because it supports cross-platform builds, pushes directly to your registry in one step, and enables optional layer caching for much faster CI builds.

​
Step 4: Configure the meshagent.yaml file

Update the container section of the YAML file to use your image(s) (if applicable). The example below uses the runtime + code image mount pattern from the standard agent samples. If you follow the single-image path, update container.image, remove storage.images, and adjust command to match your entrypoint or file path. 
kind: Service
version: v1
metadata:
  name: simple-chatbot
  description: "A simple chatbot that can interact with users"
  annotations:
    meshagent.service.id: "simple.chatbot"
agents:
  - name: simple-chatbot
    description: "A conversational agent without tools"
    annotations:
      meshagent.agent.type: "ChatBot"
ports:
- num: "*"
  endpoints:
  - path: /agent
    meshagent:
      identity: simple-chatbot
container:
  image: "us-central1-docker.pkg.dev/meshagent-public/images/python-sdk:{SERVER_VERSION}-esgz"
  command: python /src/simple_chatbot/simple_chatbot.py
  storage:
    images:
      # Replace this image tag with your own code-only image if you build one.
      - image: "us-central1-docker.pkg.dev/meshagent-public/images/python-docs-examples:{SERVER_VERSION}"
        path: /src
        read_only: true
If your service needs scheduled work, add a meshagent.agent.schedule annotation to the relevant agent in meshagent.yaml (cron or one-time). See the packaging guide for the annotation format and the Scheduled Tasks API for programmatic management. For more details on the configuration files see the packaging services documentation. Don’t forget to add a pull_secret parameter to the container section of the manifest if you are pulling from a private repository.

​
Step 5: Deploy the Service

​
Deploy via CLI

We can deploy the service to the entire project or to a specific room. To deploy to the entire project, omit --room. To deploy to a specific room, include --room <room>.
bash
meshagent setup # authenticate to MeshAgent if not already done

# Deploy as a project service
meshagent service create --file="meshagent.yaml"

# Deploy as a room service
meshagent service create --file="meshagent.yaml" --room quickstart
If you are starting from a ServiceTemplate, validate it and provide values when deploying:
bash
# Validate a template file
meshagent service validate-template --file="meshagent.template.yaml"

# Deploy from a template (project service)
meshagent service create-template --file="meshagent.template.yaml" --values-file="meshagent.values.yaml"

# Deploy from a template (room service)
meshagent service create-template --file="meshagent.template.yaml" --values-file="meshagent.values.yaml" --room quickstart

​
Deploy from MeshAgent Studio

You can also deploy and manage services from MeshAgent Studio. Project Service
  1. Visit studio.meshagent.com and select your project
  2. Select the Services tab and choose New Service
  3. Provide the required information
  4. Save the configuration
Once saved, the service will be available to all the rooms in your project. The next time any room session starts, the project service will start in that room. Room Services
  1. Visit studio.meshagent.com and open a specific room
  2. Select the menu icon on a room then Services then click New Service
  3. Provide the required information
  4. Save the configuration
Once saved, the service will be available in this room and start the next time the room starts. If the service is updated during the session, MeshAgent will automatically update the service so it stays in sync with what is saved.

​
Step 6: Use the Service

Now that your service is deployed, try it out in MeshAgent Studio. Project Services If you deployed the agent as a project service, it will appear under the Services tab of the UI. To use the service, simply start a new session in any room and enter the room, the chatbot will appear in the participants tab for you to interact with. Room Services If you deployed the agent to a specific room, it will appear in the room services menu. When you start the room, the service will come up and you can begin using it.

​
Update an Existing Service

If you make modifications to your service, you can easily update it using the MeshAgent CLI.
bash
meshagent service update --file meshagent.yaml  # add --room=myroom for room services
meshagent service update-template --file meshagent.template.yaml --values-file meshagent.values.yaml  # add --room=myroom for room services

​
Verify Deployment and Troubleshooting

You can verify if the service is running from the Developer Console which appears at the bottom half of the room UI in MeshAgent Studio. From the Containers tab, you’ll see the name of the container, who started it, and its status. You can also view container logs and stop the container. If the service is not starting be sure to check the container logs, it’s possible that the container is crashing because it is missing a library etc. From the Logs tab, you’ll see startup messages from your service, use this to check that the service has started appropriately.