Skip to main content

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.

​
Overview

Two companion packages to the core SDK:
  • @struktoai/mirage-server, a Fastify daemon that owns workspaces in-process and exposes them over HTTP (/v1/workspaces, /v1/jobs, …).
  • @struktoai/mirage-cli, a commander CLI that speaks to the daemon. Mirrors Python’s mirage CLI 1:1.
The CLI is stateless. Long-running state lives in the daemon; the CLI auto-spawns one on the first mirage workspace create if none is running.

​
Install

npm install -g @struktoai/mirage-cli
This pulls in @struktoai/mirage-server transitively (the CLI spawns the daemon from the server package’s installed bin/daemon.js).

​
Create a workspace

Write a YAML config: 
# config.yaml
mounts:
  /:
    resource: ram
    mode: write
Then: 
mirage workspace create config.yaml
The CLI:
  1. Validates the YAML + interpolates ${VAR} env references (fails fast if any are missing).
  2. Auto-spawns a daemon on 127.0.0.1:8765 if none is reachable.
  3. Sends POST /v1/workspaces and prints the returned detail as JSON.

​
Run commands in a workspace

# synchronous, blocks until the command finishes
mirage execute -w <workspace-id> -c "ls /"

# background, returns a job id immediately; poll/wait later
mirage execute --bg -w <workspace-id> -c "wc -l /large.csv"
mirage job wait <job-id>

​
Workspace lifecycle

CommandPurpose
mirage workspace create <config.yaml>Create; auto-spawns daemon if needed.
mirage workspace listList active workspaces.
mirage workspace get <id> [--verbose]Show one workspace’s detail.
mirage workspace delete <id>Stop and remove.
mirage workspace clone <id> [--id NEW] [--override over.json]Clone; fresh local resources, reused remote ones.
mirage workspace snapshot <id> <out.tar>Snapshot to tar.

​
Sessions

mirage session create <workspace-id> --id agent_a
mirage session list <workspace-id>
mirage session delete <workspace-id> <session-id>

​
Daemon lifecycle

mirage daemon status      # health + PID + uptime
mirage daemon stop        # graceful shutdown (POST /v1/shutdown + SIGTERM fallback)
mirage daemon restart     # stop; next CLI command auto-spawns fresh
mirage daemon kill        # SIGKILL; last resort

​
Configuration

Precedence (highest first):
  1. MIRAGE_DAEMON_URL env var, e.g. http://127.0.0.1:9000.
  2. MIRAGE_TOKEN env var, bearer token passed as Authorization: Bearer <token>.
  3. ~/.mirage/config.toml [daemon] table: 
    [daemon]
url = "http://127.0.0.1:8765"
auth_token = ""
persist_dir = ""
idle_grace_seconds = 30

​
Python parity

The daemon speaks the same /v1/... protocol as Python’s mirage CLI. A Python CLI client can talk to a Node daemon and vice versa. The CLI subcommand tree matches Python’s mirage/cli/*.py file-for-file.

​
Where things live

FilePurpose
packages/server/src/app.tsFastify app factory.
packages/server/src/routers/health / workspaces / sessions / execute / jobs.
packages/server/src/bin/daemon.tsmirage-daemon bin.
packages/cli/src/main.tsCLI program wiring.
packages/cli/src/{workspace,session,execute,provision,job,daemon}.tsPer-subcommand modules.
packages/cli/src/client.tsHTTP client + auto-spawn.