> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Access

> How agents and people reach a Mirage virtual terminal.

A Mirage virtual terminal is a workspace: one terminal over your mounted backends, with sessions inside it and [profiles](/home/permissions) and [policies](/home/policy/overview) that decide what each agent may see and run. Its core is the Mirage library in Python and TypeScript, running in your app. Every other way in reaches that same core.

<div className="my-6">
  <img noZoom src="https://mintcdn.com/struktoai/P2GwmHfVdrabAh4w/images/access-light.svg?fit=max&auto=format&n=P2GwmHfVdrabAh4w&q=85&s=ea2fef1ebc98119a48a7fb1beb0a2456" alt="Every client reaches one core, the Workspace. An app calls it directly. The mirage CLI, MCP clients and RPC clients reach the server's HTTP routes. SSH clients reach its SSH server. Both servers call the Workspace." className="block dark:hidden w-full" width="1340" height="650" data-path="images/access-light.svg" />

  <img noZoom src="https://mintcdn.com/struktoai/P2GwmHfVdrabAh4w/images/access-dark.svg?fit=max&auto=format&n=P2GwmHfVdrabAh4w&q=85&s=7170acaf4dd92d3dc88f582bf429c05d" alt="Every client reaches one core, the Workspace. An app calls it directly. The mirage CLI, MCP clients and RPC clients reach the server's HTTP routes. SSH clients reach its SSH server. Both servers call the Workspace." className="hidden dark:block w-full" width="1340" height="650" data-path="images/access-dark.svg" />
</div>

| Way in | For | Reach it with |
| - | - | - |
| In-app | an agent in your own process | `Workspace` and `Session`, in [Python](/python/access/in-app) or [TypeScript](/typescript/access/in-app) |
| [HTTP](/home/access/http) | programs and services | `/v1/...` routes |
| [MCP](/home/access/mcp) | agent harnesses such as Claude Code, Cursor and Codex | `/v1/workspaces/{id}/mcp`, or `mirage mcp` on stdio |
| [RPC](/home/access/rpc) | programs that run lines and move bytes | `/v1/workspaces/{id}/rpc`, or `mirage rpc` on stdio |
| [CLI](/home/access/cli) | people and scripts | `mirage <verb>` |
| [SSH](/home/access/ssh) | people and tools that speak SSH | `ssh`, `sftp`, `scp`, on the SSH port or through `mirage ssh-proxy` |
| [FUSE](/home/access/fuse) | any program that works on files | a folder: `backend: fuse` on the server's machine, `sshfs` on yours |

Every way in but in-app goes through the Mirage server, a FastAPI app in [Python](/python/access/server) and a Fastify app in [TypeScript](/typescript/access/server) that speak the same protocol. It serves HTTP, and SSH on its own port when `ssh_port` is set or over HTTP through `mirage ssh-proxy`; MCP and RPC are HTTP routes, a FUSE folder is mounted by the server itself or by `sshfs` over its SSH, and the CLI is an HTTP client that starts the server on your machine when it needs one.

## What each one exposes

Each way in exposes what its own protocol defines. A dash means the protocol has no such operation.

| | In-app | HTTP | MCP | RPC | CLI | SSH |
| - | - | - | - | - | - | - |
| Create, list, delete workspaces | ✓ | ✓ | – | – | ✓ | – |
| Create, list, delete sessions | ✓ | ✓ | – | – | ✓ | – |
| Run a line | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Send stdin to a line | ✓ | ✓ | – | ✓ | ✓ | ✓ |
| Cancel a running line | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Cancel or kill all of a session's or workspace's work | ✓ | ✓ | – | – | ✓ | – |
| VFS.md, SKILL.md and session profiles | ✓ | ✓ | – | – | ✓ | – |
| The seven agent tools | ✓ | ✓ | ✓ | ✓ | ✓ | – |
| File operations on bytes | ✓ | ✓ | ✓ | ✓ | ✓ | `sftp`, `scp`, `sshfs` |
| Explain a line or a VFS call | ✓ | ✓ | ✓ | ✓ | ✓ | – |
| Snapshots | ✓ | ✓ | – | – | ✓ | – |
| Asks | ✓ | ✓ | – | – | ✓ | – |
| Jobs | – | ✓ | – | – | ✓ | – |

## Sessions

Every call acts as one session, with its own working directory and environment, under the [profile](/home/permissions) it was created with. HTTP, MCP and RPC pick the session with `?session_id=` (or `-s` on stdio), and the CLI with `-s`; each SSH login, an `sshfs` mount among them, gets a fresh session under its key's profile. Without one, a call runs in the workspace's default session, under the default profile: the one the config's `profile:` names, else the profile called `default`, else none. A FUSE folder the server mounts is the exception: it belongs to no session, so no profile applies.

## Cancel

Each way in stops a running line as its clients do: Ctrl-C in the CLI and SSH, `notifications/cancelled` in MCP, `$/cancelRequest` in RPC, and a dropped request or `DELETE /v1/jobs/{id}` over HTTP. Through the server every line runs as a job, listed by `GET /v1/jobs`, and a cancelled one ends `canceled`. To stop everything a session or a workspace is running, whichever way it came in, HTTP and the CLI cancel its lines and kill its background jobs (`mirage session cancel`, `mirage workspace kill`).

## Auth

The server asks every HTTP request but `GET /v1/health` for a bearer token; in the default local mode the CLI reads it from `~/.mirage/auth_token` for you. See [Auth](/home/access/http#auth). SSH logins on the SSH port use public keys instead; through `mirage ssh-proxy` they use the CLI's token. In `jwt` mode a token's `sub` is an [account](/home/access/http#accounts) that reaches only its own workspaces, and an SSH key names its account with `mirage-account`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.