Service credentials

Give each VFS or virtual CLI the credentials it needs to reach its service. These differ from the bearer tokens and JWTs protecting a Mirage server; see HTTP authentication for those.

Connect from the environment

Set the credential in the environment of the process running Mirage, including on the server when your CLI connects remotely:

export SLACK_BOT_TOKEN=xoxb-your-token

If the local CLI daemon is already running, run mirage daemon restart after exporting the token. The next workspace creation inherits the updated environment. Restarting discards existing workspaces. See daemon commands.

workspace.yaml

mounts:
  /slack:
    vfs: slack
    config:
      token:
        from: env
        key: SLACK_BOT_TOKEN

See Slack setup for the token and required scopes. Then create the workspace and check a read:

mirage workspace create workspace.yaml --id credentials-demo &&
mirage shell -w credentials-demo -c 'ls /slack | head'

Remove the example workspace afterward with mirage workspace delete credentials-demo. The same pointer format works in credential fields for registered virtual CLIs.

Pointer fields

Key	Meaning
`from`	A built-in source name or a named instance under `secrets`.
`ref`	Source-specific address, such as a secret name or file path. Defaults to an empty string.
`key`	Field selected from the secret. Required in mount, CLI and source config pointers. Managed `env` entries default it to the variable’s name.

The env source uses only key, with no ref. A source needing settings is declared under secrets, and pointers use that instance’s name in from.

Read a dotenv file

Python needs the dotenv extra in the environment running Mirage. For the uv tool CLI, run uv tool install 'mirage-ai[dotenv]'. In a Python project, use uv add 'mirage-ai[dotenv]' and run its CLI with uv run mirage. The Node package includes dotenv support.

.env

SLACK_BOT_TOKEN=xoxb-your-token

workspace.yaml

secrets:
  team:
    source: dotenv
    config:
      path: .env

mounts:
  /slack:
    vfs: slack
    config:
      token:
        from: team
        key: SLACK_BOT_TOKEN

Use this config with the same workspace creation and read commands above. Relative dotenv paths use the Mirage process’s working directory. A pointer’s non-empty ref overrides the source’s configured path.

Other credential sources

`from`	`ref` example	`key` example	Prerequisite
`aws-sm`	`mirage/slack` or a secret ARN	`SLACK_BOT_TOKEN`	AWS credentials and region in the SDK’s normal environment. Python needs `mirage-ai[aws-sm]`; Node includes the source dependency.
`1password`	`op://Engineering/Slack/credential`	`credential`	`OP_SERVICE_ACCOUNT_TOKEN` in the Mirage process environment. Python needs `mirage-ai[1password]`; Node needs `@1password/sdk`.

Use these values in place of from, ref and key in the mount pointer above. Install source dependencies in the same environment that runs Mirage, using the tool or project installation method described for dotenv. AWS reads SecretString, not SecretBinary. A JSON object with string values exposes its field names as keys; other text is available under key: value. A 1Password field reference fetches that field. An item reference such as op://Engineering/Slack lets key select a field by its label. Source declarations accept source and optional config. Pointers inside a source’s config can read only from env or dotenv. Custom sources must be registered in the same process that creates the workspace.

Getting Started

Agents

VFS

Integration

CLIs

Mirage Shell

Agent Profiles

Policy

Runtimes

Configuration

Notifications

Access

Help

Service credentials

Connect from the environment

Pointer fields

Read a dotenv file

Other credential sources

​Connect from the environment

​Pointer fields

​Read a dotenv file

​Other credential sources

Connect from the environment

Pointer fields

Read a dotenv file

Other credential sources