Skip to main content
Project secrets are credentials managed at the project level, often used by your long-running backend services. They’re not tied to any individual user, but to your project as a whole. There are two main types of project secrets:
  • Secret Keys: Named collections of key/value pairs that are injected into the container as environment variables at runtime.
  • Image Pull Secrets: Credentials used by MeshAgent to pull private container images from a registry. These are used only by the orchestration layer and are never injected into the running container.

​
When to use

  • You need shared credentials for project services (DB URIs, service API keys, webhook secrets).
  • You need registry credentials to pull private images.
  • You want stable configuration that persists across rooms and redeploys.
  • You do not need per-user tokens during a live room session (use the Secrets API for this).

​
Project vs. Room Services and Secrets

  • Project Services: Always-available, shared across all rooms in a project. These are the services you (as a developer and admin) deploy to run your app. Project services can reference Secret Keys or Image Pull Secrets in their manifests.
  • Room Services: On-demand, sandboxed containers launched through the Containers API. These are often started by end users through your app. For security, room services cannot access your project’s secrets or image pull secrets. Instead, they rely on launch-time environment variables, user-supplied values, or the secrets API.

​
Secret Keys (used for Project Services)

​
What they are

A Secret Key is a named collection of key/value pairs (for example API_KEY, DB_URI). When attached to a service, each entry is injected as an environment variable inside the container. Your code can then access these values at runtime (process.env.MY_API_KEY, $DB_URI, etc.).

​
How they work

  • When you attach a Secret Key to a service, MeshAgent mounts each entry as an environment variable.
  • Your service code can read these variables at startup (e.g. process.env.MY_API_TOKEN).
  • Individual secrets are never exposed outside the container, and each service only sees its own assigned keys.
  • Easy to rotate by creating a new secret and updating the service configuration.

​
Configuration (MeshAgent Studio):

  1. Define a Secret Key
    • Navigate to Secrets → New Secret Keys.
    • Add a name for your new secret key collection (e.g. weather-api-credentials)
    • Add key/value entries (e.g. WEATHER_API_KEY, WEATHER_API_ENDPOINT)
    • Click “Create Secret”
  2. Attach it to your service
    • In the Services tab, select your service (or create it if it doesn’t already exist)
    • Under Environment & Secrets choose the secret key collection to bind
    • Save; on the next session launch, the values will be available as environment variables.

​
Configuration (MeshAgent CLI):

  1. Create a new secret: 
    meshagent secret keys create --name weather-api-credentials --data WEATHER_API_KEY=xxx WEATHER_API_ENDPOINT=yyy
    This will return the ID for this secret key. You can also return a list of secret names and IDs in your project by running meshagent secret list. Use the secret ID (not the name) in your manifest.
  2. Reference Secret ID in Service Manifest: Create or update your YAML ServiceSpec with the applicable secret IDs. For a project-wide service you’ll create a YAML file of kind Service. This YAML file provides the configuration information required to deploy the service. When the spec is converted to a deployable Service, MeshAgent translates the secrets into environment secrets which are injected as environment variables at runtime. 
      version: v1
  kind: Service
  name: weather-agent
  image: gcr.io/example/weather:latest
  secrets:
    - secret-1234567890
  3. Create Service from Service Spec: Run the CLI commands to deploy the service using your applicable secrets. 
    meshagent service create --file service.yaml

​
Image Pull Secrets (used for Project Services)

​
What they are

An Image Pull Secret stores credentials required to authenticate against a private container registry (e.g. Docker Hub private repos, Azure Container Registry, AWS ECR).

​
How they work

  • MeshAgent uses the pull secret when fetching your service’s container image.
  • Credentials are never exposed inside the running container; they’re only used by the orchestration layer.

​
Configuration (MeshAgent Studio):

  1. Create an Image Pull Secret
    • Go to the Secrets section and select New Image Pull Secret
    • Name the pull secret (e.g. acme-priv-registry)
    • Select the registry you want to use (GCP Artifact Registry, Azure Container Registry, or Other)
    • Enter required information (e.g. repository name, service account, service principal ID, etc.)
    • Click “Create Secret”
  2. Attach to a Service
    • In the Services tab, edit the service that uses a private image
    • Under Image, specify the image tag
    • Under Image Pull Secret, select the secret you created
    • Under Command add the command to run the container, if not specified, it will default to the entrypoint of the container
    • Save; MeshAgent will authenticate using these credentials whenever it starts the service

