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 grep -w demo -i error /
mirage workspace delete demo

workspace.yaml is a workspace config.

Exit codes

Code	Meaning
`0`	Success.
`1`	A tool command’s tool 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 and tools

-w names the workspace and -s the session, the default one when absent.

Command	Does
`mirage shell -w ID -c LINE [--cwd PATH] [--bg]`	Run a line. Piped stdin streams to it, Ctrl-C cancels it, and `--bg` returns a job id at once.
`mirage read -w ID PATH [--offset N] [--limit N]`	Read a file.
`mirage write -w ID PATH [--content TEXT]`	Write a file, from stdin without `--content`.
`mirage edit -w ID PATH OLD NEW [--replace-all]`	Replace a string in a file.
`mirage ls -w ID PATH`	List a directory.
`mirage grep -w ID PATTERN PATH [-i] [-F] [-l] [-c] [-m N] [-C N] [--include GLOB]`	Search file contents.
`mirage glob -w ID PATTERN [PATH]`	Find paths by pattern.

`mirage mcp`

mirage mcp [CONFIG] [-w ID] [-s SESSION] serves a session’s MCP tools on stdio. mirage rpc takes the same arguments and serves RPC. 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 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.

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.

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.

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`	`~/.mirage/auth_token`, for a local `url` only
`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

MIRAGE_HOME moves everything under ~/.mirage.

Getting Started

Access

Learn

Help

VFS

CLIs

Runtimes

Install

Quickstart

Exit codes

Run lines and tools

`mirage mcp`

Workspaces

Asks

Sessions

Jobs

Daemon

Config

​Install

​Quickstart

​Exit codes

​Run lines and tools

​mirage mcp

​Workspaces

​Asks

​Sessions

​Jobs

​Daemon

​Config

Install

Quickstart

Exit codes

Run lines and tools

`mirage mcp`

Workspaces

Asks

Sessions

Jobs

Daemon

Config