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

# Infra-agnostic Terminal

> A virtual terminal not tied to any fixed infrastructure, keeping its files, sessions and command logs on whichever backends are already in place.

Unified Virtual Filesystem

![mirage](https://docs.mirage.strukto.ai/logo/light.svg)
![mirage](https://docs.mirage.strukto.ai/logo/dark.svg)

\$

A terminal needs somewhere to keep its files, its state and its records. In
Mirage, each of those is a separate backend set in the workspace config, and
the agent sees the same terminal whichever one is behind it. This example builds a
support agent's terminal from services a team might already run.

| Part | Backend |
| - | - |
| Data the agent reads | ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/postgres-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=aca36d421c1424970f4f74eb0a3831b4)Postgres, tables as files at `/db` |
| Notes the agent writes | ![](https://mintcdn.com/struktoai/wbn_tJeahvJMuT6I/images/sqlite-logo.svg?fit=max\&auto=format\&n=wbn_tJeahvJMuT6I\&q=85\&s=8cf1e3eb2c2d13057741075c271b8b1c)SQLite, through the `sql` virtual filesystem at `/notes` |
| Sessions and background jobs | ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/redis-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=1f81a02282061ad43e3aa8f86b01434a)Redis |
| Every command it runs | ![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/langfuse-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=668cebbc3269342e4118192c40588be3)Langfuse, as OpenTelemetry traces |

## Setup

The workspace mounts Postgres read-only at `/db` and a SQLite database at
`/notes`, and keeps its sessions and jobs in Redis. The agent's process sends
a trace for each line to Langfuse.

> [accordion] workspace.yaml
>
> ```yaml workspace.yaml theme={null}
> workspace_id: support-agent
> mode: write
>
> mounts:
>   /db:
>     vfs: postgres
>     mode: read
>     config:
>       dsn: {from: env, key: DATABASE_URL}
>   /notes:
>     vfs: sql
>     config:
>       path: ./notes.db
>
> store:
>   type: redis
>   url: ${REDIS_URL}
> ```

> [accordion] Send traces to Langfuse
>
> Mirage sends a trace for each line once the process sets up an
> OpenTelemetry SDK. Langfuse accepts traces over OTLP, with the project's
> public and secret keys as basic auth:
>
> > [tab] Python
> >
> > ```python theme={null}
> > import base64
> > import os
> >
> > from opentelemetry import trace
> > from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
> > from opentelemetry.sdk.trace import TracerProvider
> > from opentelemetry.sdk.trace.export import BatchSpanProcessor
> >
> > auth = base64.b64encode(f"{os.environ['LANGFUSE_PUBLIC_KEY']}:{os.environ['LANGFUSE_SECRET_KEY']}".encode()).decode()
> > provider = TracerProvider()
> > provider.add_span_processor(
> >     BatchSpanProcessor(
> >         OTLPSpanExporter(
> >             endpoint=f"{os.environ['LANGFUSE_HOST']}/api/public/otel/v1/traces",
> >             headers={"Authorization": f"Basic {auth}"},
> >         )
> >     )
> > )
> > trace.set_tracer_provider(provider)
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { trace } from '@opentelemetry/api'
> > import { BatchSpanProcessor, TracerProvider } from '@opentelemetry/sdk-trace'
> > import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
> >
> > const auth = Buffer.from(`${process.env.LANGFUSE_PUBLIC_KEY}:${process.env.LANGFUSE_SECRET_KEY}`).toString('base64')
> > const provider = new TracerProvider({
> >   spanProcessors: [
> >     new BatchSpanProcessor({
> >       exporter: new OTLPTraceExporter({
> >         url: `${process.env.LANGFUSE_HOST}/api/public/otel/v1/traces`,
> >         headers: { Authorization: `Basic ${auth}` },
> >       }),
> >     }),
> >   ],
> > })
> > trace.setGlobalTracerProvider(provider)
> > ```

> [accordion] Load the workspace
>
> The agent runs its first lines in one process, then continues in a new
> one:
>
> > [tab] Python
> >
> > ```python theme={null}
> > import asyncio
> > import sys
> >
> > from mirage import Workspace
> > from mirage.config import load_config, resolve_secrets
> >
> > FIRST = [
> >     "ls /db/public/tables",
> >     "jq -r 'select(.status == \"refunded\") | .customer_id' /db/public/tables/orders/rows.jsonl | sort -u > /notes/refunds.txt",
> >     "cd /notes && export TICKET=4821",
> > ]
> > SECOND = ["pwd", "echo $TICKET", "cat refunds.txt"]
> >
> >
> > async def main() -> None:
> >     config = await resolve_secrets(load_config("workspace.yaml"))
> >     ws = Workspace(**config.to_workspace_kwargs())
> >     agent = await ws.session("agent")
> >     for line in FIRST if sys.argv[1] == "first" else SECOND:
> >         result = await agent.shell(line)
> >         print(await result.stdout_str(), end="")
> >     await ws.close()
> >
> >
> > asyncio.run(main())
> > provider.shutdown()
> > ```
> >
> > ```bash theme={null}
> > python agent.py first
> > python agent.py second
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Workspace, configToWorkspaceArgs, loadWorkspaceConfigFile } from '@struktoai/mirage-node'
> >
> > const first = [
> >   'ls /db/public/tables',
> >   `jq -r 'select(.status == "refunded") | .customer_id' /db/public/tables/orders/rows.jsonl | sort -u > /notes/refunds.txt`,
> >   'cd /notes && export TICKET=4821',
> > ]
> > const second = ['pwd', 'echo $TICKET', 'cat refunds.txt']
> >
> > const { mounts, options } = await configToWorkspaceArgs(loadWorkspaceConfigFile('workspace.yaml'))
> > const ws = new Workspace(mounts, options)
> > const agent = await ws.session('agent')
> > for (const line of process.argv[2] === 'first' ? first : second) {
> >   const result = await agent.shell(line)
> >   process.stdout.write(result.stdoutText)
> > }
> > await ws.close()
> > await provider.shutdown()
> > ```
> >
> > ```bash theme={null}
> > node agent.ts first
> > node agent.ts second
> > ```

## Files from Postgres and SQLite

[Postgres](https://docs.mirage.strukto.ai/python/vfs/postgres.md) shows each table as a folder with its
`schema.json` and its rows as `rows.jsonl`. [SQL](https://docs.mirage.strukto.ai/home/setup/sql.md) keeps the
files written under `/notes` in a SQLite database. The first process reads the
refunded orders from Postgres and writes their customers to SQLite:

```bash theme={null}
ls /db/public/tables
# customers
# orders
jq -r 'select(.status == "refunded") | .customer_id' /db/public/tables/orders/rows.jsonl | sort -u > /notes/refunds.txt
cd /notes && export TICKET=4821
```

## Sessions in Redis

With `store.type: redis`, the [sessions](https://docs.mirage.strukto.ai/home/infrastructure/sessions.md) and
[jobs](https://docs.mirage.strukto.ai/home/infrastructure/jobs.md) live in Redis under `support-agent`, so any
process that builds the same workspace picks them up. The second process
starts where the first one stopped, with the same working directory and
variables:

```bash theme={null}
pwd
# /notes
echo $TICKET
# 4821
cat refunds.txt
# 1
# 3
```

## Command Logs

Mirage records every line the agent runs as a
[command log](https://docs.mirage.strukto.ai/home/infrastructure/command-logs.md). Redis holds no command logs,
so `history` reads them from disk under `~/.mirage/state`, on the machine that
ran the line.

Langfuse gets the same lines as traces, the record to read across machines.
Each line is a `shell` trace, with its command, exit code, output and session.
See [Spans](https://docs.mirage.strukto.ai/home/infrastructure/command-logs.md#spans) for every attribute.

## Swap a Backend

Each part changes on its own, in the config, with nothing changed in the
agent:

* Virtualize S3, Google Drive or another [virtual filesystem](https://docs.mirage.strukto.ai/home/setup/vfs.md) at
  `/notes` instead of SQLite.
* Set `store.type` to `disk` to keep the state on one machine, or move one
  store elsewhere, such as `store.sessions`. See
  [Infrastructure](https://docs.mirage.strukto.ai/home/infrastructure/overview.md).
* Point the exporter at another OpenTelemetry backend, such as Jaeger or
  Honeycomb.


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