Service YAML - MeshAgent

Write a service manifest when you want to review, customize, validate, deploy, update, or delete the service configuration yourself. Use meshagent service with service manifests. Use Deploy a built in Agent when you want to deploy a process-backed agent from CLI flags instead. In MeshAgent, you can deploy fixed or templated services project-wide or to specific rooms, either as MeshAgent-managed container services or as external services that MeshAgent routes to; for more detail, see Intro to Services. The examples below show three common cases:

a Service with a container
a ServiceTemplate with a container
a Service with an external runtime

Example 1: `Service` with `container`

Use kind: Service when the configuration is fixed at deploy time.

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: "meshagent/cli:default"
  command: >-
    meshagent process join
    --agent-name my-chatbot
    --channel chat
    --web-search
    --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.md"
  environment:
    - name: MESHAGENT_TOKEN
      token:
        identity: my-chatbot
  storage:
    room:
      - path: /data
        read_only: false

This example uses kind: Service with a container. MeshAgent runs the meshagent/cli:default image, and the container starts meshagent process join ... inside it. Validate and deploy it:

bash

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

Use --global instead of --room myroom to deploy the same manifest as a project service.

Example 2: `ServiceTemplate` with `container`

Use kind: ServiceTemplate when the manifest shape stays the same but some values should be supplied during deployment or install.

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: "meshagent/cli:default"
  command: >-
    meshagent process join
    --agent-name my-language-chatbot
    --channel chat
    --web-search
    --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.md"
  environment:
    - name: MESHAGENT_TOKEN
      token:
        identity: my-language-chatbot
  storage:
    room:
      - path: /data
        read_only: false

This example adds a language variable and uses {{ language }} inside the container.command. Validate and deploy it:

bash

meshagent service validate-template --file meshagent.yaml

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

Use --global instead of --room myroom to deploy the rendered service project-wide. If you want to inspect the rendered YAML first, use meshagent service render-template --file meshagent.yaml --value language=Spanish.

Example 3: `Service` with `external`

Use external when MeshAgent should route to a service you already host elsewhere instead of running a container for you.

kind: Service
version: v1
metadata:
  name: mcp-deepwiki
  description: "Expose the DeepWiki MCP server"
ports:
  - num: 443
    type: http
    endpoints:
      - path: /mcp
        mcp:
          label: "mcp-deepwiki"
          description: "MCP DeepWiki tools"
          allowed_tools:
            - tool_names: ["search", "read_page"]
              read_only: true
external:
  url: "https://mcp.deepwiki.com"

This example is a fixed Service that routes to an MCP server hosted outside MeshAgent. MeshAgent does not run the MCP server. It uses the external.url and ports.endpoints config to register that server’s tools in the room. Validate and deploy it:

bash

meshagent service validate --file mcp-service.yaml
meshagent service create --file mcp-service.yaml --room myroom

If you need installer-provided values such as a URL, label, or OAuth settings, you can use external inside a ServiceTemplate too. For a longer walkthrough, see Connect to an External MCP Server.

Manage deployed services

Use meshagent service after deployment to inspect and manage what you deployed.

bash

# List project services
meshagent service list

# List room services
meshagent service list --room myroom

# View details for one service
meshagent service get SERVICE_ID

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

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

# Delete a deployed service
meshagent service delete SERVICE_ID --room myroom

Omit --room myroom when you are updating, listing, or deleting a project service instead.

Service configuration field reference

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.
`files`	No	Files MeshAgent should seed into room storage if they do not already exist.
`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.
`channels`	object	No	Channel-specific routing config for mail, messaging, queues, and toolkits.
`email`	object	No	Mailbox settings for this agent identity.
`heartbeat`	object	No	Recurring queue turn for this agent.

agents.channels

Use channels when one deployed agent should participate in more than one entry point.

Field	Type	Required	Description
`email`	list	No	Inbound email channels for the agent.
`messaging`	list	No	Messaging channels and optional named prompts.
`queue`	list	No	Queue channels the agent should consume.
`toolkit`	list	No	Toolkits the agent should register or expose.

Queue channel entries support:

Field	Type	Required	Description
`queue`	string	Yes	Queue name the agent should consume.
`threading_mode`	string	No	Threading mode for queue-delivered work, such as `default-new`.
`message_schema`	object	No	JSON schema describing expected queue payload shape.

Messaging channel entries support:

Field	Type	Required	Description
`protocol`	string	No	Messaging protocol. Defaults to `meshagent.agent-message.v1`.
`prompts`	list	No	Named prompts available on that messaging channel.

agents.email

Use email when the agent identity itself should have mailbox settings attached to it.

Field	Type	Required	Description
`address`	string	Yes	Email address for the agent.
`public`	boolean	No	Whether anyone can send to it. Defaults to `false`.

agents.heartbeat

Use heartbeat when the agent should enqueue a recurring turn for itself without creating a separate scheduled-task resource by hand.

Field	Type	Required	Description
`queue`	string	Yes	Queue that receives the recurring work item.
`thread_id`	string	No	Optional thread path or template. Time tokens such as `{year}`, `{month}`, `{day}`, `{hour}`, and `{minute}` are expanded at runtime. Token matching is case-insensitive, so `{YYYY}/{MM}/{DD}/{HH}/{mm}` also works.
`prompt`	list	Yes	Prompt content for each heartbeat turn. Uses typed content items such as `text` and `file`.
`minutes`	integer	Yes	Interval, in minutes, between heartbeats.

Heartbeat prompt items use the same typed content model as agent turns:

Field	Type	Required	Description
`type`	string	Yes	`text` or `file`.
`text`	string	No	Text content when `type: text`.
`url`	string	No	File URL when `type: file`, including `room:///...` references.

