> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Service credentials

> Connect VFS and CLI credentials from the environment or a secret store.

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](/home/access/http#configure-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:

```bash theme={null}
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](/home/access/cli#daemon).

```yaml workspace.yaml theme={null}
mounts:
  /slack:
    vfs: slack
    config:
      token:
        from: env
        key: SLACK_BOT_TOKEN
```

See [Slack setup](/home/setup/slack) for the token and required scopes. Then
create the workspace and check a read:

```bash theme={null}
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.

```dotenv .env theme={null}
SLACK_BOT_TOKEN=xoxb-your-token
```

```yaml workspace.yaml theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.