Server & CLI

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:

Validates the YAML + interpolates ${VAR} env references (fails fast if any are missing).
Auto-spawns a daemon on 127.0.0.1:8765 if none is reachable.
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

Command	Purpose
`mirage workspace create <config.yaml>`	Create; auto-spawns daemon if needed.
`mirage workspace list`	List active workspaces.
`mirage workspace get <id> [--verbose]`	Show one workspace’s detail.
`mirage workspace delete <id>`	Stop and remove.
`mirage workspace clone <src> [--id NEW] [--at REF]`	New workspace from the source; `--at REF` clones a past version, else the live state.
`mirage workspace snapshot <id> <out.tar>`	Snapshot to tar.

Versioning

Each workspace has a git-backed history kept by the daemon (under ~/.mirage/repos/<id>; set MIRAGE_VERSION_ROOT to relocate). Same verbs and semantics as the Python CLI.

mirage workspace commit <id> -m "first"            # commit live state
mirage workspace log <id> [-b branch]              # versions, newest first
mirage workspace diff <id> [a] [b]                 # changed paths; no refs = live vs HEAD
mirage workspace branch <id> <name> [--from b]     # fork a branch
mirage workspace checkout <id> <ref>               # restore in place (version id or branch)
mirage workspace clone <src> --at <ref> --id new   # new workspace from a past version

Command	Purpose
`mirage workspace commit <id> [-m MSG] [-b BRANCH]`	Commit the live state as a version.
`mirage workspace log <id> [-b BRANCH]`	List versions on a branch, newest first.
`mirage workspace diff <id> [a] [b] [-b BRANCH]`	Changed paths (added/modified/deleted).
`mirage workspace branch <id> <name> [--from BRANCH]`	Fork a branch at a branch’s current version.
`mirage workspace checkout <id> <ref>`	Restore the live state in place to a version or branch.

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):

MIRAGE_DAEMON_URL env var, e.g. http://127.0.0.1:9000.
MIRAGE_TOKEN env var, bearer token passed as Authorization: Bearer <token>.

~/.mirage/config.toml [daemon] table:

[daemon]
url = "http://127.0.0.1:8765"
auth_token = ""
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

File	Purpose
`packages/server/src/app.ts`	Fastify app factory.
`packages/server/src/routers/`	health / workspaces / sessions / execute / jobs.
`packages/server/src/bin/daemon.ts`	`mirage-daemon` bin.
`packages/cli/src/main.ts`	CLI program wiring.
`packages/cli/src/{workspace,session,execute,provision,job,daemon}.ts`	Per-subcommand modules.
`packages/cli/src/client.ts`	HTTP client + auto-spawn.

Getting Started

Agents

Resources

Overview

Install

Create a workspace

Run commands in a workspace

Workspace lifecycle

Versioning

Sessions

Daemon lifecycle

Configuration

Python parity

Where things live

​Overview

​Install

​Create a workspace

​Run commands in a workspace

​Workspace lifecycle

​Versioning

​Sessions

​Daemon lifecycle

​Configuration

​Python parity

​Where things live

Overview

Install

Create a workspace

Run commands in a workspace

Workspace lifecycle

Versioning

Sessions

Daemon lifecycle

Configuration

Python parity

Where things live