Packaging and Deploying Services

MeshAgent allows you to deploy any code as a service. Services can be anything from pre-built agents to custom code to external integrations and can be deployed as either a room service (scoped to a specific MeshAgent room) or a project service (available in every room in your project). To deploy a service in MeshAgent, you write a YAML configuration file that describes what to run and how to connect it to a room. Services can be deploy with the MeshAgent CLI, from MeshAgent Studio, or by sharing a Powerboards install link. This page covers the key concepts behind service configuration and provides a complete field reference for the required configuration YAML file. For step-by-step walkthroughs, see the deployment examples at the bottom of this page.

Key Concepts

Before deploying your service there are three decisions to make about your service.

1. Who can use the service: Project vs Room Scope

This determines who can use your service. The YAML is the same in both cases — the scope is set by how you deploy.

Project service — Available in every room in your project. Changes require a room restart to take effect. Deploy with meshagent service create --file meshagent.yaml (no --room flag).
Room service — Scoped to a single room. Auto-updates if changed during an active session. Deploy with meshagent service create --file meshagent.yaml --room myroom.

2. Is the service user-configurable: Service vs ServiceTemplate

This determines whether configuration is fixed or user-provided.

Service (kind: Service) — A concrete spec that MeshAgent can run immediately. Configuration is baked into the YAML. Deploy with meshagent service create.
ServiceTemplate (kind: ServiceTemplate) — A parameterized spec that collects user inputs (API keys, names, settings) at deploy time, then renders a Service from them. Uses {{ variable_name }} placeholders (Jinja templating) and an additional variables section to define what users provide. Deploy with meshagent service create-template --file meshagent.yaml.

ServiceTemplates can only be deployed to a specific room, not your entire project.

3. What kind of service is running: Container vs External

Each YAML configuration file can run either a containerized service or an external service.

Container — MeshAgent pulls a container image and runs it inside the room. The container can run anything: a MeshAgent CLI agent, a Python script, or other custom code. MeshAgent handles the lifecycle — starting, stopping, injecting credentials, and connecting it to the room.
External - Your service is already running somewhere else. You provide a URL and MeshAgent routes traffic to it.

How Service Configuration Files are Structured

Every service configuration starts withversion: v1, a kind (Service or ServiceTemplate), and a metadata section. You must also include either container or external.

  version: v1                                
  kind: Service | ServiceTemplate            
                                             
  metadata:         ← identity and display   
  agents:           ← agent identities       
                       provided by           
                       this service          
                                            
  container:  ─┐    ← what to run            
          OR    │      (pick one)             
  external:   ─┘                             
                                             
  ports:            ← HTTP routing           
    endpoints:        (not always needed)    
                                             
  variables:        ← user inputs            
                      (ServiceTemplate only) 

metadata — The service’s name, description, and display information. Required.
agents — Declares the participant identities this service provides to the room.
container or external — Defines what runs. container provides an image for MeshAgent to run; external points to a URL you host. One or the other is required.
ports — Defines HTTP endpoints MeshAgent can route traffic to. Optional. Services that connect directly to the room using a participant token don’t require ports.
variables — Inputs that users provide at deploy time. ServiceTemplate only. Values are substituted into the YAML using {{ variable_name }} placeholders.

Example 1: Deploying a `Service`

Let’s deploy a simple ChatBot with web search and storage tools. This is a kind: Service where configuration is fixed and it runs as-is.

kind: Service
version: v1
metadata:
  name: my-chatbot
  description: "A chatbot with web search and storage"
  annotations:
    meshagent.service.id: "my-chatbot"
agents:
  - name: my-chatbot
    description: "A helpful chatbot"
    annotations:
      meshagent.agent.type: "ChatBot"
