Mirage: un sistema de archivos virtual para agentes

Pega este texto a tu agente (Claude Code, Codex, OpenCode, Hermes o el que uses) y dile «ayúdame a montarlo». Son los pasos para ponerlo en marcha; el porqué de cada pieza está en la guía completa.

• Dificultad: avanzado
• Proyecto: https://github.com/strukto-ai/mirage (licencia Apache-2.0)
• Guía completa: https://lab.wisd.ai/hub/mirage-vfs

Para el agente: cómo acompañar al usuario

1. Pregunta primero para qué lo quiere. Si su objetivo no necesita algún paso, sáltalo.
2. Antes de instalar, comprueba lo que ya tiene (versiones, claves, sistema operativo).
3. Avanza un paso cada vez: explica en una frase qué vas a hacer y deja que el usuario lo ejecute o lo apruebe.
4. Tras cada paso, comprueba que funcionó antes de seguir. Si falla, para y explica el error.
5. No inventes comandos ni opciones: si la documentación del proyecto contradice estos pasos, manda la documentación.
6. Al terminar, haz una prueba real con el objetivo del usuario y dile dónde profundizar.

Pasos de configuración

Paso 1: instala la biblioteca

Comprueba que tu proyecto administrado con uv usa Python ≥3.12. Desde su raíz, usa el comando del README:

uv add mirage-ai

Para TypeScript, el mismo README documenta npm install @struktoai/mirage-node.

Paso 2: prepara el primer Workspace

El README indica Python ≥3.11, pero el manifiesto del paquete actual exige ≥3.12; esta ruta sigue el manifiesto. Guarda el bloque Create a Workspace del inicio rápido oficial, reproducido aquí, en prueba.py:

import asyncio
from mirage import MountMode, Workspace
from mirage.vfs.ram import RAMVFS

async def main() -> None:
    ws = Workspace({"/data": RAMVFS()}, mode=MountMode.WRITE)
    await ws.shell('echo "hello mirage" | tee /data/hello.txt')
    result = await ws.shell("cat /data/hello.txt")
    print(await result.stdout_str())
    await ws.close()

asyncio.run(main())

Desde la raíz del proyecto:

uv run python prueba.py

Debe imprimir hello mirage; no requiere credenciales ni S3. Para comprobar también las restricciones prometidas, descarga el ejemplo oficial de permisos como permissions.py en esa raíz y ejecútalo:

uv run python permissions.py

La tabla debe mostrar lectura de service.py para oncall, ausencia de su .env oculto y denegación al borrar service.py por el montaje de solo lectura. Para auditor, /vault debe aparecer ausente. Comprueba las negativas además de la lectura válida.

Paso 3: añade una fuente

Solo después de comprobar el montaje en RAM, instala el extra con uv add "mirage-ai[s3]" y sigue el ejemplo de S3VFS del README. Sustituye el bucket de ejemplo por uno de prueba y prepara sus permisos fuera de la conversación. Revisa MountMode y los perfiles antes de habilitar escritura.

Comprobación

Ejecuta una lectura sobre un archivo de prueba y compara el contenido devuelto con el original. Comprueba también que una ruta ocultada o una escritura denegada reciben el tratamiento configurado. No des por válida la política solo porque una lectura funciona.

Si algo falla

Distingue errores de shell virtual, montaje y autenticación del servicio. Revisa el inicio rápido correspondiente a Python o TypeScript: sus paquetes y adaptadores son distintos. Retira los conectores externos y reproduce primero el problema en RAM.