> ## 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.

# Configuration Overview

> Mirage's configuration is YAML, or the same fields sent through the API.

Mirage's configuration is plain data. Write it as YAML and hand it to the
`mirage` CLI, or send the same fields as JSON to the [server API](https://docs.mirage.strukto.ai/api/reference.md).
Both take one schema. The CLI fills in `${NAME}` and resolves script paths
before it sends a config; the API takes it as written. See
[Values and paths](https://docs.mirage.strukto.ai/home/configuration/workspace.md#values-and-paths).

```yaml workspace.yaml theme={null}
mounts:
  /data: { vfs: ram, mode: write }
profiles:
  reader:
    mounts:
      /data: { mode: read }
```

```bash CLI theme={null}
mirage workspace create workspace.yaml --id demo
```

```bash API theme={null}
curl -s http://127.0.0.1:8765/v1/workspaces \
  -H "Authorization: Bearer $MIRAGE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"id": "demo", "config": {"mounts": {"/data": {"vfs": "ram", "mode": "write"}}, "profiles": {"reader": {"mounts": {"/data": {"mode": "read"}}}}}}'
```

## Levels

Settings live at three levels. A server runs workspaces, and each workspace
runs sessions.

| Level | What it sets | In a file | Through the API |
| - | - | - | - |
| [Server](https://docs.mirage.strukto.ai/home/configuration/server.md) | Port, sign-in, rate limits, and the ceilings every workspace stays under | `~/.mirage/config.toml` or `MIRAGE_*` environment variables | Read when the server starts |
| [Workspace](https://docs.mirage.strukto.ai/home/configuration/workspace.md) | Mounts, CLIs, runtimes, network, limits, and where state and caches live | `workspace.yaml` | `POST /v1/workspaces` with `config` |
| [Session](https://docs.mirage.strukto.ai/home/configuration/session.md) | What one session can run and see, and its own limits, network, `cwd` and `env` | A profile under `profiles` in `workspace.yaml` | `POST /v1/workspaces/{id}/sessions` with `profile` |

In an app, `Workspace(...)` takes the same workspace config in code.
Limits can be set at all three levels; see [Limits](https://docs.mirage.strukto.ai/home/limits.md). A config
never holds a secret, only a pointer to one; see
[Service Credentials](https://docs.mirage.strukto.ai/home/service-credentials.md).


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