Skip to main content
Agents are post-trained in a terminal. They run Bash and CLIs and read what comes back. What they need is that terminal interface, not a fixed machine behind it. Yet the usual answer is a sandbox, a container or microVM for each agent, which reserves CPU, memory and local disk, takes time to start and needs a service to manage it. In some agentic services, an agent mostly reads files, calls services and waits for answers, so it barely touches the CPU and disk it was given. It needs memory only while a command runs, a network connection and a terminal. An in-process terminal gives it exactly that inside the server you already have. Each terminal is a Mirage session with its own working directory, environment and history, and one server process holds many terminals on its event loop. One virtual filesystem virtualizes remote services as files. CLIs are virtual too, and an MCP server becomes a virtual CLI automatically. Together they give an agent a virtual terminal at a fraction of a sandbox’s infrastructure cost, and with fewer tokens than calling the same services as MCP tools (VFS-Bench 1.0). Everything an agent can reach is managed in one place. The Unix commands, CLIs, MCP servers, credentials and files available to each terminal are set on the server, and a policy refuses a command before it runs.

Installation

Simple Server

The server keeps an in-memory virtual filesystem at /workspace. Agents get a terminal from POST /sessions/{id} and run commands in it with POST /sessions/{id}/run.
app.py

Simple Usage

Create a terminal, then send it commands.
The first run writes a log and prints 2. The second starts in /workspace, where the cd left it, and prints ["ERROR disk full","ERROR timeout"]. Each response carries the command’s stdout, stderr and exit code.

Infrastructure Cost

A sandbox reserves memory for every agent, busy or idle. An in-process terminal is only a working directory, variables and a history in your server’s memory, so an idle agent costs almost nothing. Move the slider to compare. An in-process terminal is built for I/O-heavy work, the reading, calling and piping most agents spend their time on.
  • Idle. Between an agent’s turns, an in-process terminal is only a record of about 10 KB, so one server holds thousands.
  • I/O-heavy tasks, such as curl, gh pr list or reading files from a bucket. A command uses no CPU while it waits for a reply, so many terminals run at once with little slowdown.
Size the server as you would any web service, by how many terminals are active at the same moment, not by how many exist.

Many Terminals at Once

In Mirage, ws.shell is a coroutine in Python and a promise in TypeScript, and it never blocks the event loop. The handlers above are async, so while one terminal waits on a file read, a runtime or a slow command, the server keeps serving every other terminal, with no thread or process per terminal.
The three commands finish together in about a second; 20 sessions take the same. Within one session, commands run one after another in order, as in a real terminal, so three sleep 1 commands on session a take three seconds.

Separation

Workspaces are kept apart.
  • Files. A terminal sees only its own workspace’s files. Agents in different workspaces share nothing unless their virtual filesystems use the same storage, such as one S3 bucket.
  • Credentials. Each workspace’s virtual filesystems and CLIs carry their own credentials, so one agent’s S3 keys or GitHub token never reach another workspace. Even inside its own workspace, an agent uses them without seeing them, because they stay in the server’s memory, never in a file or variable the agent can read.
  • Within a workspace. Each terminal is a session, and its profile decides which files it sees and which commands and CLIs it may run, so agents in one workspace can each get only what they need.

Use cases

Each page adds a few lines to this server and shows what an agent does with the terminal.

Code Review

Review a pull request against a read-only clone in memory, and write a score, a diagram and line comments.

Cowork

Kick off a new customer’s onboarding from a won deal in Slack, with Drive, Docs, Sheets and Notion.

Agent Email

Answer a customer’s email with a report built from a Slack export, holding only their data, sent once a person approves.