Skip to main content
Run the Python or TypeScript server to access your Mirage workspaces over HTTP. This guide covers setup, authentication, limits, and server operations. Use the API reference for endpoint fields and responses.

Launch a server

Set a token in the server’s environment before starting the process:
In an activated Python environment, install the server:
Save this as server.py:
server.py
Start it in the terminal where you set the token, and leave it running:
The server accepts only the host names in MIRAGE_ALLOWED_HOSTS: 127.0.0.1, localhost and ::1 by default. Add the name your clients use. It also refuses a browser page served from any other origin, a page on another port of localhost included, even when the list is *. Other options are on the Python and TypeScript server pages.

Verify the connection

From another terminal, check that the server is running:
The response includes "status": "ok". Health checks do not require a token. Use http://127.0.0.1:8765 as the base URL for requests to this server and send Authorization: Bearer <your-token> on authenticated requests. For workspace creation and command execution, see Create a workspace and Run shell command. Replace the example API host with your server’s base URL.

Configure authentication

MIRAGE_AUTH_MODE picks what the server accepts on its HTTP, MCP and RPC routes.

JWT

Point the server at your issuer’s keys:
Every token needs exp and sub. A token with aud must name an entry in MIRAGE_JWT_AUDIENCE; with none set, every such token is refused. Set one of the JWKS URL or a fixed key, not both. In the [daemon] section of config.toml, each setting is its name without MIRAGE_, in lower case, such as jwt_alg.
A token with aud must name an entry in MIRAGE_JWT_AUDIENCE. A token without aud needs an azp in MIRAGE_JWT_AUTHORIZED_PARTIES when that is set, and is refused when only an audience is set. So one server can accept an app’s session tokens (azp) and an OAuth client’s access tokens (aud), as Clerk issues them:
To let mirage login sign in to this server, see Log in.

Accounts

In jwt mode, a token’s sub is its account, and an account reaches only the workspaces it created. Another account’s workspace, session or ask returns HTTP 404 Not Found, matching a missing resource. An SSH key joins an account with its mirage-account option.
  • GET /v1/workspaces lists only the caller’s.
  • A stored workspace reopens after a restart only for its owner. One stored before the server used jwt mode has no owner, and no account can create its id.
  • Snapshot keys live under accounts/<account>/ in the snapshot store.
  • POST /v1/daemon/shutdown returns HTTP 403 Forbidden.
Accounts keep workspaces apart, not the host: a workspace config can still mount a host directory or run a host machine, unless a server policy refuses it. In local and token mode, any accepted token can use every route and every workspace, including POST /v1/daemon/shutdown.

Rate limits

By default, the server allows 1000 requests per minute per client IP, counted before authentication so rejected tokens consume the same budget. Configured limits replace this default; include an ip limit to keep unauthenticated requests bounded. An explicit empty list in code or rate_limits = "" in config.toml disables rate limiting. Each limit allows a number of requests per second, minute, hour or day for each value of its key, and answers 429 with Retry-After past it until the window that value’s first request opened ends. Set them in config.toml:
A request with no value for a key (no account, no workspace in its path, no such header) is not counted by that limit. /v1/health, /v1/daemon/ready and the OAuth protected-resource metadata are never counted. WebSocket handshakes consume the same budget as HTTP requests; messages on an established connection do not. In code, a key may also be a function of the request that returns the value to count by, or nothing to skip the limit:

Server policies

Apply server policies to every workspace the server builds. A workspace’s own configuration cannot remove these policies. See Server policies for the policy methods, and Policy programs for file-based rules. Set the policy file in the daemon’s configuration:
~/.mirage/config.toml
When you build the server in code, pass its policies through build_app or buildApp. A workspace’s network configuration controls where its connections may go.

Monitor the server

Health and readiness

Use /v1/health for a load balancer’s liveness check. Use /v1/daemon/ready for readiness: it returns 200 while the server accepts new workspaces and 503 when it is full or shutting down. Readiness and shutdown control the server process.

Metrics

The server records workspace, session, command, and refusal metrics under the OpenTelemetry meter mirage.server. Configure an SDK and exporter to collect them.
The server records its metrics through OpenTelemetry, under the meter mirage.server. Nothing is sent until the process sets up an OpenTelemetry SDK, and the exporter it picks decides where they go: OTLP to Datadog, New Relic, Honeycomb, Grafana Cloud, CloudWatch or Google Cloud, a Prometheus page, or the console. They are server-wide and name no workspace or account.In Python, run the app under opentelemetry-instrument, which also records each HTTP request:
In TypeScript, register a meter provider before buildApp:

Shut down

Request a graceful shutdown of a server you operate:
The daemon shuts down through its exit hook. A server created in code needs an on_idle_exit callback in Python or onIdleExit in TypeScript; without a hook, it keeps serving. See the Python or TypeScript server configuration.

Lines, jobs and processes

Inspect active and recently completed work with List commands, List jobs, and List processes. A shell result’s line_id identifies its line record. Servers using the same workspace store share these records, and snapshots keep ended records. See those endpoint pages for retention, filters, and response fields.

Streaming and stdin

See Streaming and stdin in the API reference for output records, cancellation, and multipart input examples.

Next steps

API reference

Look up request fields, response schemas, and endpoint examples.