container:
  image: "us-central1-docker.pkg.dev/meshagent-public/images/cli:{SERVER_VERSION}-esgz"
  command: >-
    meshagent chatbot join
    --agent-name my-chatbot
    --require-web-search
    --require-storage
    --rule "You are a helpful assistant. Use web search to find current information and save important findings to storage."
    --room-rules "agents/my-chatbot/rules.txt"
  environment:
    - name: MESHAGENT_TOKEN
      token:
        identity: my-chatbot
  storage:
    room:
      - path: /data
        read_only: false

Here’s what each section does:

kind - Declares the type of configuration file. In this case a Service.
metadata — Names the service my-chatbot and sets meshagent.service.id so Powerboards and MeshAgent Studio can identify it.
agents — Declares a single agent identity (my-chatbot) with meshagent.agent.type: ChatBot so Powerboards knows to display it as a chatbot in the UI.
container.image — Uses a MeshAgent base image, which includes the MeshAgent CLI and all prebuilt agent types.
container.command — Runs meshagent chatbot join with flags for web search, storage, an inline rule (--rule), and a room-editable rules file (--room-rules).
container.environment — Injects a MESHAGENT_TOKEN so the agent can connect to the room as the my-chatbot identity.
container.storage — Mounts room storage at /data so the agent can read and write files.

Validate and deploy to a room:

bash

meshagent service validate --file "meshagent.yaml"

meshagent service create --file "meshagent.yaml" --room myroom

To deploy as a project service drop the --room flag

Example 2: Deploying a `ServiceTemplate`

Now let’s convert the chatbot from Example 1 into a ServiceTemplate. We’ll add a variables section so users can choose a language for the chatbot to respond in.

kind: ServiceTemplate
version: v1
metadata:
  name: my-language-chatbot
  description: "A chatbot with web search and storage that responds in your chosen language"
  annotations:
    meshagent.service.id: "my-language-chatbot"
variables:
  - name: language
    description: "The language the chatbot should respond in (e.g. English, Spanish, French)"
agents:
  - name: my-language-chatbot
    description: "A helpful chatbot"
    annotations:
      meshagent.agent.type: "ChatBot"
container:
  image: "us-central1-docker.pkg.dev/meshagent-public/images/cli:{SERVER_VERSION}-esgz"
  command: >-
    meshagent chatbot join
    --agent-name my-language-chatbot
    --require-web-search
    --require-storage
    --rule "You are a helpful assistant. Always respond in {{ language }}. Use web search to find current information and save important findings to storage."
    --room-rules "agents/my-language-chatbot/rules.txt"
  environment:
    - name: MESHAGENT_TOKEN
      token:
        identity: my-language-chatbot
  storage:
    room:
      - path: /data
        read_only: false

The differences from Example 1:

kind changed from Service to ServiceTemplate.
variables added with a single variable, language. This is what users provide at deploy time.
container.command now includes {{ language }} in the --rule flag. MeshAgent substitutes the user’s value when rendering the template into a Service.

Validate and deploy, providing the variable value:

bash

meshagent service validate-template --file "meshagent.yaml"

meshagent service create-template --file "meshagent.yaml" --value language=Spanish --room myroom

Deploying and Managing Services CLI Reference

Deploy commands

Deploy a Service:

bash

# To a specific room
meshagent service create --file meshagent.yaml --room myroom

# To the entire project (available in every room)
meshagent service create --file meshagent.yaml

Deploy a ServiceTemplate (room only):

bash

meshagent service create-template --file meshagent.yaml --value key=value --room myroom

List services

View services deployed to a room:

meshagent service list --room myroom

This returns each service’s ID, name, and the applicable image associated to it. You’ll need the service ID for update and delete commands.

Update a service

bash

# Update a Service
meshagent service update --file meshagent.yaml --room myroom --id SERVICE_ID

# Update a ServiceTemplate
meshagent service update-template --file meshagent.yaml --value key=value --room myroom --id SERVICE_ID

Delete a service

bash

# Delete a Service or ServiceTemplate
meshagent service delete --file meshagent.yaml --room myroom --id SERVICE_ID

