ssh_port. The TypeScript server speaks the same protocol. The API Reference lists every route.
Install
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.
build_app. The Default column names the environment variable or ~/.mirage/config.toml key each falls back to.
Workers
By default the daemon is one process, and one thread holds every workspace. Withworkers 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/healthand/v1/daemon/readyitself, merges the workers’GET /v1/workspaceslists, and holdsmax_workspacesacross 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 interpreter tuning, for an app run with build_app
The interpreter tuning, for an app run with build_app
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_keysoptions. asyncssh enforces OpenSSH’s options (from=,command=, …), andcommand=forces the line that runs.mirage-profilebinds the key to a profile andmirage-accountopens 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.Code map
Code map