Skip to main content
A Mirage virtual terminal is a workspace: one terminal over your mounted backends, with sessions inside it and profiles and policies that decide what each agent may see and run. Its core is the Mirage library in Python and TypeScript, running in your app. Every other way in reaches that same core.
Every client reaches one core, the Workspace. An app calls it directly. The mirage CLI, MCP clients and RPC clients reach the server's HTTP routes. SSH clients reach its SSH server. Both servers call the Workspace.Every client reaches one core, the Workspace. An app calls it directly. The mirage CLI, MCP clients and RPC clients reach the server's HTTP routes. SSH clients reach its SSH server. Both servers call the Workspace.
Every way in but in-app goes through the Mirage server, a FastAPI app in Python and a Fastify app in TypeScript that speak the same protocol. It serves HTTP, and SSH too when ssh_port is set; MCP and RPC are HTTP routes, and the CLI is an HTTP client that starts the server on your machine when it needs one.

​
What each one exposes

Each way in exposes what its own protocol defines. A dash means the protocol has no such operation.

​
Sessions

Every call acts as one session, with its own working directory and environment, under the profile it was created with. HTTP picks the session with session_id, MCP and RPC with ?session_id= or -s, and the CLI with -s; each SSH login gets a fresh session under its key’s profile. Without one, a call runs in the workspace’s default session, under the default profile: the one the config’s profile: names, else the profile called default, else none.

​
Cancel

Each way in stops a running line as its clients do: Ctrl-C in the CLI and SSH, notifications/cancelled in MCP, $/cancelRequest in RPC, and a dropped request or DELETE /v1/jobs/{id} over HTTP. Through the server every line runs as a job, listed by GET /v1/jobs, and a cancelled one ends canceled.

​
Auth

The server asks every HTTP request but GET /v1/health for a bearer token; in the default local mode the CLI reads it from ~/.mirage/auth_token for you. See Auth. SSH logins use public keys instead.