AWS Secrets Manager

A pointer with from: aws-sm reads a secret from AWS Secrets Manager when the workspace starts. The value stays in the memory of the process running the workspace; see how credentials work.

Install

Python
TypeScript

Install the extra where Mirage runs:

# the mirage CLI
uv tool install 'mirage-ai[aws-sm]'
# a Python project
uv add 'mirage-ai[aws-sm]'

npm install @aws-sdk/client-secrets-manager

Give Mirage access

Mirage uses the AWS SDK’s standard credentials: environment variables, a profile, SSO or an instance role. The region comes from the profile, AWS_DEFAULT_REGION in Python or AWS_REGION in TypeScript. That identity needs secretsmanager:GetSecretValue on the secrets the workspace reads, and kms:Decrypt if a secret uses a customer managed key:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:mirage/*"
    }
  ]
}

Store a secret

aws secretsmanager create-secret \
  --name mirage/slack \
  --secret-string '{"SLACK_BOT_TOKEN":"xoxb-your-token"}'

A secret holding a JSON object of strings gives each field name as a key. A secret holding any other text is read with key: value. Mirage reads SecretString only, not binary secrets.

Point at it

workspace.yaml

mounts:
  /slack:
    vfs: slack
    config:
      token:
        from: aws-sm
        ref: mirage/slack
        key: SLACK_BOT_TOKEN

ref is the secret’s name or ARN.

Use other credentials

To read with credentials other than the process’s own, such as a second account, declare a source with its own settings and use its name in from:

workspace.yaml

secrets:
  prod:
    source: aws-sm
    config:
      region: us-east-1
      aws_access_key_id:
        from: env
        key: PROD_AWS_ACCESS_KEY_ID
      aws_secret_access_key:
        from: env
        key: PROD_AWS_SECRET_ACCESS_KEY

mounts:
  /slack:
    vfs: slack
    config:
      token:
        from: prod
        ref: mirage/slack
        key: SLACK_BOT_TOKEN

Setting	Meaning
`region`	The region to read from.
`aws_access_key_id`, `aws_secret_access_key`	An access key, set together.
`aws_session_token`	The session token for temporary keys.
`aws_profile`	A profile from your AWS config files.

Keys in a source’s config can read only from env or a dotenv file.

Cloudflare Workers

A Worker has no AWS credential files or default chain, so the source’s config must give region, aws_access_key_id and aws_secret_access_key. aws_profile isn’t available. See Read secrets from AWS and 1Password.

Getting Started

Examples

Agents

Configuration

VFS

Integration

CLIs

Mirage Shell

Policy

Machines

Infrastructure

Notifications

Help