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, workspace create, workspace load, mcp, rpc, ssh-proxy and codex-exec start the server if it is not running; other commands need it running. A remote server is never started.

Install

script
pip
uv
npm

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

Create a RAM-backed workspace that needs no credentials:

cat > workspace.yaml <<'EOF'
mounts:
  /data:
    vfs: ram
    mode: write
EOF

mirage workspace create workspace.yaml --id demo
mirage shell -w demo -c 'echo "hello mirage" > /data/hello.txt && grep -n hello /data/hello.txt'

This prints 1:hello mirage. Keep demo for the MCP or RPC examples, then remove it with mirage workspace delete demo. See Workspace configuration for YAML settings and defaults.

Write a config

A config is a YAML file listing what the workspace mounts. Each key under mounts is a path in the workspace: vfs names the backend, and config holds the fields its VFS guide lists.

workspace.yaml

mode: read
mounts:
  /data:
    vfs: s3
    config:
      bucket: my-bucket
      region: us-east-1
      aws_access_key_id: ${AWS_ACCESS_KEY_ID}
      aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
  /repo:
    vfs: github
    config:
      token: ${GITHUB_TOKEN}
      owner: strukto-ai
      repo: mirage
    command_limits:
      "@all":
        walk_limit: 2000
  /scratch:
    vfs: ram
    mode: write

mode: read makes every mount read-only unless it sets its own mode, as /scratch does.
${NAME} is read from the environment when the config loads, so keys stay out of the file. A missing variable is an error.
command_limits bounds the commands that run on that mount; its "@all" entry’s walk_limit is the most files one command walks there.

mirage workspace create workspace.yaml --id work
mirage shell -w work -c 'ls /repo && echo draft > /scratch/notes.txt'

clis, runtimes, profiles and the other top-level keys are in Workspace configuration.

Exit codes

Code	Means
`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 a streamed `shell` line was canceled.
`141`	`shell` output went to a pipe that closed, as with `\| head`.
`N`	`shell` exits with the line’s own status.

Run lines, VFS calls and tools

Command	Does
`mirage workspace shell -c LINE`	Run a line, streaming its stdout and stderr.
`mirage workspace vfs CALL ARGS`	Make one of the 23 VFS calls.
`mirage workspace tools TOOL ARGS`	Run one of the agent tools.

The workspace is -w, else MIRAGE_WORKSPACE, else the current one that mirage workspace use ID set for the context. With none, the command exits 2. Each takes -s SESSION, the default session when absent. shell and vfs take --explain, which says what the line or call would do and runs nothing; see Explain. mirage shell is a short form of mirage workspace shell, with the same options.

`mirage workspace shell`

Option	Does
`--cwd PATH`	Run the line in this directory.
`--runtime NAME`	Run its programs on this runtime.
`--json`	Print one `{kind, exit_code, stdout, stderr, refusal}` result instead of streaming.

Output streams as raw bytes as it arrives, and piped stdin streams in, so a line can answer before its input ends.
The CLI exits with the line’s code. Ctrl-C cancels the line.
--json decodes stdout and stderr as UTF-8, replacing invalid bytes.

mirage shell -w demo -c 'cat /data/archive.gz' > archive.gz
cat events.txt | mirage shell -w demo -c 'head -n 10'
mirage shell -w demo -c 'ls /data' --json | jq .stdout

`mirage-bash`

mirage-bash -c LINE runs a line as mirage workspace shell, for a coding agent that takes a shell path, such as Claude Code. Both packages install it beside mirage.

Variable	Does
`MIRAGE_WORKSPACE`	The workspace the line runs in. Required.
`MIRAGE_SESSION`	The session it runs as; the default session when unset.

The line runs in the process’s working directory, which must be a path in the workspace.
It takes only -c LINE; other bash options are read and dropped.
It exits with the line’s code, and with 2 when the arguments or MIRAGE_WORKSPACE are missing.

MIRAGE_WORKSPACE=demo mirage-bash -c 'ls /data | wc -l'

`mirage workspace vfs`

Calls are spelled with dashes: mirage workspace vfs is-dir /data -w demo.
Required arguments come in order, the rest as --name VALUE.
Bytes come from --data or --value, else from stdin.
Piped, it prints the call’s JSON. In a terminal, read prints the text and a list prints one entry per line. A call that returns nothing prints nothing.

echo "hello" | mirage workspace vfs write /data/hi.txt -w demo
mirage workspace vfs read /data/hi.txt -w demo

Relays

Command	Does
`mirage mcp [CONFIG] [-w ID] [-s S] [--all-calls]`	Serve a session’s MCP tools on stdio. `--all-calls` adds the VFS calls.
`mirage rpc [CONFIG] [-w ID] [-s S]`	Serve RPC on stdio.
`mirage ssh-proxy ID`	Carry SSH to workspace `ID` over the server’s HTTPS port, for ssh’s `ProxyCommand`.
`mirage codex-exec ID [--listen HOST:PORT]`	Serve workspace `ID` on a local port to `codex exec-server forward`.

With -w, mcp and rpc serve a workspace the server already holds. Without it, they create one from CONFIG, then MIRAGE_MCP_CONFIG (MIRAGE_RPC_CONFIG) or MIRAGE_CONFIG, then a workspace.yaml found walking up from the working directory. They delete it when the client disconnects, unless the config names a workspace_id.

Workspaces

Command	Does
`mirage workspace create CONFIG [-w ID]`	Create a workspace from a YAML or JSON config. `--id` is another name for `-w`.
`mirage workspace create --template NAME [-w ID]`	Create a workspace from a saved template.
`mirage workspace create CONFIG --explain`	Show what the server policies say of the config, and create nothing.
`mirage workspace list`	List workspaces.
`mirage workspace use ID`	Make it the current workspace of the context.
`mirage workspace get ID [--verbose]`	Show mounts and sessions.
`mirage workspace delete ID`	Stop a workspace and delete its state.
`mirage workspace stop ID`	Stop a workspace and keep its state and config. Stopping a stopped workspace does nothing.
`mirage workspace start ID`	Start a stopped workspace again from the config it was created with. Starting a running workspace does nothing.
`mirage workspace set-profile ID NAME FILE`	Add a profile from a YAML or JSON file, or replace what `NAME` means. Sessions keep their rules until `session update` moves them, and the workspace’s config is not rewritten.
`mirage workspace history ID [--session S] [--since MS] [--last N] [--vfs]`	Show what it ran, oldest first: each line as it started and how it ended; `--vfs` adds each call a line made to a mount.
`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.