Managing Services from MeshAgent Studio

You can also manage deployed services from MeshAgent Studio. Navigate to your room or project to view, edit, and remove services from the UI.

Service Configuration Field Reference

The tables below document every field in the service configuration YAML.

Top-Level Fields

Field	Required	Description
`version`	Yes	Schema version. Always `v1`.
`kind`	Yes	`Service` or `ServiceTemplate`.
`metadata`	Yes	Service identity and display information.
`agents`	No	Agent identities exposed by this service.
`ports`	No	Network ports and HTTP endpoints MeshAgent can route to.
`container`	*	Container configuration. Mutually exclusive with `external`.
`external`	*	External service URL. Mutually exclusive with `container`.
`variables`	No	User-provided inputs for templating. `ServiceTemplate` only.

* Either container or external is required, but not both.

metadata

Identifies the service and provides information displayed in the UI.

Field	Type	Required	Description
`name`	string	Yes	Unique service name.
`description`	string	No	Description shown in UI.
`repo`	string	No	Source code repository URL.
`icon`	string	No	Icon or emoji for UI display.
`annotations`	object	No	Key-value metadata. See Annotations.

agents

Declares the participant identities this service provides. MeshAgent uses this to route requests, apply policies, and display agents in the UI.

Field	Type	Required	Description
`name`	string	Yes	Unique agent identity within the service.
`description`	string	No	Display text describing the agent.
`annotations`	object	No	Key-value metadata. See Annotations.

container

Defines a container for MeshAgent to run. Fields marked † are only available in Service, not ServiceTemplate.

Field	Type	Required	Description
`image`	string	Yes	Container image (e.g. `us-central1-docker.pkg.dev/meshagent-public/images/cli:{SERVER_VERSION}-esgz`).
`command`	string	No	Command to execute when the container starts.
`environment`	list	No	Environment variables to set in the container.
`secrets`	list	No	IDs of room secrets to inject as environment variables. †
`pull_secret`	string	No	Secret ID for authenticating with a private container registry. †
`storage`	object	No	Storage volumes to mount into the container.
`api_key`	object	No	Auto-provision an admin API key and inject it into the container. †
`on_demand`	boolean	No	When true, the container runs only when explicitly invoked.
`writable_root_fs`	boolean	No	Allow writes to the container’s root filesystem. Default: read-only.
`private`	boolean	No	Mark the container as private to its service. Default: true.

container.environment

Each entry sets an environment variable in the container. A variable can have a literal value or a token that MeshAgent generates at startup.

Field	Type	Required	Description
`name`	string	Yes	Environment variable name.
`value`	string	No	Literal string value.
`token`	object	No	Request a participant token to be generated and injected as the value.

token fields:

Field	Type	Required	Description
`identity`	string	Yes	Participant identity the token is issued for.
`api`	object	No	API scope granted to the token. See API Scopes.
`role`	string	No	Participant role (e.g. `user`, `agent`, `tool`).

container.storage

Mounts storage volumes into the container.

Field	Type	Description
`room`	list	Per-room storage. Read/write by default.
`project`	list	Project-wide shared storage. Read-only by default.
`images`	list	Content from another container image. Read-only by default.
`files`	list	Inline text content mounted as a file. Read-only by default.

Room and project mount fields:

Field	Type	Required	Description
`path`	string	Yes	Mount path inside the container.
`subpath`	string	No	Subdirectory within the storage volume.
`read_only`	boolean	No	Whether the mount is read-only.

Image mount fields:

Field	Type	Required	Description
`image`	string	Yes	Source container image.
`path`	string	Yes	Mount path inside the container.
`subpath`	string	No	Subdirectory within the image.
`read_only`	boolean	No	Whether the mount is read-only.

File mount fields:

Field	Type	Required	Description
`path`	string	Yes	Mount path inside the container.
`text`	string	Yes	File contents.
`read_only`	boolean	No	Whether the mount is read-only.

container.api_key