Example:

agents:
  - name: assistant
    annotations:
      meshagent.agent.type: ChatBot
      meshagent.chatbot.threading: "default-new"
      meshagent.chatbot.thread-dir: agents/assistant/threads
    email:
      address: assistant@example.com
      public: true
    heartbeat:
      queue: assistant-scheduled-tasks
      thread_id: /agents/assistant/threads/heartbeats/{year}/{month}/{day}/{hour}.{minute}.thread
      prompt:
        - type: file
          url: room:///agents/assistant/heartbeat.md
      minutes: 60

files:
  - path: /agents/assistant/heartbeat.md
    text: |
      # Assistant Heartbeat
      Review recent room activity, unresolved requests, and any obvious follow-up work.
      If there is clear useful work to do, do it directly.
      If there is nothing useful to add, end the turn quietly without posting a filler message.
      Previous threads can be found looking at the threads in the path format based on the time: /data/agents/assistant/threads/heartbeats/{year}/{month}/{day}/{hour}.{minute}.thread
      Read the last few heartbeat threads to make sure you are up to date with what has been done so far

This mirrors the built-in assistant service template: each heartbeat run is queued to the assistant, uses the heartbeat prompt file from room storage, and writes the run into a timestamped thread under the assistant thread directory.

files

Top-level files seed room storage before the service starts. MeshAgent creates each file only if it does not already exist, which makes this useful for editable starter content such as prompts, rules, or templates.

Field	Type	Required	Description
`path`	string	Yes	Room-storage path to create.
`text`	string	Yes	Initial file contents.

Use top-level files when the content should live in room storage and remain editable after deploy. Use container.storage.files when the file should be mounted inside the running container itself.

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 (for example `meshagent/cli:default`).
`template`	`"agent"` or `"none"`	No	Runtime defaults to apply when the container starts. Defaults to `"agent"`.
`command`	string	No	Command to execute when the container starts.
`working_dir`	string	No	Absolute working directory used when starting the container command.
`environment`	list	No	Environment variables to set in the container.
`run_as`	object	No	Service account identity and runtime scopes. Required when using `SecretValue` environment variables.
`storage`	object	No	Storage volumes to mount 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 for the life of that container instance. Default: read-only.
`private`	boolean	No	Advanced setting that keeps interactive container access private to the owning service. Default: true.

container.template

container.template controls the MeshAgent runtime defaults added when the container starts:

"agent" (default): mount room storage at /data, create a participant token for the container name with role agent and default agent API permissions, and inject MeshAgent/OpenAI/Anthropic runtime environment variables.
"none": do not add those defaults. Only values explicitly configured in the manifest or container start request are passed through.

The "agent" template sets defaults only when the environment variable is not already configured. Values in container.environment override template defaults. The "agent" template may set:

Variable	Description
`MESHAGENT_TOKEN`	Room participant token for the container name, with role `agent` and default agent API permissions.
`OPENAI_API_KEY`	Same participant token, for OpenAI-compatible clients using MeshAgent’s proxy.
`ANTHROPIC_API_KEY`	Same participant token, for Anthropic-compatible clients using MeshAgent’s proxy.
`SMTP_PASSWORD`	Same participant token, for SMTP authentication.
`SMTP_USERNAME`	Container name, for SMTP authentication.
`SMTP_HOSTNAME`	MeshAgent SMTP hostname, set from `MESHAGENT_MAIL_DOMAIN` when available.
`SMTP_PORT`	SMTP port. Defaults to `587`.
`OPENAI_BASE_URL`	OpenAI-compatible MeshAgent proxy URL for the room runtime.
`ANTHROPIC_BASE_URL`	Anthropic-compatible MeshAgent proxy URL for the room runtime.
`MESHAGENT_API_URL`	MeshAgent API URL reachable from the container.
`MESHAGENT_ROOM_URL`	MeshAgent room API base URL reachable from the container.
`MESHAGENT_ROOM`	Current room name.
`MESHAGENT_PROJECT_ID`	Current project ID, when available.
`MESHAGENT_SESSION_ID`	Current session ID, when available.
`OTEL_ENDPOINT`	OpenTelemetry collector endpoint reachable from the container.
`OTEL_PYTHON_LOG_LEVEL`	Python OpenTelemetry log level forwarded from the room runtime, when available.
`MESHAGENT_MAIL_DOMAIN`	MeshAgent mail domain forwarded from the room runtime, when available.

