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

# Infrastructure Overview

> Where a workspace keeps its data, and how to move it.

A workspace needs no services. A workspace you build in code keeps its state
in memory. A workspace the server builds keeps it on disk under
`~/.mirage/state`. Each store below can move onto infrastructure you run, on
its own or together with the others.

## Workspace state

Mirage creates this data, so none of your mounts, such as S3 or GitHub, has a
copy. The `store` key sets where Mirage saves it.

| Store | Holds | Backends | Key |
| - | - | - | - |
| [Namespace](https://docs.mirage.strukto.ai/home/infrastructure/namespace.md) | Symlinks and file attributes | `ram`, `disk`, `redis` | `store.namespace` |
| [Sessions](https://docs.mirage.strukto.ai/home/infrastructure/sessions.md) | Each session's working directory, variables and functions | `ram`, `disk`, `redis`, `s3` | `store.sessions` |
| [Command Logs](https://docs.mirage.strukto.ai/home/infrastructure/command-logs.md) | Every command run, its output and the files it touched | `ram`, `disk` | `store.logs` |
| [Jobs](https://docs.mirage.strukto.ai/home/infrastructure/jobs.md) | Background jobs, their output and the processes the workspace runs | `ram`, `redis` | `store.execution` |

To see command logs from many machines in one place, send them to an
OpenTelemetry backend as [traces](https://docs.mirage.strukto.ai/home/infrastructure/command-logs.md#trace-setup).

## Caches

Copies of files and listings Mirage read from your mounts, kept to make the
next read faster. If a cache is lost, the next read is just slower. The
`cache` and `index` keys sit next to `store`, not inside it.

| Cache | Holds | Backends | Key |
| - | - | - | - |
| [File Cache](https://docs.mirage.strukto.ai/home/infrastructure/file-cache.md) | File content Mirage has read | `ram`, `redis` | `cache` |
| [Index](https://docs.mirage.strukto.ai/home/infrastructure/file-index.md) | Directory listings and metadata | `ram`, `redis` | `index` |

A mount can also set its own `index`, which replaces the workspace's for
that mount.

## What each backend gives you

Every store keeps its state by `workspace_id`. Give the workspace a fixed id
whenever its state should be found again, after a restart or by another
process.

| `type` | Survives a restart | Shared with |
| - | - | - |
| `ram` | No | Workspaces in the same process given the same store object |
| `disk` | Yes | Processes on the same machine. Jobs stay in each process's memory. |
| `redis` | Yes | Every process on that Redis, on any machine. Command logs stay on each machine's disk. |
| `s3` | Yes | Every process that reaches the bucket. Sessions only. |

In Python and TypeScript, `SqlWorkspaceStateStore` keeps the namespace,
sessions and jobs in SQLite or Postgres, so every process on the database
shares them. Command logs stay in each process's memory. YAML has no `sql`
type.

## One store or several

`store.type` sets one backend for all four stores. This config keeps the
workspace state on Redis. Redis holds no command logs, so they go to disk
under `root`, `~/.mirage/state` by default.

```yaml workspace.yaml theme={null}
workspace_id: agent
store:
  type: redis
  url: redis://redis.internal:6379/0
```

To move one store to a backend of its own, add its key under `store`:
`namespace`, `sessions`, `logs` for command logs or `execution` for jobs. Here the command logs go to a disk path you choose:

> [tab] YAML
>
> ```yaml workspace.yaml theme={null}
> workspace_id: agent
> store:
>   type: redis
>   url: redis://redis.internal:6379/0
>   logs:
>     type: disk
>     root: /var/lib/mirage
> mounts:
>   /data:
>     vfs: ram
> ```

> [tab] Python
>
> ```python theme={null}
> from mirage import RAMVFS, MountMode, Workspace
> from mirage.workspace.store import DiskWorkspaceStateStore, RedisWorkspaceStateStore
>
> store = RedisWorkspaceStateStore(
>     url="redis://redis.internal:6379/0",
>     logs=DiskWorkspaceStateStore(root="/var/lib/mirage"),
> )
> ws = Workspace(
>     {"/data": RAMVFS()},
>     mode=MountMode.WRITE,
>     workspace_id="agent",
>     store=store,
>     owns_store=True,
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import {
>   DiskWorkspaceStateStore,
>   MountMode,
>   RAMVFS,
>   RedisWorkspaceStateStore,
>   Workspace,
> } from '@struktoai/mirage-node'
>
> const store = new RedisWorkspaceStateStore({
>   url: 'redis://redis.internal:6379/0',
>   logs: new DiskWorkspaceStateStore({ root: '/var/lib/mirage' }),
> })
> const ws = new Workspace(
>   { '/data': new RAMVFS() },
>   { mode: MountMode.WRITE, workspaceId: 'agent', store, ownsStore: true },
> )
> ```

Closing the workspace closes a store it owns, the stores under its keys
included.

[stores.py](https://github.com/strukto-ai/mirage/blob/main/examples/python/configuration/stores.py)
and
[stores.ts](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/configuration/stores.ts)
place one store at a time on disk, build the workspace again and print what
came back.

## Where you set it

One config describes a workspace, the same [YAML](https://docs.mirage.strukto.ai/home/configuration/workspace.md) on
every surface. Python and TypeScript also take each store as a constructor
argument, as each store's page shows.

> [tab] CLI
>
> ```bash theme={null}
> mirage workspace create workspace.yaml --id agent
> ```

> [tab] HTTP
>
> ```bash theme={null}
> curl http://127.0.0.1:8765/v1/workspaces \
>   -H "Authorization: Bearer $MIRAGE_AUTH_TOKEN" \
>   -H 'Content-Type: application/json' \
>   -d '{"id":"agent","config":{"store":{"type":"redis","url":"redis://redis.internal:6379/0"},"mounts":{"/data":{"vfs":"ram"}}}}'
> ```

> [tab] Python
>
> ```python theme={null}
> import asyncio
>
> from mirage import Workspace
> from mirage.config import build_mcp_clis, load_config, resolve_secrets
>
>
> async def main():
>     # resolve_secrets fetches credential pointers, such as `from: env`.
>     # build_mcp_clis connects any `cli: mcp` entries.
>     config = await resolve_secrets(load_config("workspace.yaml"))
>     ws = Workspace(**config.to_workspace_kwargs(mcp_clis=await build_mcp_clis(config)))
>
>
> asyncio.run(main())
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Workspace, configToWorkspaceArgs, loadWorkspaceConfigFile } from '@struktoai/mirage-node'
>
> const { mounts, options } = await configToWorkspaceArgs(loadWorkspaceConfigFile('workspace.yaml'))
> const ws = new Workspace(mounts, options)
> ```


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