CLI

mirage is a client of the server’s HTTP routes, with the same commands in Python and TypeScript. When its url is on this machine, it starts a server on first use; a remote url is never started.

Install

curl -fsSL https://strukto.ai/mirage/install.sh | sh

pip install mirage-ai

uv tool install mirage-ai

npm install -g @struktoai/mirage-cli

Quickstart

mirage workspace create workspace.yaml --id demo   # starts the server
mirage shell -w demo -c 'ls / | head'
mirage tools grep -w demo -i error /
mirage workspace delete demo

workspace.yaml is a workspace config.

Exit codes

Code	Meaning
`0`	Success.
`1`	A tool failed, a VFS call was refused or failed, or the server could not be reached.
`2`	A usage error, a bad config, or a refusal from the server.
`130`	The line was interrupted with Ctrl-C or canceled.
`N`	`shell`, `job wait` and `job get` exit with the line’s own status.

Run lines, VFS calls and tools

-w names the workspace and -s the session, the default one when absent. --explain prints what a line or a VFS call would do, running nothing; see Explain.

Command	Does
`mirage shell -w ID [-s SESSION] -c LINE [--cwd PATH] [--runtime NAME] [--bg] [--explain]`	Run a line. Piped stdin streams to it, Ctrl-C cancels it, and `--bg` returns a job id at once.
`mirage vfs CALL ARGS -w ID [-s SESSION] [--explain]`	One of the 24 VFS calls: its required arguments in order, the rest as `--name VALUE`, bytes from `--data` / `--value` or stdin. Calls are spelled with dashes: `mirage vfs is-dir`.
`mirage glob PATTERN -w ID [-s SESSION]`	Every path a pattern matches.
`mirage tools TOOL ARGS -w ID [-s SESSION]`	One of the agent tools: `shell`, `read`, `write`, `edit`, `ls`, `grep`, `glob`.

`mirage mcp`

mirage mcp [CONFIG] [-w ID] [-s SESSION] [--all-calls] serves a session’s MCP tools on stdio; --all-calls adds the VFS calls and explain. mirage rpc takes the same arguments and serves RPC. mirage ssh-proxy ID carries SSH to workspace ID over the server’s HTTPS port, for ssh’s ProxyCommand. With -w, it serves a workspace the server already holds. Otherwise it creates one from CONFIG, from MIRAGE_MCP_CONFIG (MIRAGE_RPC_CONFIG) or MIRAGE_CONFIG, or from a workspace.yaml found walking up from the working directory. It deletes that workspace when the client disconnects, unless the config names a workspace_id.

Workspaces

Command	Does
`mirage workspace create CONFIG [--id ID]`	Create a workspace from a YAML or JSON config.
`mirage workspace list`	List workspaces.
`mirage workspace get ID [--verbose]`	Show mounts and sessions.
`mirage workspace delete ID`	Close a workspace and delete its state.
`mirage workspace close ID`	Close a workspace and keep its state for the same id.
`mirage workspace cancel ID`	Cancel the running lines of every session.
`mirage workspace kill ID`	Kill the background jobs of every session.
`mirage workspace clone SRC [--id ID]`	Copy a workspace.
`mirage workspace snapshot ID FILE.tar`	Save it to a tar here: the server sends the tar back, on this machine or another.
`mirage workspace snapshot ID --key KEY`	Save it to the server’s snapshot store instead.
`mirage workspace load FILE.tar [CONFIG] [--id ID]`	Restore a tar from here, uploading it. `CONFIG` gives back the credentials the snapshot left out.
`mirage workspace load --key KEY [CONFIG] [--id ID]`	Restore one from the server’s snapshot store.
`mirage workspace vfs-md ID [--session S] [--path PATH] [--profile P]`	Print the VFS.md, or expose it as a live file at `PATH`.
`mirage workspace skill-md ID [--session S] [--path PATH] [--profile P]`	The same for SKILL.md.

Asks

Command	Does
`mirage workspace list-asks ID [--session S] [--all]`	List pending asks.
`mirage workspace allow ID ASK [--scope once\|session]`	Allow one.
`mirage workspace deny ID ASK`	Deny one.

