@struktoai/mirage-server 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 Python server speaks the same protocol. The API Reference lists every route.
Install
Run it
buildApp returns the Fastify instance: register hooks and plugins on it before listen, as on any Fastify app.
buildApp. 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 thread.
- 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
@struktoai/mirage-cli runs the same app as a daemon, mirage-daemon, on 127.0.0.1:8765 in local auth mode, logging to ~/.mirage/daemon.log. That entry adds the two daemon behaviors: it writes $MIRAGE_HOME/daemon.pid for mirage daemon stop and kill, and exits 30 seconds (MIRAGE_IDLE_GRACE_SECONDS) after its last running workspace stops or is deleted. It listens on MIRAGE_DAEMON_PORT, the port setting, or 8765. Its settings are on the CLI page.
MCP and RPC on their own
The MCP and RPC servers can run over a transport of your own, without the Mirage server. Both serve one session of a workspace, wherews is a Workspace.
createMirageMcpServer(ws, { sessionId?, operations?, name?, version?, staleWriteProtection?, allCalls? }) returns the MCP SDK’s McpServer. allCalls: true adds the VFS calls and explain.
new MirageRpcServer(ws, { sessionId?, operations?, name?, version? }). handle(message) processes a message and returns its response (null for a notification). serve(lines, write) processes each line of an async iterable until it ends.
What is particular to this server
The protocol is the same on both servers. These are the differences in how this one serves it:- No legacy
scp -O. Modernscpuses SFTP, which is served; the old SCP protocol is not. authorized_keysoptions.mirage-profileandmirage-accountare read: the first binds the key to a profile, the second opens only that account’s workspaces. A key line carrying any other option (from=,command=, …) is skipped with a warning, rather than accepted as if it had none.- Terminal line limit. 1024 bytes.
- One event loop. Every workspace shares Node’s loop. Shell evaluation yields between steps, but a long synchronous step in a JavaScript callback or a CPU-heavy runtime holds every workspace until it returns, so run such work in a worker.
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