Skip to main content
The Mirage server is a FastAPI app that holds workspaces. It serves them over HTTP, MCP, RPC and SSH. SSH runs through the HTTP port, and on its own port too when you set ssh_port. The TypeScript server speaks the same protocol. The API Reference lists every route.

Install

The ssh extra adds asyncssh, needed only for the SSH server.

Run it

build_app returns a FastAPI app. Run it with any ASGI server, such as uvicorn; ASGI middleware wraps it as it wraps any FastAPI app.
Arguments of build_app. The Default column names the environment variable or ~/.mirage/config.toml key each falls back to.
A workspace that sets more gets the ceiling; see Limits.

Workers

By default the daemon is one process, and one thread holds every workspace. With workers above 1 (MIRAGE_WORKERS, or the workers key), the daemon starts that many workers. Each worker is a full server on its own Unix socket. The daemon routes each request to the worker that holds the workspace. New workspaces go to a random worker. The workspaces on one worker share its event loop, and the OS spreads the workers over the CPUs. worker_type (MIRAGE_WORKER_TYPE, or the worker_type key) is thread or process. The default is process, or thread on a free-threaded interpreter (3.14t).
  • The daemon answers /v1/health and /v1/daemon/ready itself, merges the workers’ GET /v1/workspaces lists, and holds max_workspaces across the workers.
  • A worker that exits stays gone, and so do its workspaces.
  • Each worker counts its own rate limits, so a limit keyed on the address or the account allows that many requests per worker.
  • The SSH port does not work with workers above 1.

Started by the CLI

The CLI runs the same app as a daemon, mirage.server.daemon:app, on 127.0.0.1:8765 in local auth mode, logging to ~/.mirage/daemon.log. That entry adds the daemon behaviors: it writes $MIRAGE_HOME/daemon.pid for mirage daemon stop and kill, exits 30 seconds (MIRAGE_IDLE_GRACE_SECONDS) after its last running workspace stops or is deleted, and tunes the interpreter as it starts. Its other settings are on the Server page.
The CLI’s daemon tunes the garbage collector and sets the GIL switch interval to 1 ms, so a busy line makes other sessions wait 2 ms turns instead of 10 ms. An app run with build_app does not get this. Add the same lines at startup:

On its own event loop

WorkspaceRunner pins a workspace to a thread and event loop of its own. A line waiting on I/O then never stalls the app’s loop, and workspaces in one process never wait on each other’s I/O. CPU-bound work still shares the GIL with every other thread in the process. The Mirage server hosts every workspace this way.
call runs a coroutine on the workspace’s loop and is safe from any other loop; cancelling the caller cancels the coroutine. stop closes the workspace (delete=True also deletes its state), then stops the loop and refuses new calls.

MCP and RPC on their own

The MCP and RPC servers are classes that run over any transport, without the Mirage server. Both serve one session of a workspace.
MirageMcpServer(workspace, stale_write_protection=True, name="mirage", version=..., session_id=None, operations=None, all_calls=False). Its server is the MCP SDK’s low-level Server. all_calls=True adds the VFS calls and explain.
MirageRpcServer(workspace, session_id=None, operations=None, name="mirage", version=...). handle(message) answers one message, and None for a notification. serve(read_line, write_line) answers newline-delimited messages until read_line returns "".

What is particular to this server

The protocol is the same on both servers. These are the differences in how this one serves it:
  • Legacy scp -O. The SCP protocol is served, as well as SFTP.
  • authorized_keys options. asyncssh enforces OpenSSH’s options (from=, command=, …), and command= forces the line that runs. mirage-profile binds the key to a profile and mirage-account opens only that account’s workspaces.
  • Terminal line limit. 1024 characters.
  • A thread per workspace. Each workspace runs on its own thread and event loop through a WorkspaceRunner, so a busy workspace does not hold up another or the HTTP server.

Endpoints

The API Reference lists every route with its request and response, Authentication the token and JWT modes, and Streaming how shell output and stdin stream.