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

# Workspace Configuration

> Configure a workspace with workspace.yaml.

A workspace config describes one virtual terminal. `mounts` is the only
required key:

```yaml workspace.yaml theme={null}
mounts:
  /data:
    vfs: ram
```

```bash theme={null}
mirage workspace create workspace.yaml --id demo
mirage shell -w demo -c 'echo ready > /data/status && cat /data/status'
```

Keys are `snake_case`; TypeScript constructor options use camelCase, such as
`commandLimits`. Unknown keys are errors. A template saved on the server takes
the same document.

## Workspace settings

| Key | Sets |
| - | - |
| `mounts` | Virtual prefixes and their VFSs. See [Mount settings](#mount-settings). |
| `mode` | Default mount access: `read`, `write` or `exec`. YAML defaults to `write`, the `Workspace` constructors to `read`. |
| `read`, `write` | Default [read and write behavior](https://docs.mirage.strukto.ai/home/setup/vfs.md#read-and-write-behavior) for every mount. |
| `clis` | [Virtual CLIs](https://docs.mirage.strukto.ai/home/setup/clis.md) by command name. See [CLI entries](#cli-entries). |
| `machines` | The [machines](https://docs.mirage.strukto.ai/home/setup/machine/overview.md) programs run on. |
| `route_policy` | Which [machine](https://docs.mirage.strukto.ai/home/policy/route-machine.md) a line runs on. |
| `profiles`, `profile` | [Session profiles](https://docs.mirage.strukto.ai/home/configuration/session.md) and the default one. |
| `processes` | Whose processes a session lists and stops, and how many it runs: `128` by default. |
| `command_limits` | [Output and execution limits](https://docs.mirage.strukto.ai/home/limits.md#command-output). |
| `max_memory` | Memory cap, as a [size](#sizes): `96MB` by default, `null` for none. |
| `max_env` | Cap on each session's variables, functions and aliases: `2MB` by default. |
| `max_body_bytes` | Largest API reply read whole: `64MB` by default. |
| `network` | Where connections may go. See [Network](#network). |
| `system_time` | The clock's start time. See [System time](#system-time). |
| `env`, `secrets` | Session environment and [credential sources](https://docs.mirage.strukto.ai/home/service-credentials.md). |
| `store`, `cache`, `index` | Where state and caches live. See [State and caches](#state-and-caches). |
| `io` | Byte-queue capacity, as `buffer_bytes`. |
| `workspace_id`, `default_session_id` | Fixed ids instead of generated ones. |

## Mount settings

Each mount key is an absolute prefix, such as `/data`. Its value is a block
of the keys below, or `"@<machine>"`: that machine's own files at the same
path, as `/tmp: "@gpu"` shows the `gpu` machine's `/tmp`. The name must be one
under `machines:`. See [Machine Files](https://docs.mirage.strukto.ai/home/setup/machine/machine_files.md).

| Key | Sets |
| - | - |
| `vfs` | Required. A registered VFS, such as `ram` or `s3`. |
| `config` | The VFS's own fields, from its [setup guide](https://docs.mirage.strukto.ai/home/setup/vfs.md). |
| `mode`, `read`, `ttl`, `write` | Overrides of the workspace defaults. `read: bounded` needs `ttl` in seconds. |
| `command_limits`, `index` | Overrides for this mount. |
| `backend`, `mountpoint` | Where the mount shows up, below. |

| `backend` | The mount shows up |
| - | - |
| `workspace` | Inside Mirage only. The default. |
| `fuse` | As a local folder, through [FUSE](https://docs.mirage.strukto.ai/home/setup/fuse.md). |
| `fskit` | As a local folder, through FSKit on macOS 15.4 or later. |
| `nfs` | As a read-only local folder, through the system's NFS client. Linux needs root. A file whose size is unknown until read shows up empty; use `fuse` for that VFS. |

## Network

| `network` | Connections go |
| - | - |
| `true` | Anywhere. The default. |
| `false` | Nowhere. |
| `allowed_domains: [...]` | Only to what the list names. |
| `denied_domains: [...]` | Anywhere but what the list names. |

```yaml theme={null}
network:
  allowed_domains:
    - api.github.com:443
    - "*.slack.com"
    - 10.0.0.0/8
  denied_domains:
    - "*:22"
```

| Entry | Matches |
| - | - |
| `*` | Every host. |
| `api.github.com` | That host. |
| `*.slack.com` | Every host under that name. |
| `10.0.0.0/8` | An address or range. |
| `:443` at the end | Only that port. IPv6 writes `[::1]:8080`. |

* A denied entry wins over an allowed one.
* A refused connection fails like a closed port: `curl` exits 7.
* Mounts connect under the same rules. A [profile](https://docs.mirage.strukto.ai/home/configuration/session.md)
  can narrow them, and [`routes`](https://docs.mirage.strukto.ai/home/policy/route-network) redirect a host.
* Programs on a [machine](https://docs.mirage.strukto.ai/home/setup/machine/overview.md) connect under the
  machine's own network. A `host` machine refuses to run while `network`
  limits anything.
* In a browser or on an edge runtime, only host names are checked, and a
  `denied_domains` address or range is refused. Deny host names there.

## System time

```yaml theme={null}
system_time: 2026-03-02T09:00:00Z
env:
  TZ: America/New_York
```

The clock starts at that time and runs forward. `date`, file times, `find
-mtime`, git commits and the Monty, WASI, Pyodide and QuickJS runtimes see it. Programs on a `host`
machine see it only through [libfaketime](https://docs.mirage.strukto.ai/home/setup/machine/host.md). `TZ` picks the zone,
UTC by default. Without `system_time`, the workspace uses the server's clock.

## CLI entries

Each `clis` key is the command name. An entry takes `cli` or `script`, and a
`machine`:

```yaml theme={null}
clis:
  slack:
    cli: slack
    machine: in_process
    config:
      token: {from: env, key: SLACK_TOKEN}
  pager:
    script: pager.py
    machine: in_process
machines:
  py:
    provider: in_process
    runtime: monty
```

| Key | Sets |
| - | - |
| `cli` | A registered [CLI](https://docs.mirage.strukto.ai/home/setup/clis.md). |
| `script` | A `.py`, `.js` or `.mjs` program, as a custom CLI in [Python](https://docs.mirage.strukto.ai/python/cli/new.md) or [TypeScript](https://docs.mirage.strukto.ai/typescript/cli/new.md). |
| `machine` | Required. `in_process`, or `host` for a script. A script needs a `machines` entry that runs its language. |
| `runtime` | The runtime for a script on `in_process`, such as `monty`. |
| `config` | The CLI's fields. A script's `config` takes no credential pointer. |

## State and caches

| Key | Holds | Details |
| - | - | - |
| `store` | Symlinks, attributes, sessions, command logs and jobs | [Namespace](https://docs.mirage.strukto.ai/home/infrastructure/namespace.md), [Sessions](https://docs.mirage.strukto.ai/home/infrastructure/sessions.md), [Jobs](https://docs.mirage.strukto.ai/home/infrastructure/jobs.md) |
| `cache` | File content | [File Cache](https://docs.mirage.strukto.ai/home/infrastructure/file-cache.md) |
| `index` | Directory listings and metadata | [File Index](https://docs.mirage.strukto.ai/home/infrastructure/file-index.md) |

A `cache` or `index` block needs a `type`. A `store` without one keeps in
memory each part (`namespace`, `sessions`, `logs`, `execution`) that names no
store of its own.

## Values and paths

* `${NAME}` takes the value from the environment when the config loads. A
  missing variable is an error. `mirage workspace create` fills it in before
  sending; the server never does.
* Script paths resolve from the config file's folder.

## Sizes

A size is bytes, or a number with `K`, `M` or `G` and an optional `B`. `K` is
1024 bytes.

| Write | Bytes |
| - | - |
| `512K` | 524,288 |
| `100MB` | 104,857,600 |
| `1g` | 1,073,741,824 |

`1.5GB`, `100 MB` and `100MiB` are refused.


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