From a template

A template is a saved workspace config. -f takes a workspace config, or a file with name, an optional description, and config, as mirage template get ID -o yaml prints one:

mirage template create ram-only -f workspace.yaml --description "One RAM mount"
mirage workspace create --template ram-only -w demo

Command	Does
`mirage template create NAME -f FILE [--description TEXT]`	Save a config as a template.
`mirage template list`	List templates.
`mirage template get ID [-o yaml]`	Print one; `-o yaml` is a file `create -f` reads back.
`mirage template delete ID`	Delete one.
`mirage template restore ID`	Bring a deleted one back.

The file is saved as written: ${NAME} is not read from the environment. The server checks the config when it saves the template, as a create would. A workspace gets a copy of the template’s config, so a later change to the template leaves it as it is, and a template’s config cannot set workspace_id: -w names the workspace. Give a config file or --template, not both. The local daemon keeps templates under ~/.mirage/resources, as resource_store sets. get, delete and restore take the template’s ID or its name: a name is unique, so it works as an ID. On the local daemon a template’s ID is its name.

Saved policies

mirage policy keeps Python programs by name on the daemon, or on the hosted API, through the /v1/policies routes. A name ends in .py. --source @FILE reads a file; any other value is the program itself. get, update and delete take the policy’s ID or its name, which works as an ID; on the local daemon the two are the same.

Command	Does
`mirage policy create NAME --source @FILE\|TEXT`	Save a new policy. A name already saved exits 2.
`mirage policy list`	List the saved names.
`mirage policy get ID [-o yaml]`	Show one; in a terminal, its source.
`mirage policy update ID --source @FILE\|TEXT`	Replace its source.
`mirage policy delete ID`	Delete it.

mirage policy create guard.py --source @guard.py
mirage policy get guard.py -o yaml

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.

Saved connections

mirage vfs, mirage cli and mirage runtime keep connections on the server: a type, its settings and its credentials, saved once under a name. They are the /v1/vfs, /v1/clis and /v1/runtimes routes, and work the same against the local daemon and the hosted API. ID is an entry’s ID or its name: a name is unique, so it works as an ID. On the local daemon an entry’s ID is its name.

