Lightweight Terminal

What an agent can run

Installation

pip install 'mirage-ai[monty]' fastapi uvicorn

npm install @struktoai/mirage-node @pydantic/monty express

Server

from contextlib import asynccontextmanager

from fastapi import FastAPI
from pydantic import BaseModel

from mirage import RAMVFS, MountMode, Workspace
from mirage.runtime.python.monty import MontyRuntime

ws = Workspace(
    {"/work": (RAMVFS(), MountMode.EXEC)},
    machines=[MontyRuntime(captures=["python", "python3"])],
)


@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    await ws.close()


app = FastAPI(lifespan=lifespan)


class Run(BaseModel):
    command: str


@app.post("/sessions/{session_id}")
async def create(session_id: str) -> None:
    ws.create_session(session_id)


@app.post("/sessions/{session_id}/run")
async def run(session_id: str, body: Run) -> dict:
    r = await ws.shell(body.command, session_id=session_id)
    return {"stdout": await r.stdout_str(), "stderr": await r.stderr_str(), "exit_code": r.exit_code}

uvicorn app:app --port 3000

import express from 'express'
import { MontyRuntime, MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
  { '/work': new RAMVFS() },
  { mode: MountMode.EXEC, machines: [new MontyRuntime({ captures: ['python', 'python3'] })] },
)
const app = express()
app.use(express.json())

app.post('/sessions/:id', (req, res) => {
  ws.createSession(req.params.id)
  res.sendStatus(201)
})

app.post('/sessions/:id/run', async (req, res) => {
  const r = await ws.shell(req.body.command, { sessionId: req.params.id })
  res.json({ stdout: r.stdoutText, stderr: r.stderrText, exitCode: r.exitCode })
})

app.listen(3000, '127.0.0.1')

node app.mjs

Usage

curl -X POST localhost:3000/sessions/a
curl -X POST localhost:3000/sessions/a/run -H 'content-type: application/json' \
  -d '{"command": "cd /work && echo \"print(sum(range(10)))\" > s.py && python3 s.py"}'

run() {
  jq -Rs '{command: .}' |
    curl -s localhost:3000/sessions/a/run -H 'content-type: application/json' -d @- |
    jq -j '.stdout, .stderr'
}

run <<'SH'
pwd
python3 s.py
SH

/work
45

Terminals per server

• Idle terminals are nearly free. An idle terminal has no process or thread of its own, only a record of about 20 KB on Python and on TypeScript. One server holds thousands of them, so an agent can keep its terminal between turns.
• Terminals waiting on a service run at once. A command that waits for a reply uses no CPU while it waits, and the server runs other terminals’ commands in the meantime. See Async.
• Terminals working on data share the CPU. Commands such as sort and grep take turns on it, so each takes longer as more run together. A command that needs a core to itself belongs on a machine: see Runtime Routing.

Async

import asyncio

for sid in ["a", "b", "c"]:
    ws.create_session(sid)
await asyncio.gather(*(ws.shell("sleep 1", session_id=sid) for sid in ["a", "b", "c"]))

for (const sid of ['a', 'b', 'c']) ws.createSession(sid)
await Promise.all(['a', 'b', 'c'].map((sid) => ws.shell('sleep 1', { sessionId: sid })))

Sharing and security

• By default, terminals share the workspace’s mounts, so a file one writes under /work is visible to the others.
• A session profile and a policy decide which commands a terminal may run and which files it sees, so each agent can have a folder the others cannot see. Policy & Security walks through one. To keep everything apart, give an agent its own workspace.

Use cases