Skip to main content
Project keys secrets store shared runtime credentials for project services. Use them for credentials such as:
  • a shared SERVICE_API_TOKEN for a project-owned agent or integration
  • DATABASE_URL
  • STRIPE_SECRET_KEY
  • other shared API keys used by backend services
When you reference a project keys secret with container.secrets, MeshAgent injects each key/value pair into the running container as environment variables at runtime. Project keys secrets are for application credentials that the service needs while it is running. If the credential belongs to a specific room or identity, use room secrets. If the credential is only for authenticating a private image pull, use image pull secrets.
Note: OpenAI and Anthropic credentials are often handled through MeshAgent Studio Integrations and the LLM proxy, not as generic project keys secrets. In MeshAgent Studio, users can switch the project to their own provider credentials or use MeshAgent-managed routing by default.

​
Before you start

These examples assume:

​
Create a project keys secret

bash
meshagent secret key create \
  --name support-agent-config \
  --data "SERVICE_API_TOKEN=replace-me"
This creates a project secret and returns its secret ID. To see existing project secrets:
bash
meshagent secret list

​
Reference it from a project service

Create a file named project-secret-demo.yaml: 
version: v1
kind: Service
metadata:
  name: support-agent
  description: "Project-wide support agent backed by meshagent process"
  annotations:
    meshagent.service.id: support-agent
agents:
  - name: support-agent
    description: "A support agent with a project-scoped runtime secret"
    annotations:
      meshagent.agent.type: ChatBot
      meshagent.chatbot.threading: default-new
      meshagent.chatbot.thread-list: .threads/support-agent/index.threadl
container:
  image: us-central1-docker.pkg.dev/meshagent-public/images/cli:{SERVER_VERSION}-esgz
  command: /bin/bash /var/start.sh
  environment:
    - name: MESHAGENT_TOKEN
      token:
        identity: support-agent
  secrets:
    - secret-1234567890
  storage:
    room:
      - path: /data
        read_only: false
    files:
      - path: /var/start.sh
        text: |
          #!/bin/bash
          set -e

          if [ -z "${SERVICE_API_TOKEN:-}" ]; then
            echo "SERVICE_API_TOKEN is required for support-agent" >&2
            exit 1
          fi

          exec /usr/bin/meshagent process join \
            --agent-name=support-agent \
            --channel=chat \
            --threading-mode=default-new \
            --thread-dir=".threads/support-agent" \
            --model=gpt-5.4 \
            --require-storage \
            --rule="You are a support agent. Help users with support workflows and never reveal credentials or secret values."
Replace secret-1234567890 with the secret ID returned by meshagent secret key create. When the service starts, MeshAgent loads the referenced keys secret and injects each entry as an environment variable.

​
Deploy the service

bash
meshagent service create --file project-secret-demo.yaml
This is a real MeshAgent agent service, not a placeholder container. The startup script checks that SERVICE_API_TOKEN exists and then starts meshagent process join --model=gpt-5.4 ... inside the MeshAgent CLI image. MeshAgent injects the actual stored secret value into the container environment at runtime, so the agent process really does receive the secret. It does not print the value, because logging secrets would be unsafe. This example is only showing how the secret reaches the agent. If you were building a real GitHub, Supabase, or Stripe integration, your bootstrap logic, toolkit setup, or custom tool layer would still need to read SERVICE_API_TOKEN and use it explicitly.

​
Update or delete a project secret

Update an existing secret:
bash
meshagent secret key update \
  --secret-id secret-1234567890 \
  --name support-agent-config \
  --data "SERVICE_API_TOKEN=replace-me-again"
Delete a secret:
bash
meshagent secret delete secret-1234567890

​
Best practices

  • Use project keys secrets only for shared runtime credentials used by project services.
  • Attach a secret only to the services that actually need it.
  • Avoid logging secret values from inside the container.
  • Rotate credentials by updating the secret and redeploying the service.