container.run_as

container.run_as selects the service account identity used by the container. The default scope list grants access to the HTTP/MCP secret proxy without granting broad project administration.

Field	Type	Required	Description
`email`	string	Yes	Service account email the container runs as.
`scopes`	list of strings	No	Runtime scopes for the service-account token. Defaults to `["secrets:proxy"]`.

container.environment

Each entry sets an environment variable in the container. A variable can come from a literal value, a MeshAgent token, or a service-account secret.

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.
`secret`	object	No	Load a secret available to the service account in `container.run_as` and inject it as the value.

Use:

value for plain configuration
token for MeshAgent API access
secret for service-account credentials. container.run_as is required when any environment variable uses secret.

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 (for example `user`, `agent`, or `tool`).

secret fields:

Field	Type	Required	Description
`id`	string	Yes	Secret ID to load for the service account in `container.run_as`.

This pattern is common for services: token gives the service access to MeshAgent, while secret gives it an external credential through its service account.

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.
`empty_dirs`	list	Writable temporary directories mounted into the container.
`configs`	list	MeshAgent runtime config mounts such as `spec.json` and `members.json`.

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.

Empty directory mount fields:

Field	Type	Required	Description
`path`	string	Yes	Mount path inside the container.
`read_only`	boolean	No	Whether the temporary directory is read-only.

Config mount fields:

Field	Type	Required	Description
`path`	string	Yes	Directory inside the container where MeshAgent runtime config files should be mounted. Defaults to `/var/run/meshagent`.

Config mounts are useful when a shell tool or helper process inside the container needs access to runtime files such as spec.json and members.json.

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.
`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.
`annotations`	object	No	Key-value metadata.

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. Template values are rendered into the manifest before validation, so they can be used anywhere the resulting YAML remains valid.

Field	Type	Required	Description
`name`	string	Yes	Variable identifier. Referenced as `{{ name }}` in templates.
`title`	string	No	Human-readable label shown in install UI.
`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 (for example `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 documentation.

Agent annotations

Set in agents[].annotations.

Key	Description
`meshagent.agent.type`	Internal agent type metadata used by service manifests and generated specs.
`meshagent.agent.widget`	UI widget to display for this agent.
`meshagent.agent.schedule`	JSON string defining a `ScheduledTaskSpec`. Use either `queue: { name, payload }` or `container`, not both.
`meshagent.agent.shell.command`	Shell command for `Shell`-type agents.
`meshagent.agent.dataset.schema`	Dataset schema metadata for the agent.

Variable annotations

Set in variables[].annotations.

Key	Description
`meshagent.secret.id`	Suggested secret identifier for installer-collected credential variables.
`meshagent.secret.name`	Display name for installer-collected credential variables.
`meshagent.secret.type`	Credential content type for installer-collected variables.

Event annotations

Set in agents[].annotations. Subscribe an agent to room events. The value is the name of a queue that a queue-consuming agent can 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.

​Example 1: Service with container

​Example 2: ServiceTemplate with container

​Example 3: Service with external

​Manage deployed services

​Service configuration field reference

​Top-level fields

​metadata

​agents

​agents.channels

​agents.email

​agents.heartbeat

​files

​container

​container.template

​container.run_as

​container.environment

​container.storage

​external

​ports

​ports.endpoints

meshagent endpoint

mcp endpoint

​variables (ServiceTemplate only)

​Annotations

​Service annotations

​Agent annotations

​Variable annotations

​Event annotations

​Read next

Example 1: `Service` with `container`

Example 2: `ServiceTemplate` with `container`

Example 3: `Service` with `external`

Manage deployed services

Service configuration field reference

Top-level fields

metadata

agents

agents.channels

agents.email

agents.heartbeat

files

container

container.template

container.run_as

container.environment

container.storage

external

ports

ports.endpoints

variables (ServiceTemplate only)

Annotations

Service annotations

Agent annotations

Variable annotations

Event annotations

Read next