Provisions an admin API key and injects it into the container. Service only.

Field	Type	Required	Description
`role`	string	Yes	Always `admin`.
`name`	string	Yes	Name for the API key.
`auto_provision`	boolean	No	Automatically provision on deployment.

external

Routes traffic to a service running outside MeshAgent. Requires ports to define how MeshAgent reaches the service.

Field	Type	Required	Description
`url`	string	Yes	URL where the service is running.

ports

Defines network ports the service listens on and how MeshAgent routes HTTP traffic to them.

Field	Type	Required	Description
`num`	`"*"` or int	Yes	Port number, or `"*"` for auto-assignment.
`host_port`	int	No	Host port mapping. Defaults to `num`.
`type`	string	No	Protocol: `http` or `tcp`.
`liveness`	string	No	HTTP path for health checks.
`endpoints`	list	No	Endpoints served on this port.
`published`	boolean	No	Expose the port to the internet.
`public`	boolean	No	When false, requests must include a participant token.

ports.endpoints

Each endpoint maps a URL path to either a MeshAgent-native service or an MCP server.

Field	Type	Required	Description
`path`	string	Yes	URL path for this endpoint.
`meshagent`	object	No	MeshAgent-native endpoint. Mutually exclusive with `mcp`.
`mcp`	object	No	MCP server endpoint. Mutually exclusive with `meshagent`.
`annotations`	object	No	Key-value metadata.

meshagent endpoint

Connects the endpoint to a MeshAgent participant identity.

Field	Type	Required	Description
`identity`	string	Yes	Participant identity for this endpoint.
`api`	object	No	API scope overrides. See API Scopes.

mcp endpoint

Registers an MCP server as a toolkit in the room.

Field	Type	Required	Description
`label`	string	Yes	Toolkit display name.
`description`	string	No	Description of what the toolkit provides.
`allowed_tools`	list	No	Filters which tools are exposed.
`headers`	object	No	Custom HTTP headers to include in requests.
`require_approval`	string	No	`always` or `never`.
`oauth`	object	No	OAuth client configuration.
`openai_connector_id`	string	No	OpenAI connector ID.

allowed_tools entries:

Field	Type	Required	Description
`tool_names`	list	Yes	Tool names to allow.
`read_only`	boolean	No	Treat the tools as read-only.

oauth fields:

Field	Type	Required	Description
`client_id`	string	Yes	OAuth client ID.
`client_secret`	string	No	OAuth client secret.
`authorization_endpoint`	string	Yes	Authorization endpoint URL.
`token_endpoint`	string	Yes	Token endpoint URL.
`no_pkce`	boolean	No	Disable PKCE (Proof Key for Code Exchange).
`scopes`	list	No	OAuth scopes to request.

variables (ServiceTemplate only)

Defines user-provided inputs for a ServiceTemplate. Values are substituted into the YAML using {{ variable_name }} syntax (Jinja templating). Templating is supported in: metadata fields, agents, container.image, container.command, container.environment values, and external.url.

Field	Type	Required	Description
`name`	string	Yes	Variable identifier. Referenced as `{{ name }}` in templates.
`description`	string	No	Help text shown in UI and Powerboards.
`enum`	list	No	Restricts input to specific values. Displayed as a dropdown.
`optional`	boolean	No	Whether the variable can be left blank.
`obscure`	boolean	No	Hides the value in UI. Use for sensitive data.
`type`	string	No	Type hint (e.g. `email`).
`annotations`	object	No	Key-value metadata. See Annotations.

Annotations

Annotations are key-value strings attached to services, agents, or variables. MeshAgent and Powerboards use specific annotation keys to control behavior. You can also define custom annotations.

Service Annotations

Set in metadata.annotations.

Key	Description
`meshagent.service.id`	Unique identifier for the service.
`meshagent.service.readme`	URL or inline content for the service’s documentation.

Agent Annotations

Set in agents[].annotations.

