Launch a server
Set a token in the server’s environment before starting the process:- Python
- TypeScript
In an activated Python environment, install the server:Save this as Start it in the terminal where you set the token, and leave it running:
server.py:server.py
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:"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: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.
Accept both app session tokens and OAuth access tokens
Accept both app session tokens and OAuth access tokens
A token with To let
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:mirage login sign in to this server, see
Log in.Accounts
Injwt 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.
What else an account changes
What else an account changes
GET /v1/workspaceslists only the caller’s.- A stored workspace reopens after a restart only for its owner. One stored
before the server used
jwtmode has no owner, and no account can create its id. - Snapshot keys live under
accounts/<account>/in the snapshot store. POST /v1/daemon/shutdownreturns HTTP 403 Forbidden.
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 anip 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
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 metermirage.server. Configure an SDK and exporter to collect them.
Configure metric collection
Configure metric collection
The server records its metrics through OpenTelemetry,
under the meter In TypeScript, register a meter provider before
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:buildApp:Shut down
Request a graceful shutdown of a server you operate: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’sline_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.