Sessions

Command	Does
`mirage session create ID [--id S] [-p PROFILE] [-m /prefix:mode]...`	Add a session under a profile, with mounts narrowed to `r`, `rw` or `rwx`.
`mirage session list ID`	List sessions.
`mirage session delete ID S`	Close a session.
`mirage session cancel ID S`	Cancel the session’s running lines.
`mirage session kill ID S`	Kill the session’s background jobs.
`mirage session update ID S (-p PROFILE \| --default-profile)`	Replace the session’s profile; its cwd, env and history stay.

Jobs

Command	Does
`mirage job list [-w ID]`	List jobs.
`mirage job get JOB`	Show one job and its result.
`mirage job wait JOB [--timeout SECONDS]`	Wait for a job to finish.
`mirage job cancel JOB`	Cancel a job.

Daemon

The server the CLI starts. It exits 30 seconds after its last workspace is deleted, and logs to ~/.mirage/daemon.log.

Command	Does
`mirage daemon status`	Show PID, uptime and workspace count.
`mirage daemon stop`	Close its workspaces and exit.
`mirage daemon restart [--eager]`	Stop it; the next command, or `--eager`, starts a new one. Workspaces are lost.
`mirage daemon kill`	Kill it. A last resort.

Log in

A server in jwt mode, such as a hosted one, needs a login. Point the CLI at it and log in once:

mirage config set url https://mirage.example.com
mirage login

mirage login asks the server where to sign in, opens your browser there, and waits. If you are already signed in, the browser comes straight back. The CLI then keeps the tokens in ~/.mirage/login.json, readable only by you. A machine with no browser can use mirage login --token TOKEN instead, which keeps a token you paste once the server accepts it; --token - reads it from stdin, so it stays out of your shell history.

Command	Does
`mirage login [--token TOKEN]`	Log in to the server `url` points at.
`mirage whoami`	Show the account and the date to log in again by.
`mirage logout`	Forget the login.

Every command sends the login’s token, ssh-proxy included, but only to the server it was made for. MIRAGE_TOKEN or auth_token wins over it.
The CLI refreshes the token when it ends, and asks you to log in again 30 days after you signed in. A running mcp or rpc relay asks for it on every request, so it keeps working past a refresh.
A server that publishes no login, such as the one the CLI starts on your machine, needs none, and mirage login says so.

Config

mirage config set|get|unset|list edits ~/.mirage/config.toml. An environment variable wins over the file. Changes apply on the next start.

Key	Env var	Default
`url`	`MIRAGE_DAEMON_URL`	`http://127.0.0.1:8765`
`port`	`MIRAGE_DAEMON_PORT`	the `url`’s port
`auth_token`	`MIRAGE_TOKEN`	your login for this `url`, else `~/.mirage/auth_token` for a local `url`
`auth_mode`	`MIRAGE_AUTH_MODE`	`local`
`allowed_hosts`	`MIRAGE_ALLOWED_HOSTS`	`127.0.0.1,localhost,::1`
`idle_grace_seconds`	`MIRAGE_IDLE_GRACE_SECONDS`	`30`
`ssh_*`	`MIRAGE_SSH_*`	see SSH
`jwt_*`	`MIRAGE_JWT_*`	see Auth
`login_client_id`	`MIRAGE_LOGIN_CLIENT_ID`	see CLI login

MIRAGE_HOME moves everything under ~/.mirage.

Getting Started

Access

Policy

Learn

Help

VFS

CLIs

Runtimes

Install

Quickstart

Exit codes

Run lines, VFS calls and tools

`mirage mcp`

Workspaces

Asks

Sessions

Jobs

Daemon

Log in

Config

​Install

​Quickstart

​Exit codes

​Run lines, VFS calls and tools

​mirage mcp

​Workspaces

​Asks

​Sessions

​Jobs

​Daemon

​Log in

​Config

Install

Quickstart

Exit codes

Run lines, VFS calls and tools

`mirage mcp`

Workspaces

Asks

Sessions

Jobs

Daemon

Log in

Config