Skip to main content
MeshAgent has three main secret types:
  • Project Secrets for shared runtime credentials used by deployed services
  • Room Secrets for room-scoped or identity-scoped credentials used by room services, toolkits, and participants
  • Image Pull Secrets for registry credentials used only to pull private images
If you need to request and store a user OAuth credential in a room, that is an advanced Room Secrets workflow. See OAuth with Room Secrets.

​
How to choose

Secret typeUse it forStored inRead byHow you reference it
Project SecretShared runtime credentials for deployed servicesThe projectThe running service containercontainer.secrets
Room SecretRoom-local or identity-scoped credentials for services, toolkits, and participant flowsA room, scoped to an identityA room service, toolkit, or participant flowcontainer.environment[].secret, room.secrets, --header-secret
Image Pull SecretCredentials to pull a private container imageThe projectMeshAgent while pulling the imagecontainer.pull_secret
Use a project secret when the running service needs the credential at runtime. Use a room secret when the credential belongs to one room or one identity. Use an image pull secret when MeshAgent only needs the credential to download the image before startup. For OpenAI and Anthropic specifically, check whether you should use MeshAgent Studio Integrations and the LLM proxy instead of creating a generic secret. Two related concepts often appear next to secrets, but they are not secret types:
  • Token: a MeshAgent-issued credential that gives a service access to MeshAgent APIs
  • Plain environment variable: a literal value written directly into a service spec or passed at launch
The distinction is:
  • Tokens authorize MeshAgent access
  • Secrets store sensitive external values
  • Environment variables are one way to deliver values into a container
If you are deciding what a service can do inside MeshAgent, see Participant Tokens and API Scopes.

​
What a secret does and does not do

A secret keeps a sensitive value out of your manifest, source code, and UI while still making it available to the runtime that needs it.
  • the service process can read a secret that is injected at runtime
  • the model does not automatically see that value
  • the value is only exposed to the model if your code, tools, logs, or prompts explicitly pass it through

​
If you are packaging and sharing a service

ServiceTemplate is the secure way to collect installer-provided secrets when you are sharing an agent, toolkit, or service with other people. In practice:
  • a ServiceTemplate variable is the input field shown to the installer
  • Powerboards can store that value as a room secret using meshagent.secret.* annotations
  • the installed service later reads that stored room secret with secret:
If you are using the CLI directly instead of Powerboards, you typically create the room secret yourself with meshagent room secret set.