Skip to main content
MeshAgent has three secret types:
  • Project keys secrets for shared runtime credentials used by project 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 have not installed the CLI yet, start with CLI Quickstart.

​
How to choose

Secret typeUse it forStored inRead byHow you reference it
Project keys secretShared runtime credentials for project servicesThe projectThe running service containercontainer.secrets
Room secretRoom-local or identity-scoped credentials for room services, toolkits, and participantsA 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 keys 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. MeshAgent can use its managed routing by default, or let you switch to your own provider credentials at the project level. 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 values
  • Environment variables are one way to deliver values into a container

​
What a secret does and does not do

A secret is meant to keep a sensitive value out of your manifest, source code, and UI while still making it available to the specific runtime that needs it.
  • the service process can read a secret that is injected at runtime
  • the model does not automatically see that secret value
  • the value is only exposed to the model if your code, tools, logs, or prompts explicitly pass it through
This is why secrets are still useful for agents and services:
  • they are stored securely
  • they are delivered only to the specific service that needs them
  • they are not hardcoded in YAML or checked into source control
  • they can be rotated or revoked without changing the service code

​
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. It does not create a fourth secret type. Instead:
  • 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:
This is useful when you want each installer to bring their own credential, for example:
  • a GitHub agent where each installer provides their own GitHub token
  • a Supabase toolkit where each installer provides their own Supabase token
  • a Stripe-enabled service where each installer provides their own Stripe secret key
If you are using the CLI directly instead of Powerboards, you typically create the room secret yourself with meshagent room secret set.

​
Next steps