​
Configuration (MeshAgent CLI):

  1. Create an Image Pull Secret: There are different subcommands for each registry. 
    # Docker Hub
meshagent secret docker create --name docker-hub --server myregistry.docker.io --username user --password ****

# Azure Container Registry
meshagent secret acr create --name my-acr --server myregistry.azurecr.io --username serviceprincipalid --password ****

# GCP Artifact Registry
meshagent secret gar create --name gcp-registry --server us-docker.pkg.dev --json_key ****
    This will return the ID for the pull secret. You can also use the —help flag for additional details.
  2. Reference Image Pull Secret in Manifest: Pass in the ID for the pull secret and MeshAgent will use this to pull the appropriate image at runtime.
    yaml
    version: v1
kind: Service
name: weather-agent
image: registry.example.com/weather:latest
pull_secret: secret-abcdef123
  3. Create Service from Service Spec: Run the CLI commands to deploy the service using your applicable pull secret. 
    meshagent service create --file service.yaml

​
Supplying Sensitive Values to Room Services

Room services launched with the Containers API cannot consume project-level Secret Keys or Image Pull Secrets. This is by design, room services are sandboxed environments for running user-initiated code in a container, and they must not have access to your app’s infrastructure secrets. However, you can still use private images with room services by passing credentials directly through the Containers API or CLI at launch time. These credentials are used only for image pulling and are not exposed to the running container. For runtime secrets (API keys, configuration values, etc.), use ServiceTemplate parameters to define what your room services need:

​
Using ServiceTemplate manifests

A ServiceTemplate manifest defines what inputs a container accepts and how they map to environment variables. See the packaging services documentation for more details.
  • User-supplied parameters → Declared under variables: (with obscure: true for sensitive inputs) and mapped into environment:. These are provided by end users through your app at runtime.
  • App-supplied values → Declared only under environment:. These must be provided by your project services when launching the container and are not visible to end users.
For example, if you create a Research Agent that users can add to their rooms, you would create a ServiceTemplatemanifest for the agent. This manifest might allow users to pass a system prompt at runtime so they can customize the agent’s behavior, but as the agent creator you might maintain a guardrail prompt that users cannot modify, or pass additional API keys to specialized research sites. 
version: v1
kind: ServiceTemplate
name: research-agent
# User supplied variables at runtime
variables:
  - name: research_system_prompt
    description: "Special instructions for the research agent"
environment: 
  # Variables from user are mapped to environment 
  - name: RESEARCH_SYSTEM_PROMPT 
    value: "{research_system_prompt}"
  # App-supplied and injected by a project service at launch
  - name: RESEARCH_API_KEY     
    value: "{research_api_key}"
  - name: GUARDRAIL_PROMPT 
    value: "{guardrail_prompt}"

​
Using the MeshAgent CLI

You can also run containers directly using the MeshAgent CLI. Pass credentials or environment variables directly when starting a container. 
meshagent container run --image registry.example.com/tools:latest --env API_KEY=xxxx
You can also use the --cred flag for registry authentication. See the CLI docs for details.

​
Best Practices

  • Use Secret Keys for API tokens, DB URIs, and project-wide credentials.
  • Use Image Pull Secrets only for private registries.
  • For room services, prefer launch-time variables, never hardcode values.
  • Rotate regularly: create new secrets, update manifests, redeploy, then delete old secrets.
  • Limit scope: attach secrets only to the services that need them.
  • Audit unused secrets periodically (meshagent secret list or Studio UI).
By defining Secret Keys and Image Pull Secrets for project services, and using launch-time variables for room-specific services, you keep sensitive data secure, scoped, and easily managed — ensuring that project services have the credentials they need to run your app, while room services remain safe, sandboxed environments for user-driven code.