Command	Does
`mirage vfs types [TYPE]`	List the types, with their required and secret fields; with `TYPE`, its fields.
`mirage vfs create NAME --type TYPE [--set K=V] [--secret K] [-f FILE]`	Save a new entry.
`mirage vfs list [--type TYPE] [-q TEXT]`	List the entries, by name, with how many saved templates use each.
`mirage vfs get ID [-o yaml]`	Show an entry. A secret field shows as `(sealed)`, never its value.
`mirage vfs update ID [--set K=V] [--secret K] [--unset K] [-f FILE]`	Change an entry. Fields not named keep their values.
`mirage vfs delete ID`	Delete an entry and wipe its secrets. There is no restore.

mirage cli and mirage runtime take the same commands.

mirage vfs types github
mirage vfs create github --type github --set owner=strukto-ai --set repo=mirage --secret token
Token for github: ********
mirage vfs get github
mirage vfs update github --secret token
mirage vfs delete github

--set KEY=VALUE sets a plain field and can be repeated. A value that starts with { or [ is read as JSON.
--secret KEY reads a secret field from a hidden prompt, or from the next line of stdin when stdin is not a terminal. --secret KEY=@FILE reads a file, without its last newline. A secret value on the command line is refused, by --secret KEY=VALUE and by --set alike.
--unset KEY removes a field, plain or secret.
-f FILE reads the entry from YAML or JSON: name, type, fields, and secrets, a list of the secret fields to read as --secret reads them. The output of get -o yaml reads back too.
In a terminal, a missing required field is prompted for. Otherwise the command exits 2 and names every missing field.
Piped, every command prints JSON. -o yaml on get prints a file that create -f and update -f read back.

github.yaml

name: github
type: github
fields:
  owner: strukto-ai
  repo: mirage
secrets: [token]

mirage vfs create -f github.yaml < token.txt

update keeps a secret field you leave out, so --secret token rotates a token while the entry stays in use. delete is refused while a saved template uses the entry. The local daemon keeps entries under ~/.mirage/resources, their secrets in a separate file only you can read.

Sessions

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

Each takes -w ID, else the current workspace, as shell and vfs do.

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 context is a server the CLI talks to, with its login, team and current workspace. local is the daemon on this machine, which needs no login and is always there. mirage login adds a context and makes it current:

mirage login                                   # the hosted API, context "strukto"
mirage login https://mirage.example.com        # context "mirage.example.com"
mirage login https://dev.example.com --name dev
mirage context use local

Command	Does
`mirage login [URL] [--name NAME] [--token TOKEN]`	Log in to `URL`, `https://api.strukto.ai` when left out, and make its context current. The context is `--name`, else `strukto` for the hosted API, `local` for this machine, else the server’s host.
`mirage context list`	List the contexts; `*` marks the current one.
`mirage context use NAME`	Make a context current.
`mirage context delete NAME`	Forget a context and its login. `local` stays.
`mirage whoami`	Show the context, its URL, team, user and workspace, and the date to log in again by.
`mirage logout`	Forget the current context’s login; the context stays.

--context NAME before a command, or MIRAGE_CONTEXT=NAME, runs one command in another context. MIRAGE_DAEMON_URL points any context at another URL. On a terminal, a command that changes something names its context first, as strukto · team acme · created demo.

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 keeps each context in ~/.mirage/contexts/NAME.json, its tokens in ~/.mirage/logins/NAME.json, and the current context’s name in ~/.mirage/current_context, all readable only by you.
On a machine with no browser, mirage login --token TOKEN keeps a token you paste once the server accepts it. --token - reads it from stdin, so it stays out of your shell history.
Every command sends the login’s token, ssh-proxy and codex-exec included, but only to the server it was made for. MIRAGE_TOKEN wins over it, and so does auth_token in the local context.
The token refreshes on its own; you log in again 30 days after you signed in.
A server that publishes no login, such as the one the CLI starts on your machine, needs none, and mirage login says so.

A server publishes a login when it runs in jwt mode with an issuer and MIRAGE_LOGIN_CLIENT_ID set to an OAuth client that MIRAGE_JWT_AUDIENCE lists:

export MIRAGE_JWT_ISSUER=https://clerk.example.com
export MIRAGE_JWT_AUDIENCE=client_cli
export MIRAGE_LOGIN_CLIENT_ID=client_cli

mirage login then reads the issuer and client from the server’s /.well-known/oauth-protected-resource, signs in through the browser, and exchanges the code for tokens with PKCE.In Clerk, create an OAuth application with no client secret and PKCE enabled. Add the redirect http://127.0.0.1/callback (the CLI picks a free port), allow the offline_access scope for a refresh token, and turn the consent screen off so a signed-in user comes straight back to the CLI.

Call any route

mirage api calls a route of the current context’s server with the CLI’s login or token, as gh api does, so a script needs no token of its own:

mirage api /v1/workspaces
mirage api /v1/workspaces/demo/shell --command 'ls /data | wc -l'
mirage api /v1/workspaces/demo/clone --id demo-2 \
  --override '{"mounts": {"/data": {"vfs": "ram"}}}'
mirage api /v1/workspaces --input workspace.json
mirage api /v1/workspaces/demo -X DELETE

Every option after the route is a field, except these:

Flag	Does
`--input FILE`	The body, from a YAML or JSON file; `-` reads stdin.
`-X METHOD`	The method: GET, or POST once there are fields or `--input`.

A field is --key value or --key=value. A value that starts with { or [ is JSON, @FILE is the file’s text (@- reads stdin), anything else is a string, and a bare --flag is true. Fields make a JSON body, or the query string of a GET. The answer prints as JSON, a 204 prints nothing, and an error exits 2 with its detail. api takes only a route, never a URL, so the token goes nowhere but its own server.

Daemon config

mirage daemon 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
`port`	`MIRAGE_DAEMON_PORT`	`8765`; the `local` context follows it
`url`	`MIRAGE_DAEMON_URL`	`http://127.0.0.1:PORT`: the `local` context’s URL; `mirage login URL` adds another server
`auth_token`	`MIRAGE_TOKEN`	your login for the `local` context, else `~/.mirage/auth_token`
`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`
`max_workspaces`	`MIRAGE_MAX_WORKSPACES`	no cap; past it a new workspace answers 503
`max_sessions`	`MIRAGE_MAX_SESSIONS`	`16`; past it a new session answers 429
`max_memory`	`MIRAGE_MAX_MEMORY`	none; the most any workspace’s `max_memory` reaches, as a size
`max_processes`	`MIRAGE_MAX_PROCESSES`	none; the most any session’s `processes.max` reaches
`max_line_seconds`	`MIRAGE_MAX_LINE_SECONDS`	none; the most seconds any line runs
`max_env`	`MIRAGE_MAX_ENV`	none; the most any workspace’s `max_env` reaches, as a size
`workers`	`MIRAGE_WORKERS`	`1`; see Workers
`worker_type`	`MIRAGE_WORKER_TYPE`	`thread` in TypeScript; in Python, `thread` without the GIL, else `process`
`rate_limits`	`MIRAGE_RATE_LIMITS`	`ip=1000/minute`; see Rate limits
`forwarded_allow_ips`	`MIRAGE_FORWARDED_ALLOW_IPS`	none; the proxies whose `X-Forwarded-For` names the client
`graceful_timeout`	`MIRAGE_GRACEFUL_TIMEOUT`	`0`; seconds running lines get to finish on shutdown
`policy_file`	`MIRAGE_POLICY_FILE`	none; see Server policies
`resource_store`	`MIRAGE_RESOURCE_STORE`	`files`, under `~/.mirage/resources`; `memory` keeps saved templates and connections only until the daemon stops, and does not combine with `workers`
`ssh_*`	`MIRAGE_SSH_*`	see SSH
`jwt_*`	`MIRAGE_JWT_*`	see Configure authentication
`login_client_id`	`MIRAGE_LOGIN_CLIENT_ID`	see Log in

MIRAGE_HOME moves everything under ~/.mirage.

Getting Started

Examples

Agents

VFS

Integration

CLIs

Mirage Shell

Agent Profiles

Policy

Runtimes

Infrastructure

Configuration

Notifications

Help

Install

Quickstart

Write a config

Exit codes

Run lines, VFS calls and tools

`mirage workspace shell`

`mirage-bash`

`mirage workspace vfs`

Relays

Workspaces

From a template

Saved policies

Asks

Saved connections

Sessions

Daemon

Log in

Call any route

Daemon config

​Install

​Quickstart

​Write a config

​Exit codes

​Run lines, VFS calls and tools

​mirage workspace shell

​mirage-bash

​mirage workspace vfs

​Relays

​Workspaces

​From a template

​Saved policies

​Asks

​Saved connections

​Sessions

​Daemon

​Log in

​Call any route

​Daemon config

Install

Quickstart

Write a config

Exit codes

Run lines, VFS calls and tools

`mirage workspace shell`

`mirage-bash`

`mirage workspace vfs`

Relays

Workspaces

From a template

Saved policies

Asks

Saved connections

Sessions

Daemon

Log in

Call any route

Daemon config