Key	Description
`meshagent.agent.type`	MeshAgent Agent type: `ChatBot`, `VoiceBot`, `Transcriber`, `TaskRunner`, `MailBot`, `Worker`, or `Shell`.
`meshagent.agent.widget`	UI widget to display for this agent.
`meshagent.agent.schedule`	JSON string defining a scheduled task and its payload.
`meshagent.agent.shell.command`	Shell command for `Shell`-type agents.
`meshagent.agent.database.schema`	Database schema metadata for the agent.

Event Annotations

Set in agents[].annotations. Subscribe an agent to room events. The value is the name of a queue for a Worker agent to process.

Key	Description
`meshagent.events.service.created`	Fires when a service is created in the room.
`meshagent.events.service.updated`	Fires when a service is updated.
`meshagent.events.room.user.grant.create`	Fires when a user is added to the room.
`meshagent.events.room.user.grant.delete`	Fires when a user is removed from the room.
`meshagent.events.room.user.grant.update`	Fires when a user’s room grant is updated.

Webhook Annotations

Set in agents[].annotations.

Key	Description
`meshagent.webhook.processor`	Identifies the agent as a webhook processor.
`meshagent.webhook.queue`	Queue name for incoming webhook payloads.
`meshagent.webhook.validation.method`	Method used to validate webhook signatures.
`meshagent.webhook.validation.secret`	Secret ID used for webhook signature validation.

Variable Annotations

Set in variables[].annotations. ServiceTemplate only.

Key	Description
`meshagent.secret.*`	Tells Powerboards to store this variable’s value as a room secret. Powerboards prompts the user and creates the secret automatically. The CLI ignores these annotations — create the secret manually with `meshagent room secrets set`.

Deployment Examples

Step-by-step guides for common deployment patterns:

Deploy an agent with a single command — Deploy a prebuilt agent with a single command, no YAML required.
Deploy a customizable multi-agent service — Deploy a chatbot and mailbot where users can create their own email.
Deploy a terminal based agent - Deploy a terminal based agent like Codex into a Room.
Connect to an external MCP server — Connect to a third-party MCP server.
Publish to Powerboards — Turn any ServiceTemplate into a one-click install link.

Introduction

Room API

Project Administration

Agents

Tools

Observability

Services Runtime & Deployment

Secrets

Documents

UI SDKs

References

​Key Concepts

​1. Who can use the service: Project vs Room Scope

​2. Is the service user-configurable: Service vs ServiceTemplate

​3. What kind of service is running: Container vs External

​How Service Configuration Files are Structured

​Example 1: Deploying a Service

​Example 2: Deploying a ServiceTemplate

​Deploying and Managing Services CLI Reference

​Deploy commands

​List services

​Update a service

​Delete a service

​Managing Services from MeshAgent Studio

​Service Configuration Field Reference

​Top-Level Fields

​metadata

​agents

​container

​container.environment

​container.storage

​container.api_key

​external

​ports

​ports.endpoints

meshagent endpoint

mcp endpoint

​variables (ServiceTemplate only)

​Annotations

​Service Annotations

​Agent Annotations

​Event Annotations

​Webhook Annotations

​Variable Annotations

​Deployment Examples

Key Concepts

1. Who can use the service: Project vs Room Scope

2. Is the service user-configurable: Service vs ServiceTemplate

3. What kind of service is running: Container vs External

How Service Configuration Files are Structured

Example 1: Deploying a `Service`

Example 2: Deploying a `ServiceTemplate`

Deploying and Managing Services CLI Reference

Deploy commands

List services

Update a service

Delete a service

Managing Services from MeshAgent Studio

Service Configuration Field Reference

Top-Level Fields

metadata

agents

container

container.environment

container.storage

container.api_key

external

ports

ports.endpoints

variables (ServiceTemplate only)

Annotations

Service Annotations

Agent Annotations

Event Annotations

Webhook Annotations

Variable Annotations

Deployment Examples